# Visual Buddy Bridge

A single Python file that turns Traktor's existing outputs into a JSON
WebSocket feed for the Visual Buddy renderer.

```
Traktor Broadcasting ──▶ port 8000 ─┐
Traktor MIDI Clock   ──▶ IAC/loopMIDI ─┤──▶ vbuddy_bridge.py ──▶ ws://<host>:8765
```

## 1. Install

```bash
pip install -r requirements.txt
```

`python-rtmidi` needs a compiler on some systems. On macOS:
`xcode-select --install`. On Windows, install the Visual C++ Build Tools or
use a prebuilt wheel.

## 2. Create a virtual MIDI port

**macOS** — open *Audio MIDI Setup* → *Window* → *Show MIDI Studio* →
double-click **IAC Driver** → tick *Device is online*. Bus 1 is enough.

**Windows** — install [loopMIDI](https://www.tobias-erichsen.de/software/loopmidi.html)
and create a port named e.g. `loopMIDI Port`.

## 3. Traktor: send MIDI clock

*Preferences → Controller Manager*

1. **Add… → Generic MIDI**
2. Out-Port: your IAC / loopMIDI port
3. *Preferences → MIDI Clock* → enable **Send MIDI Clock**
4. Start the clock from the master clock panel in Traktor (the metronome icon)

## 4. Traktor: send hotcues (optional)

Still in *Controller Manager*, with your Generic MIDI device selected:

1. **Add Out… → Track Deck → Hotcue 1 State** (repeat for 1–8)
2. Assign Deck A hotcues to notes **C1–G1** (MIDI notes 36–43)
3. Assign Deck B hotcues to notes **G#1–D#2** (MIDI notes 44–51)

The bridge's `--cue-base` defaults to note 36 for Deck A hotcue 1. Change it
if you map different notes.

## 5. Traktor: broadcast metadata

*Preferences → Broadcasting*

| Field    | Value       |
| -------- | ----------- |
| Address  | `127.0.0.1` |
| Port     | `8000`      |
| Mount    | `/live`     |
| Password | anything    |
| Format   | Ogg Vorbis, lowest bitrate is fine |

Then activate broadcasting from the deck's REC/broadcast button. Traktor only
sends track metadata while broadcasting is live.

## 6. Run it

```bash
python vbuddy_bridge.py --list-midi
python vbuddy_bridge.py --midi "IAC Driver Bus 1"
```

Open the Visual Buddy renderer and connect to `ws://localhost:8765`.

## Remote rendering

Run the bridge on your DJ laptop and the renderer on another machine on the
same network. The bridge binds `0.0.0.0` by default, so on the render machine
just connect to `ws://<dj-laptop-ip>:8765`.

Find the IP with `ipconfig getifaddr en0` (macOS) or `ipconfig` (Windows).

## Forward to Resolume / VDMX instead

```bash
python vbuddy_bridge.py --midi "IAC Driver Bus 1" --osc 127.0.0.1:7000
```

OSC addresses: `/vbuddy/bpm`, `/vbuddy/beat`, `/vbuddy/playing`,
`/vbuddy/track`, `/vbuddy/cue`.

## Message format

```json
{"type":"hello","app":"vbuddy-bridge","version":"0.1.0"}
{"type":"track","deck":"A","artist":"Overmono","title":"So U Kno","filename":"Overmono - So U Kno"}
{"type":"clock","bpm":130.02,"beat":2,"bar":41,"playing":true}
{"type":"cue","deck":"A","index":3,"note":38,"channel":0}
{"type":"transport","playing":false}
```

## Troubleshooting

| Symptom | Fix |
| --- | --- |
| No MIDI ports listed | Enable IAC Driver / create a loopMIDI port, then restart the script |
| BPM stays 0 | Traktor's master clock isn't running — press play on the clock |
| No track names | Broadcasting isn't active, or the port doesn't match `--meta-port` |
| Cues do nothing | Check `--cue-base` matches the notes you mapped in Controller Manager |
| Renderer can't connect remotely | Allow port 8765 through the DJ laptop's firewall |