Skip to content

Add independent previews and configurable audio routing - #11

Open
timz wants to merge 4 commits into
beneaze:mainfrom
timz:feature/additional-preview-buttons
Open

timz wants to merge 4 commits into
beneaze:mainfrom
timz:feature/additional-preview-buttons

Conversation

@timz

@timz timz commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Add independent track and mashup previews across Library, Studio Playlist and Mashups, Add tracks, the Live browser, and the Automix queue. Two private decks and a separate conductor keep previews independent of Studio, Automix, and Live transport. Preview buttons share playback state, replace or stop the current preview, and reset on completion or failure. Track previews start at the first analyzed drop, otherwise one third into the track; mashups retain their alignment and lead-in.

Output routing

  • Keep Auto as the default audio-device routing, including system-default startup fallback: master on 1/2 and headphone CUE on 3/4 when available. Deck CUE is never summed into the speaker output. The legacy MainOutput configuration remains readable but no longer exposes a physical CUE output.
  • Offer a separate preview preference: Auto / Headphones / Main output. Auto resolves against the running output when playback starts, preferring configured headphones and otherwise using the physical main output. Configured but unavailable headphones reject playback. The destination remains fixed for the session; loss stops playback rather than retargeting it to speakers.
  • Keep both preview destinations outside the master bus, recording, and offline exports. Headphone previews enter after CUE/MIX; speaker previews use an isolated third bus summed only in the device callback before final output protection. PHONES controls preview volume independently of MASTER. Separate-device alignment includes the final output limiter's latency.
  • Migrate preferences older than version 4 once to preview Auto, including the earlier Master preference. Preserve saved audio-device settings and subsequent explicit preview choices.

Settings and behavior changes

Master and headphone device/channel settings remain separate from the preview destination. Restore explicit Auto, Off, and Split cable options alongside channel pairs and a separate device. Apply commits both drafts after success and stops the preview; failure preserves the applied settings. Discard restores both drafts. List labels show the resolved output rather than an unapplied setting.

On a headphone output, CUE/MIX explicitly controls master monitoring: with no CUE selected and the knob at CUE (the default), headphones are silent. This intentionally changes the previous automatic master-monitoring behavior. CUE/MIX is disabled when no headphone route exists. Leaving the preview's source screen also stops it.

MixPlayer::stop clears pending prefetch requests for all players, not only previews. This change from the original implementation remains in the PR.

Validation

  • cargo test -p clubcraft-engine -j 4 passed: 49 unit tests, 31 engine integration tests, 13 preview tests, and 1 doc test.
  • cargo test -p clubcraft -j 4: 39 passed, 4 ignored, 3 failed in the previously observed DJ.Studio importer tests (imports_library_and_project, reimport_updates_the_same_mix_and_keeps_samples, and user_cues_are_kept), where fixture track lookup returns None. Routing resolution/loss, migration, Apply/Discard, and preview UI tests passed.
  • cargo clippy --workspace --all-targets -j 4 -- -D warnings passed.
  • cargo build -p clubcraft -j 4 and git diff --check passed.
  • Signal and routing tests run offline. Physical output listening and device disconnect/reconnect remain unverified manually.
  • The existing four-deck CPU-budget test passes, but a four-deck set plus a two-deck mashup preview is not yet covered by a dedicated CPU-budget test. No six-deck performance claim is made.

@beneaze beneaze left a comment

Copy link
Copy Markdown
Owner

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! Running previews on two private decks with their own transport is a good change: previews no longer stop the Studio or Live mixes, and the extra rendering doesn't allocate on the audio thread.

I reviewed this by reading the code; I haven't built or run it here. Two routing problems need fixing first, because both can put audio on the speakers that the audience shouldn't hear.

Blockers

  1. The new default routing sends deck CUE to the speakers. AudioConfig::default() changes from Auto to MainOutput, and in that mode the cue bus (the deck 🎧 buttons plus previews) is added to the physical master output (mix_shared_output in engine.rs). So in a new install, pressing 🎧 on the next deck plays it to the room.
    • The same happens whenever the app falls back to AudioConfig::default(), including the startup fallback when the saved interface is unplugged.
    • New installs with a 4-output controller no longer get cue on outputs 3/4 automatically; the cue goes into the speakers and the headphone jack stays silent.
    • Previewing through the main output can make sense when preparing on a laptop, but deck CUE through the speakers is never what a DJ wants.
  2. Existing setups send previews into the master and the recording. Prefs::preview_output defaults to Master, and existing preference files don't have the field. With any routing other than MainOutput (Auto, channel pairs, separate device), Mixer::process adds the preview to the master bus before master gain, the limiter and the recorder tap (core.rs:605–610). So until an existing user presses Apply, the new preview buttons in the Live browser and Automix queue play to the audience and into the recording, which contradicts the PR description. The settings screen also shows these users "Main output" (legacy_main), which isn't what their engine is doing.

