Signal Bridge

starfish-bridge proxies external signal protocols — MIDI, OSC, MQTT, DMX/Art-Net, Serial — in and out of Starfish topics. Run it on-site next to your hardware to ingest external signals into a session, drive external endpoints from a session, or bridge both ways at once. It ships as a single self-contained binary, so there's no runtime to install.

The bridge lets non-browser sources take part in a Starfish session as first-class peers: a MIDI controller can publish to a topic, an Art-Net fixture can be driven from one, and a subscriber sees the same frames whether they came from a phone or a stage rig.

The command shape

Every invocation is a connector followed by a required direction:

starfish-bridge <connector> <in|out|both> --server <url> --session <name> --topic <topic> [connector flags]

The two-level positional shape mirrors kubectl config use-context and aws s3 cp. Direction has no default — you always state it explicitly.

# Ingest MIDI note events into the `notes` topic
starfish-bridge midi in  --server ws://localhost:8080/starfish --session show --topic notes

# Drive an Art-Net fixture from the `lights` topic
starfish-bridge artnet out --server ws://localhost:8080/starfish --session show --topic lights

# Bridge an OSC endpoint both ways
starfish-bridge osc both --server ws://localhost:8080/starfish --session show --topic control

Direction convention

Direction is always relative to Starfish:

direction	Data flow	Meaning
in	external endpoint → Starfish topic	ingest external signals
out	Starfish topic → external endpoint	drive external endpoints
both	external ↔ Starfish	bidirectional bridge

in runs the publish path, out runs the subscribe path, both runs both.

Connectors

Connector	What it bridges
MIDI	A hardware MIDI device — notes, CC, pitch bend, and more as structured JSON
OSC	Open Sound Control over UDP, with per-direction listen/send configuration
MQTT	An MQTT broker's topics (planned)
DMX/Art-Net	Lighting fixtures over Art-Net (planned)
Serial	A serial port device (planned)

Each connector self-registers, so the set grows without changes to the core CLI.

Full reference

The bridge's README is the single source of truth for the exhaustive per-connector reference — common flags, payload schemas, source identification via presence, and how to add a connector.