Installing

Installing

You need Ableton Live 12 with Max for Live. Built and tested against 12.4.3 Suite.

Get the device

Download the latest zip from Releases and unzip it somewhere permanent — not a Downloads folder you clear out.

Inside are three files:

SessionBridge.amxd    the device
bridge.js             the server, with the whole UI baked into it
lom.js                the half that talks to Live

Keep all three together. The device loads the other two by name from beside itself. Move the folder, not the .amxd.

Get the apps

The device bridges Live and nothing else. Every interface is an app of its own, and each one is a separate .dmg on the same release:

set[flow]	the session manager — the grid, naming, roles, color and the running order
visual[flow]	the VJ rig — an Ableton Link peer that renders the set from a node graph

Open the .dmg and drag the app to Applications. Both are signed with a Developer ID and notarised by Apple, so they open with a double-click — no right-click, and nothing to approve in System Settings. If macOS says an app is damaged, you have a build from somewhere other than a release; delete it and take the one from Releases.

Apple silicon only. There is no Intel build.

chart[flow], the page the band reads off a phone, has no app yet — it runs from a clone of the repository.

Load it

1. Drag SessionBridge.amxd onto any track. It's an audio effect with a straight passthrough, so it's inert on the signal path — the Master track is a fine home.
2. Wait for the device's Status to read Connected to Live.
3. Open set[flow], the session manager. It finds the device by itself, and set[flow] appears on the device's face with its dot lit.

The set loads by itself — you don't have to ask for it. The snapshot starts as soon as the device reports it's ready to talk to Live.

The face

Status is about Live, and it settles within a moment of the device loading.

it says	it means
Starting…	the patcher loaded, Node hasn't booted yet
Waiting for Live	the server is listening, but Live isn't answering yet
Connected to Live	running — the resting state, whether or not an app is attached

Under it, a row for each app that has connected — set[flow], visual[flow], chart[flow], master[flow], or anything newer — in the order each first connected, with a dot in that app's own colour. An app that tells the device its version shows it beside its name. The dot is lit while that app is connected — so if the grid has gone quiet, the device tells you at a glance whether the app is still on the other end.

Closing an app dims its row rather than removing it. The name greys out and the dot goes dark, but the row stays where it was and the ones below don't move up, so an app is always where you last saw it. Open the app again and its row lights back up. The rows reset only when the device reloads.

One app is one row however many connections it has — chart[flow] gets one dot however many phones are reading it.

There are four rows. A fifth app takes the place of one that has closed; if all four are still connected, it is counted in the line below instead.

plus 1 more appears under the rows when something on the socket has no lit row: an app past the fourth, or a browser you left pointed at the device. It's worth chasing — an old window on another desktop is still connected, and still reading and writing the same set.

GitHub opens the project page in your browser. There is nothing else on the face, and that is the whole of what the device does: it bridges Live, and the windows that show you a set are apps of their own.

Stuck on either of the first two? Options ▸ Max ▸ Open Max Window. Every error and every timing line lands there. More in Troubleshooting.

What it does and doesn't touch

Nothing you make is stored in the device folder, so replacing it on an update costs you nothing:

• Your default artist, role definitions and chosen colors are stored in the device itself, in a hidden parameter — which means Live writes them into the .als. Save, Save As, presets and moving the set to another machine all carry them, with no sidecar file to lose. An older bsv.json or roles.json is imported once, the first time a device with nothing in it loads.
• The color palette is Live's own 70 colors, compiled into the app. Nothing to derive, nothing to cache.
• Everything else — names, keys, tags, colors, roles — lives in the set itself. Roles and song tags are written into scene names, which is why they survive a restart and show up in Live.

Only the column width and the fold state are per-machine view settings, and neither is worth carrying anywhere.

The server binds 127.0.0.1 only, and nothing is downloaded at runtime. This is built to work on stage with no network.

One device per set. Two copies would fight over port 17800; a second instance posts a warning rather than crashing. (master[flow]'s small measuring device, the probe, is a different device and you can load as many as you like — see master[flow].)

After an update

Live usually reloads the device on its own. If behaviour looks stale, delete it from the track and drag it back on.

Building from source

The apps use the shared Desktop package from a pinned Git commit. Run npm ci in the app repository with Node 26 or newer; npm installs and builds that dependency automatically. There is no separate Desktop folder to copy into the app repository and no npm registry release to wait for. Packaged apps include the shared code and continue to run without fetching it.