Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 38 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
# Changelog

## 1.0

The first release: a Mac menu-bar app that plays Untitled Audio Syndicate from a Denon LC6000 PRIME over OSC, with
LED feedback. It replaces the Python `lc6000-bridge` command-line tool.

### Controller

- Transport, loops, beat jumps, Key Lock, Slip, Censor (hold, or latched with Shift), Pitch Bend and the browser.
- Pads in Hot Cue, Roll and Loop modes.
- The 14-bit jog wheel bends the phase while playing and seeks while paused; the Needle Drop strip seeks.
- The 14-bit pitch fader at full resolution, with pickup so the tempo never jumps; Shift + Key Lock resets it.
- Four decks from one unit: the bridge follows the LC6000's deck layers.

### LEDs

- Play, Cue, Sync, Master and the loop LEDs follow Syndicate. Play blinks while a quantized start is pending.
- Pads show hot cues in Syndicate's cue colors; a held pad lights brighter.
- The platter ring shows the active deck's color, following Syndicate's cue palette or your own colors.
- Optional beat pulse on the ring, and a choice of dim or off for Syndicate's LEDs while feedback is stale.

### App

- A panel with status lights (CONTROLLER, FEEDBACK, TEMPO) and plain-words help when the LEDs are dark.
- A warning when Syndicate's OSC feedback subscriptions are off (FEEDBACK ● NO DECK DATA), or when one an LED needs is
missing.
- Settings: deck, MIDI devices, channel, layers, a second controller, LEDs, OSC host and ports, feedback listening,
deck colors, appearance (Match macOS, Dark or Light), mapping import and export, and start at login.
- Diagnostics: MIDI Monitor, LED Sweep and OSC Log.
- A setup guide for Syndicate, and a demo controller that runs without hardware.
- Recovery: unplug, replug, sleep, a restarted Syndicate and quitting all release held controls and repaint the LEDs.
- Syndicate's look, in its own dark and light theme tokens, with every text color at WCAG AA.

### Not possible yet

