Repository navigation
Audio: support separate master and headphone output devices - #10
Conversation
beneaze
left a comment
There was a problem hiding this comment.
Thanks for the careful write-up and the thorough tests. Handing the core back by destroying the callback, rather than waiting for one more callback, is a real improvement over the current reopen logic.
Checked on macOS: cargo clippy --workspace --all-targets -- -D warnings passes, and cargo test -p clubcraft-engine passes (38 unit, 31 integration, 1 doctest). No listening test here.
Blocker
Any stream error now mutes the master until Apply, in every routing mode. err_cb sets health.master.failed, which is sticky, and the master callback then outputs silence. cpal 0.18.2 reports ErrorKind::Xrun through the error callback on every backend (CoreAudio, WASAPI, ALSA, PipeWire, JACK, ASIO). CoreAudio also reports DeviceChanged for a default-device stream whose route changed, while the stream keeps running. So the first underrun in a set silences the speakers. The log::warn! is gone too, so the error isn't logged anywhere. Please mark an endpoint failed only for errors that really end the stream (DeviceNotAvailable, StreamInvalidated, …), and count xruns as diagnostics.
Significant
- The stall detector never recovers.
check_stalledruns whenever the UI reads stream info. A gap of more than 2 s (waking from sleep, another app taking exclusive mode) marks the output failed for good, even after callbacks resume. It should clear once callbacks are back. - Single-device setups lose their fallbacks.
LiveEngine::startno longer falls back toAudioConfig::default().choose_formatno longer falls back to the device's default rate, a savedsample_rateis now strict, andsupports_bufferrejects buffer sizes outside the reported range off Windows. So a saved setup that no longer matches the hardware now starts with no audio at all, where today it plays on the default output. Strict negotiation makes sense forSeparateDevice; please keep the existing modes as forgiving as they are onmain. - The master runs through a moving delay.
master_delayfollows a smoothed offset that includes the wandering fill of the cue queue. The tap slews at up to 0.25 frames per sample, which is a 25 % speed change while it moves; settling about 25 ms sweeps the master's pitch for around 100 ms. I'd keep the master delay fixed (set on open or when the correction changes) and do all continuous correction on the cue side, for example by steering the servo on timing error rather than on queue fill.
On the headphone lag
- With Bluetooth, the driver estimates don't cover the codec delay (often 100–300 ms), and compensating for it means delaying the master by that much. I think it's fine to document Bluetooth as unsuitable for cue rather than keep the PR open on it.
- Something the code can fix: without driver timestamps,
render_atusesalignment(0.0, …)(output.rs:282). That ignores the latency the cue path adds itself (target fill of about 20–30 ms plus the 15-frame sinc look-ahead), which the code knows exactly. Compensating for it would remove part of the lag on drivers without timestamps.
Minor
output.rshas unexplained constants (0.94 cutoff,1e-7/2e-6servo gains, the 0.25 slew) and one-letter names.AGENTS.mdasks for comments that explain why.output_probestarts the streams before setting the gains to −60 dB. That's harmless with no tracks loaded, but setting gains before starting would follow the house rule exactly.
Next steps
Please fix the blocker and items 1–2 before marking this ready. Item 3 is a design suggestion; happy to discuss.
|
This is my first major contribution to an external project, so please forgive me if I’ve done anything wrong. 😅 |
|
No it's perfectly fine, and thanks for the contribution! I just had Claude checking on the PR. |
|
I tested it with Bluetooth headphones, and there's a delay of around 140 milliseconds. However, there's a field to manually compensate for this delay. Codex couldn't find a better way to detect the latency. I didn't have this issue in VirtualDJ, but I couldn't figure out how they implemented it. |
|
Thanks, that matches what I'd expect: on Windows the Bluetooth codec delay isn't part of the timing cpal gets from the driver, so the manual correction is the right tool, and documenting Bluetooth as unsuitable for low-latency cueing is fine. On VirtualDJ: ClubCraft follows a clean-room rule ( Since the PR is now marked ready: there are no new commits yet, so the points from the review still apply. Most important is the blocker. Any xrun reported to the error callback mutes the master until Apply, in every routing mode. Please fix that and items 1–2 before we merge. |
|
Addressed the review in commit 2950371.
Validation: Windows app build and workspace Clippy pass; 42 engine unit tests, 31 integration tests, 1 doctest and 3 app startup tests pass. The full workspace run still reports the same 3 importer failures and 5 missing-model failures. A silent Senary Audio reopen probe passes; AKG is not currently connected, so I could not repeat the revised two-device hardware probe. No new listening or macOS/Linux hardware result is claimed. The PR description and output documentation now describe the revised behavior and Bluetooth limitation. |
|
Thanks, this addresses everything from the review. The error classification, stall recovery, single-device fallbacks and fixed master delay all look right, and clippy plus the engine and app tests pass on macOS. One regression from combining the restored fallback with Smaller, not blocking: |
|
Addressed both follow-up points in e696117.
Windows validation: app build and workspace Clippy pass; 44 engine unit tests, 31 integration tests, 1 doctest and all 4 startup/persistence tests pass. The full workspace run still has the same 3 importer failures and 5 missing-model failures. No additional hardware or listening result is claimed for this follow-up. Updated the output documentation, UI hint and PR description accordingly. |
Summary
Allow speakers and headphone cue/PFL to use two independent audio output devices. The existing single-device channel routing modes remain available.
Refs #9.
Changes
Validation
Windows checks for the review fixes:
cargo build -p clubcraft -j 4— passed.cargo clippy --workspace --all-targets -j 4 -- -D warnings— passed.cargo test --workspace --no-fail-fast -j 4— all changed-area tests passed; the same 8 previously reported failures remain: 3 DJ.Studio importer tests on Windows and 5 separation tests requiring missing ONNX models. The workspace run is not green.Before the review fixes, silent probes opened and reopened Senary Audio and AKG N9 Hybrid in both directions. The maintainer also reported passing macOS Clippy and engine tests for the original commit. These results do not establish cross-platform hardware or acoustic alignment for the revised code.
Limitations
Driver timestamps do not cover the complete wireless/analog path. Bluetooth listening tests showed approximately 140 ms of additional headphone lag; use manual correction to delay master accordingly. Bluetooth is unsuitable for low-latency cueing.
Fixed calibration avoids master pitch modulation but can leave residual offset if device latency or cue buffering changes; Apply recalibrates. The resampler still regulates queue fill, rather than steering on timestamp error. Analog alignment, physical unplug/replug and revised two-device behavior on macOS/Linux need hardware validation.
Developed with AI assistance and tested locally.