Repository navigation
Description
Problem Statement
I DJ with Untitled Audio Syndicate and a Denon LC6000 PRIME, on a Mac. The current bridge is a Python command-line program:
- Hard to install and run. It needs Python, a venv, pip and a terminal window that stays open through the set. Other DJs won't do that.
- Hard to ship. No signed app, no App Store, no updates.
- Not native. Python checks for MIDI every millisecond instead of reacting when a message arrives. It has no idea when the controller is plugged in or pulled.
- The v0.2 gaps are still open. Only one controller gets LEDs. The pitch fader jumps. A bumped cable or a Syndicate restart leaves controls stuck and LEDs stale. LEDs show state, not timing. Mapping mistakes fail silently.
Solution
A native macOS menu-bar app, written in Swift and sold through the Mac App Store. It does everything the Python bridge does, plus the v0.2 features:
- A menu-bar icon that shows status: controller connected, Syndicate feedback live, or a problem. The menu holds the deck picker, the controller list, OSC settings and diagnostics. There is no Dock icon.
- Same translation as the Python bridge: LC6000 MIDI turns into Syndicate OSC, and Syndicate's OSC feedback drives the LEDs.
- Native MIDI. CoreMIDI delivers messages as they arrive and tells the app when devices come and go, so unplugging and replugging just work.
- The v0.2 features:
- more than one controller in one app
- pitch pickup
- recovery from a disconnect or a Syndicate restart
- timing LEDs
- a checked mapping
- Diagnostics in the app: a MIDI monitor and an LED sweep replace the Python
monitorandled-sweepcommands, so the PROVISIONAL mapping values can be checked without Python. - The Python bridge stays in the repo until the app matches it. Then it is removed.
User Stories
Install and run
- As a DJ, I want to install the bridge from the Mac App Store, so that I don't need Python or a terminal.
- As a DJ, I want the bridge to live in the menu bar with no Dock icon, so that it stays out of the way during a set.
- As a DJ, I want the menu-bar icon to show whether the controller is connected and Syndicate feedback is live, so that I can check at a glance.
- As a DJ, I want an option to start the bridge at login, so that it is ready when I open Syndicate.
- As a DJ, I want the app to remember my settings between launches, so that I set it up once.
- As a DJ, I want a short first-run guide covering the Syndicate settings (OSC input on, feedback to 127.0.0.1:9096, subscriptions ticked, LC6000 MIDI input off), so that I can set up Syndicate without reading a README.
- As a DJ, I want the app to tell me clearly if port 9096 is already in use, so that I know why there are no LEDs.
- As a DJ, I want to quit the app from its menu, and have every held control released first, so that nothing is left stuck in Syndicate.
Translation (parity with the Python bridge)
- As a DJ, I want the pitch fader to use all 14 bits, sent as a float tempo slider, so that I get fine tempo control.
- As a DJ, I want the jog to nudge (phase bend) while playing and seek while paused, falling back to beat skip without a track length, so that it behaves as it does now.
- As a DJ, I want the nudge released 80 ms after the wheel stops, so that a nudge never sticks.
- As a DJ, I want the Needle Drop strip to seek while touched, so that I can jump around a track.
- As a DJ, I want Play, Cue (hold), Sync, Master, Loop In, Loop Out, Auto Loop, beat jump (Shift for bar jump), Censor (reverse hold), Key Lock, Slip, Pitch ± (Shift to reset), Param ◀ ▶ and the browse controls to send the same OSC as the Python bridge, so that nothing changes in my hands.
- As a DJ, I want the pads in Hot Cue, Roll and Loop modes to behave as they do now, and a held pad to be released when I switch modes, so that nothing sticks.
- As a DJ, I want the auto loop knob to halve and double the loop, so that I can resize loops by feel.
LEDs (parity)
- As a DJ, I want Play, Cue, Sync and Master to follow Syndicate's state, so that the controller shows what the deck is doing.
- As a DJ, I want Key Lock, Slip, Shift and the pad-mode buttons to show the bridge's own state, so that I can see what mode I'm in.
- As a DJ, I want the pads to show my hot cues in Syndicate's cue colors, quantized to the LC6000's color table, so that I can find cues by color.
- As a DJ, I want the platter ring lit when a track is loaded, so that I can see which deck has a track.
Settings
- As a DJ, I want to pick the Syndicate deck (1–4) for each controller from the menu, so that I can switch decks without editing files.
- As a DJ, I want to pick the controller's MIDI input and output from a list of connected devices, so that I don't type port names.
- As a DJ, I want to set the Syndicate host and port, and the feedback port, so that the bridge can work with Syndicate on another Mac.
- As a DJ, I want an option to turn LEDs off, so that I can run without feedback.
- As a DJ, I want to import a mapping file that overrides the default mapping, so that I can fix a PROVISIONAL value for my unit without a new app build.
- As a DJ, I want to export the current mapping as a file, so that I have a starting point to edit.
- As a DJ, I want a reset-to-default option, so that a bad import is easy to undo.
Multiple controllers
- As a DJ with two LC6000s, I want one app to drive both, each on its own deck, so that both get LEDs from Syndicate's single feedback destination.
- As a DJ, I want to tell two identical LC6000s apart, by device or by MIDI channel, so that two units with the same name don't get mixed up.
- As a DJ, I want feedback for one deck never to change the LEDs of a controller on another deck, so that each controller shows only its own deck.
- As a DJ, I want either controller's browse and load controls to work at any time, so that either one can load tracks.
Pitch pickup
- As a DJ, I want the pitch fader to do nothing after a track load until it crosses the deck's current tempo-slider position, so that the tempo doesn't jump.
- As a DJ, I want pickup to re-arm whenever Syndicate reports a tempo-slider change I didn't make (sync, a mouse edit, another controller), so that the physical fader never fights the on-screen one.
- As a DJ, I want the pitch center LED to show that the fader isn't picked up yet, so that I can catch the value by feel.
- As a DJ, I want pickup to be optional, so that I can turn it off if I prefer jumps.
- As a DJ, I want the fader ignored while Syndicate reports the slider disabled, so that moving it doesn't queue up a jump.
Recovery
- As a DJ, I want every held control (nudge, cue, hot cue, roll, reverse) released the moment the LC6000 is unplugged, so that nothing stays stuck in Syndicate.
- As a DJ, I want the app to pick the LC6000 up again by itself when it is plugged back in, so that a bumped cable doesn't end my set.
- As a DJ, I want the app to start fine with no LC6000 plugged in and connect when one appears, so that the order I plug things in doesn't matter.
- As a DJ, I want every LED repainted when the controller reconnects, so that its lights match Syndicate straight away.
- As a DJ, I want the bridge to ask Syndicate to resend its state when feedback resumes after a silence, so that a Syndicate restart doesn't leave the LEDs stale.
- As a DJ, I want deck state cleared once feedback has been silent for a long time, so that the LEDs don't show a track that's gone.
- As a DJ, I want the menu to show the last disconnect, reconnect or feedback dropout, so that I know what happened.
- As a DJ, I want the bridge to release held controls if my Mac goes to sleep, and to reconnect when it wakes, so that sleep doesn't leave anything stuck.
Timing LEDs
- As a DJ, I want the Play LED to blink while a quantized start is pending, so that I can see the deck is about to start.
- As a DJ, I want a held hot-cue pad at full brightness and released pads at their normal color, so that I can see which cue is sounding.
- As a DJ, I want an option for the platter ring to pulse on each beat or on the downbeat, so that I can see the beat while mixing.
- As a DJ, I want the ring to stay solid when beat pulse is off or no clock is arriving, so that it never looks broken.
- As a DJ, I want blinking and pulsing not to flood the controller with MIDI, so that the LC6000 stays responsive.
Mapping check
- As a DJ, I want an imported mapping checked for unknown keys, wrong types, out-of-range numbers (notes and CCs 0–127, channels 1–16, decks 1–4) and duplicate assignments, so that typos are caught before I play.
- As a DJ, I want every problem in an imported mapping listed at once, with the key's name and what was expected, so that I can fix them all in one go.
- As a DJ, I want a rejected import to leave my working mapping unchanged, so that a typo never breaks a running set.
Diagnostics
- As a DJ, I want a MIDI monitor window that shows each incoming message with its mapping name, or UNMAPPED, so that I can check my unit against the mapping.
- As a DJ, I want an LED sweep that steps the pads and ring through all 64 color values and then lights each button note, so that I can check the color table and LED notes.
- As a DJ, I want an OSC log in the diagnostics, showing what is sent and received, so that I can see why a control does nothing.
Maintainer
- As a maintainer, I want all the bridge logic in a Swift package with no CoreMIDI, networking or UI in it, so that it runs under
swift testin the terminal and in CI. - As a maintainer, I want the release set up like ShowRecorder's (a version tag builds, signs and uploads to TestFlight and the App Store), so that I ship both apps the same way.
- As a maintainer, I want the Python bridge kept until the Swift app matches it, then removed in one ticket, so that there is always a working tool.
Implementation Decisions
-
Project layout copies ShowRecorder.
- An XcodeGen project file, a bundle identifier under
dev.ericdahl, Swift 6 with strict concurrency, and macOS 26 as the minimum. - A local Swift package (LC6000Kit) holds every piece of logic, with a thin app target on top.
- CI builds and tests on GitHub's standard macOS runner. Pushing a version tag archives, signs and uploads to App Store Connect, using the same kind of secrets ShowRecorder uses (an Apple Distribution certificate, a Mac Installer certificate and an App Store Connect API key).
- An XcodeGen project file, a bundle identifier under
-
Package modules:
- Core: the Bridge (per-controller translation and LED state), the Coordinator, the mapping model and its check, and the OSC codec. Pure Swift: no CoreMIDI, no Network framework, no UI.
- MIDI adapter: CoreMIDI behind the Coordinator's MIDI-system interface.
- OSC transport adapter: UDP behind the Coordinator's send and feedback interfaces.
- The app: a SwiftUI menu-bar extra, settings, diagnostics windows and the first-run guide.
-
Coordinator interface. The one test seam for behavior. It takes:
- A MIDI system: lists sources and destinations with a stable id, name and connected flag, opens an input that delivers parsed MIDI messages, opens an output that sends them, and reports added and removed devices.
- An OSC sender: address plus typed arguments.
- A clock.
- A log sink.
It exposes start, stop, feedback (address plus arguments), tick, and an observable status for the menu.
-
Coordinator holds a list of Bridges from the start, and settings are stored as a list of controller entries, so adding multiple controllers later is an addition, not a rewrite.
-
Held controls are recorded at press time with their deck, address and release arguments. Release-all sends exactly those, once, and is safe to call again. It also clears Shift and touch state. Changing deck or device, importing a mapping, unplugging, sleep and quit all go through it.
-
One resync routine: clear the LED cache, repaint every LED, send one feedback resend. Replug, feedback coming back and mapping import all use it, so a resend is never doubled.
-
Threading. CoreMIDI callbacks, UDP receive and the tick timer all hop onto one serial executor that owns the Coordinator. The Coordinator is an actor, or is confined to one, and replaces the Python lock. Tests drive it directly with the fake clock and see no real threads.
-
Disconnect and reconnect use CoreMIDI notifications, not polling.
- When a controller's source is removed, the Coordinator releases everything held on that Bridge exactly once, closes its ports, logs it and shows it in the status.
- When a matching source is added, it reopens the ports, clears the LED cache, repaints every LED, sends a feedback resend and re-arms pitch pickup.
- A send or read error counts as a disconnect.
- Waking from sleep re-checks the device list.
- Starting with no controller is not an error.
-
Controller matching. Prefer the CoreMIDI unique id saved for the device. Fall back to a name substring, then the MIDI channel. Two controllers claiming the same device and channel is a mapping error.
-
OSC codec. Hand-written, no dependency.
- Encoding: a message with int32, float32 and string arguments, each argument 4-byte aligned and big-endian, with a type tag string.
- Decoding: messages and bundles; unknown type tags are skipped.
- Transport: UDP. Send to the configured host and port, and listen on the feedback port.
-
Mapping. The default mapping ships in the app as JSON, ported value for value from the Python default mapping, keeping the PROVISIONAL markers as comments in the docs. JSON was chosen over TOML because Foundation decodes it, so no extra package is needed.
- Settings: deck, devices, hosts and ports are app settings, stored in user defaults.
- Mapping overrides: a user mapping file is imported through the open panel and copied into the app container. The override merges over the default, the same way the Python config merge works. The check runs on the merged result before it replaces the working mapping.
-
Sandbox and entitlements (Mac App Store):
- The app sandbox.
- The network client entitlement, to send OSC.
- The network server entitlement, to listen for feedback.
- User-selected read-write files, for mapping import (read) and export (write). ShowRecorder uses the same entitlement.
LSUIElement(no Dock icon), the hardened runtime, andITSAppUsesNonExemptEncryptionset to false, as in ShowRecorder.- A privacy manifest.
- A local-network usage description, for a Syndicate host that isn't loopback.
CoreMIDI needs no entitlement. The first ticket proves that with a signed, sandboxed build.
-
Pickup, liveness, timing LEDs, held-pad brightness and multiple controllers follow the same rules as spec Multi-controller support, pitch pickup, recovery and richer LED feedback #2 (now superseded), moved onto the Coordinator and Bridge:
- Pickup re-arms on load, on a change to slider-enabled, and on a reported value that differs from the last value sent.
- Liveness has a timeout, and stale state falls back to idle LEDs. When feedback comes back, the bridge sends one resend.
- Blink and pulse are driven by tick, through the de-duplicating LED cache.
- Multiple controllers: one feedback listener fans out to every Bridge.
-
OSC rules from the Syndicate guide still apply:
- Triggers fire only on a press.
- Holds are always followed by a release.
- Each message carries one int32 or float32 argument, except the multi-argument hot-cue, cue-loop and sampler routes.
- No wildcards. Addresses are matched without regard to case.
-
App Store review. A built-in demo MIDI source lets a reviewer see the app work without an LC6000. The submission includes review notes and a short video. Start at login is off by default and uses the system login-item service.
-
Python removal is its own last ticket, once every parity story above passes in the app and the diagnostics windows exist.
Testing Decisions
-
Seam 1: the Coordinator (agreed). Tests give it:
- a fake MIDI system: a device list, add and remove events, and fake input and output ports that record what is sent
- a fake OSC sender
- a fake clock
- a fake log
Tests check only what comes out: the OSC sent to Syndicate, the LED messages sent to the controller, the log lines and the status. Every behavior is tested here: buttons, jog, pitch, pads, LEDs, pickup, timing LEDs, multiple controllers, unplug and replug, and liveness. The Bridge is not tested on its own.
-
Seam 2: OSC packet bytes (agreed). Encoding and decoding are tested against byte strings worked out by hand from the OSC 1.0 spec: int32, float32, string padding, several arguments, and a bundle. Expected bytes are literals, never produced by the encoder.
-
The mapping check is tested through the Coordinator's start, or the import function on the Core module: a mapping document goes in, and a list of readable errors comes out (or none).
-
Expected values come from independent sources: the 23 Python tests (which are prior art and can be ported as cases), the LC6000 MIDI spec text and the Syndicate OSC guide. They are never recomputed the way the code computes them.
-
What makes a good test here: it describes a controller action or a Syndicate state change, and checks the OSC or LED messages that result. For example: "unplug while holding Cue sends Cue 0 once". It does not check how that is done.
-
Not unit-tested: the CoreMIDI adapter, the UDP transport and the SwiftUI app. The CoreMIDI callback parses the MIDI words into plain values before returning, because the event-list pointer is only valid during the callback. MIDI, UDP feedback and the tick timer feed one ordered stream that the Coordinator consumes, so message order is kept. They are covered by one smoke check: the sandboxed app against a virtual MIDI source and a UDP loopback listener, scripted as a manual step in CI or in the README.
-
Hardware checks stay manual, using the in-app MIDI monitor and LED sweep.
Out of Scope
- Windows and Linux. The app is Mac only.
- Scratching or touch-scrub, because Syndicate has no route for it.
- The platter's center display, because it needs undocumented SysEx.
- Slicer mode, and setting or deleting hot cues from the controller: Syndicate has no routes for these.
- Confirming the PROVISIONAL mapping values on hardware. That is a human task, done with the diagnostics.
- Controllers other than the LC6000.
- Syndicate addresses newer than 0.3.9.
- Paid features and in-app purchases.
Further Notes
- Supersedes spec Multi-controller support, pitch pickup, recovery and richer LED feedback #2 and tickets Check the mapping file, plus a validate command #5–Multiple controllers in one process #10. Their features are carried into this spec.
- Targets Syndicate public beta 0.3.7. Its OSC API is fixed. Feedback is sent only when a value changes, except Time (at most once a second) and the beat messages.
- Mapping numbers come from Denon's LC6000 PRIME MIDI Specification v1.0. Run the hardware checks before relying on the PROVISIONAL values (the jog CCs, the pitch direction, the color table layout and the LED notes). The Python
monitorandled-sweepcommands work today, and doing it before porting the values is cheapest. - Probe (2026-11-15, Xcode 27.2, macOS 27): all of these work unsandboxed:
MIDIClientCreateWithBlock, with its notify blockMIDIInputPortCreateWithProtocol(MIDI 1.0)MIDIOutputPortCreateMIDISourceCreateWithProtocol, for a virtual source in tests- Network.framework UDP
- Spelling: the org requires American spelling in every PR, including Swift files and issue text.
Activity
45 remaining items