PCHI 2.0
Protocol documentation.

Why PCHI?#

Live shows can involve 10+ tools—Resolume, TouchDesigner, Ableton, lighting consoles, and tracking systems—connected through dozens of custom OSC mappings. Scene coherence is maintained by convention. When something breaks, it can be difficult to know which state is valid.

PCHI standardizes the “letter”—the message schema—while remaining transport-agnostic. It adds explicit mathematical checks, so state verification becomes part of the protocol rather than an assumption.

PIR Invariants#

Every PCHI message carries invariant data describing its mathematical state. Before a change is applied, the Conductor checks these values against its configured validation criteria.

01 Equilibrium check

Uses the Prouhet–Thue–Morse sign sequence to test mathematical balance through a computed residual.

02 Coherence gap

Measures deviation from the mean to help detect state drift.

03 Curvature signature

Approximates second-derivative behavior to describe smoothness during transitions.

{
  "pirInvariants": {
    "equilibriumCheck": {
      "residual": 0.000000000001,
      "precision": 1e-12,
      "signSequence": [1, -1, -1, 1]
    },
    "coherenceGap": 0.0234,
    "curvatureSignature": "0.001234, -0.000567, 0.000890",
    "residual": 0.000000000001
  }
}

Only-Lang Governance#

Generative agents can introduce unexpected changes into a live environment. Only-Lang rules define explicit boundaries for those behaviors, allowing the Conductor to clamp or reject a proposed update before it reaches receivers.

if kraken_tentacle.wobbliness > 0.8
then
    kraken_tentacle.wobbliness = 0.8
end

Here, the maximum permitted wobbliness is 0.8. Suggestions within that boundary can pass; values outside it are constrained by the rule.

Software governance is one layer of protection—not a substitute for show-specific safety limits, hardware interlocks, or operator oversight.

Message Schema#

A common message format carries object state, control parameters, musical context, and tracking data. JSON keeps messages readable; FlatBuffers supports high-performance binary serialization.

The overview example uses a state_update envelope. Check the repository’s versioned schema for the exact message types and fields your implementation supports.

Meet the Conductor#

The PrimeSwarm Engine acts as the PCHI Conductor: a central Rust-based server that receives proposed changes, verifies them, and distributes a coherent state to connected tools.

1. 01ReceiveIncoming state
2. 02VerifyPIR invariants
3. 03GovernOnly-Lang rules
4. 04BroadcastVerified updates

Start with the source

Install Git and the Rust toolchain, then clone the repository. Consult its README for current prerequisites and configuration.

// Check the repository for current imports and API signatures.
#[tokio::main]
async fn main() {
    let conductor = PCHIConductor::new(1e-12);
    conductor.start_transport("0.0.0.0:8888").await.unwrap();
    conductor.load_rules("kraken-rules.only").await.unwrap();
    tokio::signal::ctrl_c().await.unwrap();
}

Integration Patterns#

Start by identifying which role a tool plays. A creative system may send updates, receive validated state, or do both.

The bridge listens for OSC messages from Resolume Arena, calculates invariant data, converts messages into the PCHI format, and forwards them to the Conductor.

pip install python-osc numpy
python resolume_pchi_bridge.py \
    --resolume-port 7000 \
    --pchi-host 127.0.0.1 \
    --pchi-port 8888 \
    --threshold 1e-12

From OSC to shared state

An OSC address such as /composition/layers/{layer_id}/video/opacity maps to a PCHI control_parameter targeting that layer.

A Python CHOP connects to the Conductor over UDP and creates channels from incoming scene objects, musical context, and invariant status.

Export the appropriate channels to a Geometry COMP’s transform parameters to drive your objects from the shared scene state.

A Max for Live device monitors Ableton’s musical state, including BPM and clip changes. It calculates PIR invariant data from the musical state and emits a musical_context payload.

Pitch values can be mapped to Prouhet–Thue–Morse sequences for equilibrium calculations. Match the device’s transport and destination to your Conductor before sending.