- Scratching (Syndicate has no scratch or scrub OSC route), the platter's center display (undocumented SysEx) and
Slicer mode (unmapped).
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -145,15 +145,15 @@ xcodebuild -project ControllerBridge.xcodeproj -scheme ControllerBridge -configu
scripts/smoke.sh # a virtual LC6000 and a fake Syndicate check Play out and the Play LED back; CI requires it too
```

Build Release for the smoke check: an ad-hoc Debug build leaves out the hardened runtime. Quit Syndicate and the app itself first, because the smoke check needs UDP 9090 and 9096. A real controller can stay plugged in: the check pins the app to its own virtual device and puts your saved settings back afterwards.
Build Release for the smoke check: an ad-hoc Debug build leaves out the hardened runtime. Quit Syndicate and the app itself first, because the smoke check needs UDP 9090 and 9096. With no real LC6000 attached, the check runs the app on automatic devices beside a virtual "… WD" port, as on a real unit (#143). A real controller can stay plugged in: then the check pins the app to its own virtual device instead and says the automatic case was skipped. It puts your saved settings back afterwards. CI always runs the automatic case.

**CI uses an older Xcode than you may have locally.** GitHub's standard macOS runner builds with Xcode 26.x (Swift 6.2), while development has been on Xcode 27.2. The two compilers can disagree. Once, Xcode 26.6's Release optimizer crashed on code that 27.2 built fine (#65). If **App build** fails with a `swift-frontend` stack dump, find the function named in `gh run view <id> --log-failed`, then simplify or split it.

Releases are a version tag on `main`. See [`docs/DEVELOPING.md`](docs/DEVELOPING.md#releasing-to-testflight) for the workflow, its secrets and the one-time setup.

### Look and fonts

The app follows Syndicate's dark, flat style (#34). The colors were sampled from its public screenshots, and `ControllerBridgePresentation` tests every text color against WCAG AA. The app bundles two fonts under the [SIL Open Font License 1.1](https://openfontlicense.org): [Inter](https://github.com/rsms/inter) 4.1 for UI text and [IBM Plex Mono](https://github.com/IBM/plex) 2.5.0 for numbers. Their license files ship in the app, in `Contents/Resources/Fonts/` (`App/Fonts/` in the repo).
The app follows Syndicate's flat style (#34) in its dark and light themes. The colors are Syndicate's own tokens, from its user guide's CSS (#127), and `ControllerBridgePresentation` tests every text color against WCAG AA in both themes. **Settings › Appearance** picks Match macOS, Dark or Light. The app bundles two fonts under the [SIL Open Font License 1.1](https://openfontlicense.org): [Inter](https://github.com/rsms/inter) 4.1 for UI text and [IBM Plex Mono](https://github.com/IBM/plex) 2.5.0 for numbers. Their license files ship in the app, in `Contents/Resources/Fonts/` (`App/Fonts/` in the repo).

For PR screenshots, a Debug build can render the panel without a screen: `ControllerBridge.app/Contents/MacOS/ControllerBridge --render-snapshots snaps`. It prints where the PNGs went (inside the sandbox container). Release builds leave this out.

Expand Down
119 changes: 119 additions & 0 deletions docs/HARDWARE-CHECK.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
# Hardware check before a release

About 15 minutes on a real Denon LC6000 PRIME and Syndicate, run on the build you're about to ship. Each line is one
check: do the action, then confirm the expected result. If any line fails, file an issue and don't ship.

## Before you start

- Quit djay Pro, Engine DJ and any other DJ app, then power-cycle the LC6000.
- Syndicate is set up as in the README's [Set up Syndicate](../README.md#set-up-syndicate), with every subscription on.
- Load tracks with hot cues on decks 1 and 2. Leave decks 3 and 4 empty for now.
- The Mac is plugged in. You'll put it to sleep once.

## 1. Connect and feedback

| # | Do | Expect |
|---|---|---|
| 1.1 | Launch the app with the LC6000 plugged in | Panel: CONTROLLER ● CONNECTED, FEEDBACK ● LIVE. The LEDs light up |
| 1.2 | Open the panel | Deck shows "Following controller layers"; badge 1 is selected |

## 2. Transport (layer 1, deck 1)

| # | Do | Expect |
|---|---|---|
| 2.1 | Press Play | Deck 1 plays; Play LED lit |
| 2.2 | Press Play with quantize on in Syndicate | Play LED blinks until the start lands, then stays lit |
| 2.3 | Pause, then hold Cue | Deck 1 previews from the cue point while held, and returns on release; Cue LED follows Syndicate |
| 2.4 | Press Sync, then Master | Sync and Master LEDs follow Syndicate; the panel shows TEMPO ● MASTER when deck 1 leads |
| 2.5 | Loop In, Loop Out, then Auto Loop; turn the Auto Loop knob | A loop is set and toggled; the knob halves or doubles it; loop LEDs follow |
| 2.6 | Beat Jump ◀ and ▶ | Jumps one beat each way |
| 2.7 | Param ◀ and ▶ | Skips one beat each way |
| 2.8 | Hold Pitch Bend − then + | Tempo nudges while held and returns on release |
| 2.9 | Hold Censor | Plays in reverse while held, forward on release |
| 2.10 | Key Lock, then Slip | Syndicate's key lock and slip toggle; both LEDs show their state |
| 2.11 | Turn and press the Browse knob, then Back, Forward and Track ◀ ▶ | The browser moves, loads to deck 1 and goes back |

## 3. Shift functions

| # | Do | Expect |
|---|---|---|
| 3.1 | Hold Shift | Shift LED lit while held |
| 3.2 | Shift + Beat Jump ◀ ▶ | Jumps a bar each way |
| 3.3 | Shift + Censor, twice | First press latches reverse on, the second turns it off |
| 3.4 | Move the pitch fader off center, then Shift + Key Lock | Tempo resets to 0; the fader does nothing until it reaches the center |
| 3.5 | Shift + Browse press | Enter in Syndicate's browser |
| 3.6 | Shift + Pitch Bend | Nothing happens (Syndicate has no OSC route for the pitch range) |

## 4. Pads

| # | Do | Expect |
|---|---|---|
| 4.1 | Hot Cue mode | Mode LED lit; pads show deck 1's hot cues in Syndicate's cue colors |
| 4.2 | Hold a hot cue pad | Plays from that cue while held; the pad lights brighter |
| 4.3 | Roll mode; hold each pad | Slip loop rolls from 1/32 up to 4 beats while held; the track resumes where it would have been |
| 4.4 | Loop mode; press a pad | Sets that cue loop |
| 4.5 | Slicer mode | Nothing happens (unmapped) |

## 5. Jog, pitch and needle drop

| # | Do | Expect |
|---|---|---|
| 5.1 | Turn the jog while deck 1 plays | Phase bends while turning, and stops about 80 ms after the wheel stops |
| 5.2 | Turn the jog while deck 1 is paused | Seeks through the track |
| 5.3 | Move the pitch fader slowly over its full range | Tempo follows smoothly, in fine steps; the top is slower |
| 5.4 | Touch and slide on the Needle Drop strip | Seeks to that point while touched |

## 6. Layers 1-4

| # | Do | Expect |
|---|---|---|
| 6.1 | Shift + deck select to layer 2, press Play | Deck 2 plays; the panel shows deck 2; every LED repaints from deck 2 |
| 6.2 | Move the pitch fader on layer 2 | Deck 2's tempo doesn't jump: it waits until the fader meets deck 2's tempo (pickup) |
| 6.3 | Hold a pad on layer 2, then switch to layer 1 | The held pad is released on deck 2 |
| 6.4 | Step through layers 3 and 4 | Each drives its own deck; with no track loaded the ring stays off |
| 6.5 | Settings: turn Follow controller layers off, pick deck 3 | Every layer drives deck 3; turn it back on after |

## 7. LEDs, ring and colors

| # | Do | Expect |
|---|---|---|
| 7.1 | Layer 1, then layer 2, with tracks loaded | The platter ring shows each deck's color, the same as its badge in the panel |
| 7.2 | Settings › Decks: Use Syndicate's deck colors on; change cue palette slot 3 in Syndicate | Deck 2's badge and ring change to the new color right away |
| 7.3 | Turn Use Syndicate's deck colors off; pick a custom deck 1 color | The badge, the preview and the ring use your color |
| 7.4 | Vivid ring colors (once #156 is in the build): switch Vivid / Exact | Vivid looks saturated, with no washed-out white; Exact is the plain mapping; it repaints at once |
| 7.5 | Settings: turn Controller LEDs off, then on | All LEDs go dark, then repaint |
| 7.6 | Diagnostics › LED Sweep | Pads and ring step through the 64 colors, then each button lights in turn |

## 8. Subscriptions warning

| # | Do | Expect |
|---|---|---|
| 8.1 | In Syndicate, turn off every OSC FEEDBACK subscription, then quit and relaunch the app | FEEDBACK ● NO DECK DATA in orange; the help lists the subscriptions to turn on, with Setup guide |
| 8.2 | Turn them all back on | FEEDBACK ● LIVE within a few seconds; the LEDs come back |
| 8.3 | Turn off only Cues, with a track loaded; wait about 15 s | FEEDBACK stays LIVE; help says hot cue pad colors need the Cues subscription. Turn it back on |
| 8.4 | Eject every track (empty decks), wait about 15 s | Plain LIVE: no warning |

## 9. Unplug, sleep and quit

| # | Do | Expect |
|---|---|---|
| 9.1 | Hold a pad, then unplug the USB cable | The deck stops the held action; CONTROLLER ● UNPLUGGED |
| 9.2 | Plug it back in | CONNECTED; the LEDs repaint from Syndicate's state |
| 9.3 | Quit Syndicate, wait 15 s | FEEDBACK ● DROPPED; Syndicate's LEDs go idle; the panel shows the last dropout time |
| 9.4 | Relaunch Syndicate | FEEDBACK ● LIVE again; the LEDs catch up without touching anything |
| 9.5 | Hold Censor, then put the Mac to sleep and wake it | Reverse was released; the controller works again after wake |
| 9.6 | Quit from the panel while feedback is live | It asks first; Cancel keeps it running |
| 9.7 | Press ⌘Q with the panel open | Quits without asking |

## 10. Settings, Diagnostics and demo

| # | Do | Expect |
|---|---|---|
| 10.1 | Settings: type an empty host, click Apply | The problem is listed in plain words; nothing changes |
| 10.2 | Settings: Appearance Light, then Dark, then Match macOS | Every window follows; text stays readable |
| 10.3 | Settings › Mapping: Export, then Import the same file | It's accepted; the Mapping section names it; Reset to default goes back |
| 10.4 | Settings: Start at login on, log out and in | The app starts; turn it off after |
| 10.5 | Diagnostics › MIDI Monitor, move every control | Each message shows a mapping name, not UNMAPPED |
| 10.6 | Diagnostics › OSC Log | What goes to Syndicate and what comes back both show |
| 10.7 | Panel: Demo controller on | A scripted controller drives a simulated Syndicate; nothing goes to the network; relaunch turns it off |
| 10.8 | Panel: Setup guide | The steps show the live status lights; the button reads "Done: feedback live" |
16 changes: 16 additions & 0 deletions docs/TESTFLIGHT.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# TestFlight: What to test

Paste this into the build's "What to Test" in App Store Connect.

---

Controller Bridge 1.0 plays Syndicate from a Denon LC6000 PRIME. Please try:

- Setup: follow the setup guide on first launch. FEEDBACK should read LIVE.
- Play a set: transport, hot cues, loops, jog, the pitch fader and the Needle Drop strip.
- Four decks: Shift + deck select through layers 1-4. The ring and LEDs should follow each deck.
- LEDs: pads in your cue colors, and the ring in each deck's color.
- Recovery: unplug and replug the controller, sleep the Mac, and restart Syndicate. Everything should come back.
- If the LEDs stay dark, read the panel's "Why no LEDs?" help. Does it tell you what to fix?

Tell us about anything that didn't respond, lit the wrong color, or needed a relaunch.
Loading