Behaviour changes to discuss

  1. Headphones no longer hear the master when no deck is cued. Today they do; now they're silent unless CUE·MIX is turned toward master, and its default is 0. That matches hardware mixers, but it changes the default for every existing 4-output setup.
  2. Settings no longer offer Auto, Off or Split cable; Split appears only as "saved configuration", and choosing "Main output" turns on the shared mode.

Smaller

  1. A preview during a 4-deck set renders two more decks in the same callback. cpu_budget_4_decks_keylock_stems_fx doesn't cover that case.
  2. MixPlayer::stop now clears pending prefetches for every player, not only previews. It looks harmless, but please mention it in the description.

Suggested direction

  • Keep Auto as the default routing.
  • In MainOutput, don't put deck CUE on the speakers. Either leave PFL out of the shared output, or allow speaker previews only while no deck is playing.
  • Default preview_output to headphones when a headphone output exists, otherwise to the main output, and never route previews into the master bus or the recording.

@timz

timz commented Nov 12, 2026

Copy link
Copy Markdown
Contributor Author

Thanks for the detailed review. I agree with both blockers and have pushed 0f3b259 to address them.

  1. Restored AudioConfig::default() to Auto, including startup fallback. Four-output devices retain master 1/2 and CUE 3/4. Removed shared CUE-to-speaker mixing entirely: the legacy MainOutput route now has no physical deck CUE output. Only an isolated preview bus can be added to the physical main output.
  2. Added preview Auto and a one-time version-4 migration of older preview preferences, including Master, while preserving saved device routing. Auto prefers the running headphone route; configured but unavailable headphones reject playback rather than falling back to speakers. Speaker previews now bypass the master bus and recorder and are summed only in the device callback. PHONES controls them independently of MASTER. Removed legacy_main; list labels use the resolved route, and settings no longer pretend a different audio configuration is active. The preview destination stays fixed while loading/playing and output loss stops the session.

Added regression coverage for default/legacy channel routing, separate speaker-preview isolation from CUE and recording, automatic routing and failed endpoints, destination pinning, preference migration, and Apply/Discard including failed Apply.

The other behavior notes are now explicit in the PR description: the no-CUE silence at the CUE end remains intentional, Auto/Off/Split cable options are restored, and MixPlayer::stop still clears pending prefetch requests for all players. A dedicated four-live-decks-plus-two-preview-decks CPU-budget test remains outstanding; the existing four-deck test is not presented as covering that case.

Validation: all engine tests passed (49 unit, 31 engine integration, 13 preview, 1 doc), Clippy with warnings denied passed, and the Windows debug app built successfully, all with -j 4. App tests report 39 passed, 4 ignored, and the same 3 previously observed DJ.Studio importer failures. Hardware listening and disconnect/reconnect checks have not been performed. The PR description has been updated to match the final routing.

@beneaze

beneaze commented Nov 12, 2026

Copy link
Copy Markdown
Owner

Thanks, this addresses both blockers. Auto is the default again, deck CUE never reaches the speakers, previews stay out of the master bus and the recording, and the preference migration looks right.

One new issue from moving speaker previews into the callback: every master output now runs through shared_limiter (fixed −0.3 dB ceiling, always enabled), in every routing mode and even with no preview playing. It ignores SetLimiter, so disabling the master limiter or raising its ceiling to 0 dB no longer affects the speakers, while the recording stays unlimited. Please make it follow the master limiter's on/off state and ceiling.

Smaller: on a stereo-only setup, Auto resolves to the main output, so the Live browser and queue previews play to the room during a set, and the audience warning only appears when Main output is chosen explicitly. Consider refusing or confirming speaker previews while the master is playing. The 4 + 2 deck CPU budget test is also still open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants