MIDI Bridge

The MIDI Bridge is a small helper tool bundled with the Now Playing desktop app that captures MIDI messages from all connected DJ controllers at once. Its output feeds the mix processor, so that fader positions, EQ knobs, crossfader, and play buttons can be evaluated for on-air detection.

Why a Separate Bridge?

DJ controllers and mixers typically expose themselves as MIDI devices so that DJ software (Rekordbox, Serato, Traktor) can read their state. On macOS, however, MIDI devices are normally locked to a single listening application unless they are set up as multi-client. The MIDI Bridge uses CoreMIDI’s multi-client architecture on macOS to listen to every controller in parallel, without blocking the DJ software from doing the same.

Running the bridge as a separate binary also isolates low-level MIDI handling from the Electron main process, which reduces the chance of MIDI issues affecting the rest of the app.

How It Works

1. The desktop app spawns the MIDI Bridge as a child process.
2. The bridge scans for connected MIDI devices and opens them in multi-client listen mode.
3. As MIDI messages arrive, the bridge emits a line of JSON on stdout per message.
4. The desktop app reads stdout line-by-line, decodes each JSON event, and translates it into controller state using the mapping for the detected device.
5. The translated state is sent to the cloud over Socket.IO, where the mix processor picks it up.

What MIDI Messages Are Captured

Message	Used For
Control Change (CC)	Faders, EQ knobs, crossfader, filter, jog wheels
Note On / Note Off	Play, cue, pad, loop buttons
Pitch Bend	Tempo fader position on some controllers

Every captured event includes the device name, channel number, CC or note number, value, and timestamp.

Controller Mappings

The MIDI Bridge does not know which knob is “channel 1 fader” vs “channel 2 EQ low” — that depends on the controller. Now Playing ships with 98 controller mappings covering the major brands:

• Pioneer DJ — 61 controllers, including the DDJ-FLX and DDJ-REV lines.
• Hercules — 14 controllers.
• Numark — 7 controllers.
• Denon DJ — 6 controllers.
• Behringer — 5 controllers.
• Others — Roland, Reloop, Native Instruments, and more.

Mappings are auto-generated from the MIDI implementation charts published by the manufacturers for Rekordbox, and converted into a Now Playing-specific mapping format. When a new device is connected, it is matched against the mapping database and its state is normalised into the signal format the mix processor expects (0–1 linear signals or -1 to 1 bipolar signals).

Platform Support

• macOS — fully supported. Implemented as a Swift CLI using CoreMIDI, bundled inside the desktop app.
• Windows — planned. Waiting on Windows MIDI Services (the new MIDI 2.0 API) to reach general availability.

Where It Sits in the Pipeline

Controller
    │
    │ MIDI (USB / Bluetooth)
    ▼
MIDI Bridge (CLI)
    │
    │ JSON on stdout
    ▼
Desktop app
    │
    │ Socket.IO event: controllerState
    ▼
Cloud (mix-processor-service)
    │
    │ Scoring
    ▼
On-air track → Overlay

Without the MIDI Bridge, the mix processor only has track metadata to work with — enough for software-only setups (BYPASS strategy), but not enough for multi-deck on-air detection during transitions.