From 25b652fa9abe11d6cd76e2d4c93a034e954891f8 Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Thu, 5 Nov 2026 10:40:27 +0300 Subject: [PATCH 1/4] Add independent track previews and explicit headphone monitoring --- crates/app/src/app.rs | 98 +++++++--- crates/app/src/library_view.rs | 39 +++- crates/app/src/live/adapter.rs | 57 ++++-- crates/app/src/live/view.rs | 4 +- crates/app/src/main.rs | 1 + crates/app/src/mashup_view.rs | 20 +- crates/app/src/prefs.rs | 13 ++ crates/app/src/preview.rs | 178 +++++++++++++++++ crates/app/src/settings.rs | 16 +- crates/app/src/studio.rs | 34 +++- crates/app/src/theme.rs | 3 + crates/app/src/track_picker.rs | 8 +- crates/app/src/widgets.rs | 13 +- crates/engine/src/command.rs | 23 +++ crates/engine/src/core.rs | 33 ++++ crates/engine/src/deck.rs | 8 + crates/engine/src/dsp.rs | 13 ++ crates/engine/src/fx.rs | 26 +++ crates/engine/src/lib.rs | 1 + crates/engine/src/mixer.rs | 77 +++++++- crates/engine/src/player.rs | 27 +++ crates/engine/src/preview.rs | 113 +++++++++++ crates/engine/src/state.rs | 3 + crates/engine/tests/preview.rs | 338 +++++++++++++++++++++++++++++++++ docs/audio-output.md | 25 +++ 25 files changed, 1106 insertions(+), 65 deletions(-) create mode 100644 crates/app/src/preview.rs create mode 100644 crates/engine/src/preview.rs create mode 100644 crates/engine/tests/preview.rs diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index 83a970b..d6f3969 100644 --- a/crates/app/src/app.rs +++ b/crates/app/src/app.rs @@ -16,6 +16,7 @@ pub enum View { /// Library data cached for the UI (refreshed on job events). #[derive(Default)] pub struct Shared { + pub preview: crate::preview::PreviewState, pub tracks: Vec, pub by_id: HashMap, pub analyses: HashMap, @@ -294,6 +295,9 @@ impl App { self.studio.playing = false; } } + if self.eng.preview_player.is_none() { self.sh.preview.item = None; } + self.sh.preview.output = self.prefs.preview_output; + self.sh.preview.loading = self.eng.preview_player.is_some() && self.eng.state().preview.waiting; // the track a preview would start on, loaded ahead so Space plays at once if self.view == View::Studio && self.eng.studio_player.is_none() { if let Some(t) = self.studio.track_at_playhead().and_then(|i| self.studio.mix.tracks.get(i)) { @@ -329,8 +333,8 @@ impl App { } let st = self.eng.state(); self.settings.tick(&st); - if self.eng.preview_player.is_some() && st.mix.active { - self.studio.preview_pos = st.mix.time; + if self.eng.preview_player.is_some() && st.preview.active { + self.studio.preview_pos = st.preview.time; } self.decks = (0..2).map(|d| crate::live::adapter::deck_ui(&st, d, &self.sh, &Default::default(), self.eng.is_loading(d))).collect(); self.mixer = crate::live::adapter::mixer_ui(&st, &self.eng); @@ -402,6 +406,7 @@ impl App { self.studio.add_tracks(&self.sh, &ids); self.view = View::Studio; } + LibraryAction::Preview(item) => self.preview_track(item, None), LibraryAction::LoadDeck(id, deck) => self.load_to_deck(id, deck), } } @@ -446,6 +451,8 @@ impl App { } let p = self.prefs.clone(); let first = self.applied_prefs.is_none(); + if self.applied_prefs.as_ref().is_some_and(|old| old.preview_output != p.preview_output) { self.stop_preview(); } + self.sh.preview.output = p.preview_output; crate::theme::set_key_notation(p.key_notation); crate::theme::set_soft_stems(p.soft_stem_colors); if first || self.applied_prefs.as_ref().map(|o| o.accent) != Some(p.accent) { @@ -661,27 +668,72 @@ impl App { } } + fn start_preview(&mut self, mix: &clubcraft_core::Mix, from: f64, item: crate::preview::PreviewItem) { + match self.eng.play_preview(mix, from, &self.sh) { + Ok(()) => { + self.sh.preview.item = Some(item); + self.sh.preview.mix_serial = self.studio.mix_serial; + self.sh.preview.mashup_revision = self.studio.mashup.revision; + self.status = format!("Preview in {}: {}", self.prefs.preview_output.label(), self.sh.track(item.track).map(|t| t.display_name()).unwrap_or_default()); + } + Err(e) => self.status = format!("Preview: {e:#}"), + } + } + + fn stop_preview(&mut self) { + self.eng.stop_preview(); + self.sh.preview.item = None; + } + + fn preview_track(&mut self, item: crate::preview::PreviewItem, from: Option) { + if from.is_none() && self.sh.preview.item == Some(item) { self.stop_preview(); return; } + let id = item.track; + let a = self.sh.analyses.get(&id); + let dur = a.map(|a| a.duration).filter(|d| *d > 0.0).or_else(|| self.sh.track(id).map(|t| t.duration)).unwrap_or(0.0); + let from = from.unwrap_or_else(|| crate::track_picker::preview_start(a, dur)); + let mut mix = clubcraft_core::Mix { name: "Preview".into(), tempo: clubcraft_core::TempoMode::Glide, ..Default::default() }; + mix.tracks.push(clubcraft_core::MixTrack { track_id: id, mix_in: 0.0, mix_out: dur.max(1.0), key_shift: 0, gain_db: 0.0, stems: Vec::new() }); + mix.normalize(); + self.start_preview(&mix, from.clamp(0.0, dur.max(0.0)), item); + } + + fn reconcile_preview(&mut self) { + use crate::preview::PreviewSource as P; + let Some(item) = self.sh.preview.item else { return; }; + let visible = match item.source { + P::Library { playlist, mix } => self.view == View::Library && playlist == self.library.playlist && mix == self.library.mix, + P::LiveBrowser { playlist, mix } => self.view == View::Live && playlist == self.browser.playlist && mix == self.browser.mix, + P::LiveQueue => self.view == View::Live && self.eng.automix_queue.get(item.row) == Some(&item.track), + P::Playlist => self.view == View::Studio && self.studio.tab == Some(crate::studio::Tab::Playlist) + && self.studio.mix.tracks.get(item.row).is_some_and(|t| t.track_id == item.track), + P::Mashups => self.view == View::Studio && self.studio.tab == Some(crate::studio::Tab::Mashups) && self.studio.mashup.open && self.sh.preview.mashup_revision == self.studio.mashup.revision && self.studio.mashup.has_preview_row(item.row, item.track), + P::AddTracks => self.view == View::Studio && self.studio.picker.open, + }; + let studio = matches!(item.source, P::Playlist | P::Mashups | P::AddTracks); + if !visible || (studio && self.sh.preview.mix_serial != self.studio.mix_serial) { self.stop_preview(); } + } + fn handle_mashup_actions(&mut self, actions: Vec) { use crate::mashup_view::MashupAction as M; let short = |sh: &Shared, id: TrackId| sh.track(id).map(|t| if t.title.is_empty() { t.display_name() } else { t.title.clone() }).unwrap_or_default(); for a in actions { match a { - M::Preview(m) => { + M::Preview(m, row) => { if let Some(mix) = crate::mashup::mashup_mix("Preview", &m, &self.sh.analyses, 4) { let tl = clubcraft_core::MixTimeline::build(&mix, &|id| self.sh.analyses.get(&id).cloned()); let bar = self.sh.analyses.get(&m.vocal_track).and_then(|a| a.grid).map(|g| g.bar_len()).unwrap_or(2.0); let from = tl.transitions.first().map(|t| (t.start_sec - 2.0 * bar).max(0.0)).unwrap_or(0.0); - self.eng.play_preview(&mix, from, &self.sh); - self.status = format!("Preview: vocals of {} over {}", short(&self.sh, m.vocal_track), short(&self.sh, m.inst_track)); + let item = crate::preview::PreviewItem { source: crate::preview::PreviewSource::Mashups, track: m.vocal_track, row }; + self.start_preview(&mix, from, item); } } - M::StopPreview => self.eng.stop_preview(), + M::StopPreview => self.stop_preview(), M::SeparateBest(id) => { self.jobs.separate_at(id, "best"); self.status = format!("Separating {} in Best quality…", short(&self.sh, id)); } M::NewMix(m) => { - self.eng.stop_preview(); + self.stop_preview(); self.save_mix(); let name = format!("{} × {}", short(&self.sh, m.vocal_track), short(&self.sh, m.inst_track)); if let Some(mut mix) = crate::mashup::mashup_mix(&name, &m, &self.sh.analyses, 16) { @@ -705,7 +757,7 @@ impl App { self.studio.selection = crate::studio::Selection::Transition(k); self.view = View::Studio; self.studio.mashup.open = false; - self.eng.stop_preview(); + self.stop_preview(); self.status = "Mashup inserted into the mix".into(); } } @@ -716,7 +768,7 @@ impl App { self.studio.selection = crate::studio::Selection::Transition(k); self.status = "Transition set to the mashup".into(); self.studio.mashup.open = false; - self.eng.stop_preview(); + self.stop_preview(); } } } @@ -729,19 +781,14 @@ impl App { match a { A::SaveMix => self.save_mix(), A::PreviewTrack(id, from) => { - // a one-track mix from the start of the file, so mix time is track time - let dur = self.sh.analyses.get(&id).map(|a| a.duration).filter(|d| *d > 0.0).or_else(|| self.sh.track(id).map(|t| t.duration)).unwrap_or(0.0); - let mut mix = clubcraft_core::Mix { name: "Preview".into(), tempo: clubcraft_core::TempoMode::Glide, ..Default::default() }; - mix.tracks.push(clubcraft_core::MixTrack { track_id: id, mix_in: 0.0, mix_out: dur.max(1.0), key_shift: 0, gain_db: 0.0, stems: Vec::new() }); - mix.normalize(); - self.studio.playing = false; - self.eng.play_preview(&mix, from.clamp(0.0, dur.max(0.0)), &self.sh); - self.status = format!("Preview: {}", self.sh.track(id).map(|t| t.display_name()).unwrap_or_default()); - } - A::StopPreview => { - self.eng.stop_preview(); - self.status.clear(); + self.preview_track(crate::preview::PreviewItem { source: crate::preview::PreviewSource::AddTracks, track: id, row: 0 }, Some(from)); + } + A::PreviewPlaylist(row) => { + if let Some(t) = self.studio.mix.tracks.get(row) { + self.preview_track(crate::preview::PreviewItem { source: crate::preview::PreviewSource::Playlist, track: t.track_id, row }, None); + } } + A::StopPreview => self.stop_preview(), A::DuplicateMix => { if !self.save_mix_now() { continue; @@ -1018,7 +1065,7 @@ impl App { use crate::mashup_view::MashupAction as M; if let Some(m) = self.studio.mashup.result(arg.trim().parse().unwrap_or(0)) { let a = match c { - "mashup-preview" => M::Preview(m), + "mashup-preview" => M::Preview(m, 0), "mashup-newmix" => M::NewMix(m), _ => M::Apply(m, self.studio.mashup.transition_index().unwrap_or(0)), }; @@ -1447,6 +1494,7 @@ impl eframe::App for App { self.settings.message = self.eng.error.clone().unwrap_or_else(|| "Audio output started".into()); } self.apply_prefs(&ctx); + self.reconcile_preview(); for a in sa { match a { crate::settings::SettingsAction::ProcessAll => { @@ -1500,6 +1548,7 @@ fn live_browser(ui: &mut egui::Ui, browser: &mut LibraryView, sh: &Shared, queue queue.clear(); } }); + sh.preview.label(ui); let (rect, resp) = ui.allocate_exact_size(egui::vec2(270.0, ui.available_height().max(60.0)), egui::Sense::hover()); if let Some(p) = resp.dnd_release_payload::() { for id in &p.0 { @@ -1517,10 +1566,13 @@ fn live_browser(ui: &mut egui::Ui, browser: &mut LibraryView, sh: &Shared, queue egui::ScrollArea::vertical().id_salt("queue").show(&mut child, |ui| { for (i, id) in queue.iter().enumerate() { ui.horizontal(|ui| { + let item = crate::preview::PreviewItem { source: crate::preview::PreviewSource::LiveQueue, track: *id, row: i }; + if sh.preview.button(ui, item, true).clicked() { actions.push(LibraryAction::Preview(item)); } let name = sh.track(*id).map(|t| t.display_name()).unwrap_or_default(); let a = sh.analyses.get(id); ui.label(RichText::new(format!("{}.", i + 1)).color(theme::TEXT_DIM)); - ui.add(egui::Label::new(crate::studio::truncate(&name, 26)).truncate()); + let name_width = (ui.available_width() - 64.0).max(60.0); + ui.add_sized(egui::vec2(name_width, ui.spacing().interact_size.y), egui::Label::new(&name).truncate()); if let Some(k) = a.and_then(|a| a.key) { ui.label(RichText::new(crate::theme::key_label(k)).color(theme::key_color(k)).size(11.0)); } diff --git a/crates/app/src/library_view.rs b/crates/app/src/library_view.rs index b657631..7c021a4 100644 --- a/crates/app/src/library_view.rs +++ b/crates/app/src/library_view.rs @@ -40,6 +40,7 @@ impl Default for LibraryView { /// What the user asked to do with tracks from the table. #[derive(Debug, Clone)] pub enum LibraryAction { + Preview(crate::preview::PreviewItem), LoadDeck(TrackId, usize), AddToMix(Vec), Process(Vec), @@ -136,6 +137,10 @@ impl LibraryView { let n = if self.mix.is_some() || self.playlist.is_some() || !self.search.is_empty() { self.visible(sh).len() } else { sh.tracks.len() }; ui.label(RichText::new(format!("{n} tracks")).color(theme::TEXT_DIM)); }); + sh.preview.label(ui); + let source = if compact { + crate::preview::PreviewSource::LiveBrowser { playlist: self.playlist, mix: self.mix } + } else { crate::preview::PreviewSource::Library { playlist: self.playlist, mix: self.mix } }; let rows = self.visible(sh); let row_ids: Vec = rows.iter().map(|t| t.id).collect(); let mut table = TableBuilder::new(ui) @@ -143,6 +148,7 @@ impl LibraryView { .resizable(true) .sense(egui::Sense::click_and_drag()) .cell_layout(egui::Layout::left_to_right(egui::Align::Center)) + .column(Column::exact(24.0)) .column(Column::exact(18.0)) .column(Column::initial(if compact { 260.0 } else { 300.0 }).at_least(80.0).clip(true)) .column(Column::initial(if compact { 180.0 } else { 220.0 }).at_least(60.0).clip(true)) @@ -172,6 +178,7 @@ impl LibraryView { }; table .header(20.0, |mut h| { + h.col(|ui| header(ui, "", None)); h.col(|ui| header(ui, "", None)); h.col(|ui| header(ui, "Title", Some(SortBy::Title))); h.col(|ui| header(ui, "Artist", Some(SortBy::Artist))); @@ -190,6 +197,12 @@ impl LibraryView { let a: Option<&Analysis> = sh.analyses.get(&t.id); let sel = self.selected.contains(&t.id); row.set_selected(sel); + let mut preview_click = false; + row.col(|ui| { + let item = crate::preview::PreviewItem { source, track: t.id, row: 0 }; + preview_click = sh.preview.button(ui, item, true).clicked(); + if preview_click { actions.push(LibraryAction::Preview(item)); } + }); row.col(|ui| { let has_stems = a.and_then(|a| a.stems_model.as_ref()).is_some(); let c = if has_stems { theme::OK } else if a.is_some_and(|a| a.version > 0) { theme::TEXT_DIM } else { theme::LINE }; @@ -238,7 +251,7 @@ impl LibraryView { } }); let resp = row.response(); - if resp.clicked() { + if resp.clicked() && !preview_click { let (cmd, shift) = ui_mods(&resp.ctx); if shift { if let Some(last) = self.last_clicked { @@ -258,7 +271,7 @@ impl LibraryView { } self.last_clicked = Some(t.id); } - if resp.double_clicked() { + if resp.double_clicked() && !preview_click { actions.push(LibraryAction::LoadDeck(t.id, usize::MAX)); } if resp.drag_started() { @@ -314,3 +327,25 @@ impl LibraryView { fn ui_mods(ctx: &egui::Context) -> (bool, bool) { ctx.input(|i| (i.modifiers.command, i.modifiers.shift)) } + +#[cfg(test)] +mod preview_tests { + use super::*; + + #[test] + fn preview_click_in_library_and_live_does_not_select_or_load_a_deck() { + for compact in [false, true] { + let sh = Shared { tracks: vec![Track { id: 1, title: "First".into(), duration: 120.0, ..Default::default() }, Track { id: 2, title: "Second".into(), duration: 120.0, ..Default::default() }], ..Default::default() }; + let mut view = LibraryView::default(); + view.selected.insert(2); + let mut actions = Vec::new(); + crate::preview::test_ui::click_preview(|ui| view.ui(ui, &sh, compact, &mut actions)); + assert_eq!(view.selected, HashSet::from([2])); + assert_eq!(actions.len(), 1); + let LibraryAction::Preview(item) = &actions[0] else { panic!("only preview should run") }; + assert_eq!(item.track, 1); + let expected = if compact { crate::preview::PreviewSource::LiveBrowser { playlist: None, mix: None } } else { crate::preview::PreviewSource::Library { playlist: None, mix: None } }; + assert_eq!(item.source, expected); + } + } +} diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index 3c526a6..d9e5b18 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -379,7 +379,7 @@ pub struct LiveEngine { /// Mix player per deck pair (studio preview on C/D, live mix on A/B). pub studio_player: Option, pub live_player: Option, - /// Mashup finder preview (on the studio decks, independent of the studio mix). + /// Independent browser/mashup preview (private decks, separate transport). pub preview_player: Option, pub loading_mix: Option, pub export: Option, @@ -563,7 +563,6 @@ impl LiveEngine { /// Start playing `mix` on `decks`. Tracks are loaded just in time (only the current and the /// next couple of tracks are kept in memory). pub fn play_mix(&mut self, mix: &Mix, decks: [usize; 2], from: f64, sh: &Shared) { - self.stop_preview(); self.stop_mix(STUDIO_DECKS); self.stop_mix(LIVE_DECKS); let mut p = MixPlayer::lazy(mix, &|id| sh.analyses.get(&id).cloned(), decks); @@ -579,23 +578,31 @@ impl LiveEngine { } } - /// Play a short mix (a mashup preview) on the studio decks from `from` seconds. - pub fn play_preview(&mut self, mix: &Mix, from: f64, sh: &Shared) { + /// Play a browser/mashup preview on its private decks from `from` seconds. + pub fn play_preview(&mut self, mix: &Mix, from: f64, sh: &Shared) -> Result<()> { + use clubcraft_engine::command::PreviewOutput; + use clubcraft_engine::player::PreviewSink; + let output = self.prefs.preview_output; + let h = self.handle.as_ref().context("Audio output is unavailable")?; + if output == PreviewOutput::Headphones && !crate::preview::headphones_available(&h.stream_info()) { + anyhow::bail!("Headphone output is unavailable. Configure Audio output in Settings."); + } self.stop_preview(); - self.stop_mix(STUDIO_DECKS); - self.stop_mix(LIVE_DECKS); - let mut p = MixPlayer::lazy(mix, &|id| sh.analyses.get(&id).cloned(), STUDIO_DECKS); + let mut p = MixPlayer::lazy(mix, &|id| { + let mut a = sh.analyses.get(&id).cloned().unwrap_or_default(); + if a.duration <= 0.0 { a.duration = sh.track(id).map(|t| t.duration).unwrap_or(0.0); } + Some(a) + }, [0, 1]); if let Some(h) = self.handle.as_mut() { - if let Err(e) = p.play(h, from) { - log::warn!("preview: {e:#}"); - } + p.play(&mut PreviewSink { sink: h, output }, from)?; } self.preview_player = Some(p); + Ok(()) } pub fn stop_preview(&mut self) { if let (Some(mut p), Some(h)) = (self.preview_player.take(), self.handle.as_mut()) { - let _ = p.stop(h); + let _ = p.stop(&mut clubcraft_engine::player::PreviewSink { sink: h, output: self.prefs.preview_output }); } } @@ -702,11 +709,10 @@ impl LiveEngine { // Prefetch upcoming tracks of a playing mix. let st = self.state(); let loader = self.loader(); - for which in 0..3 { + for which in 0..2 { let player = match which { 0 => self.studio_player.as_mut(), - 1 => self.live_player.as_mut(), - _ => self.preview_player.as_mut(), + _ => self.live_player.as_mut(), }; let h = self.handle.as_mut(); if let (Some(p), Some(h)) = (player, h) { @@ -721,6 +727,29 @@ impl LiveEngine { } } } + let mut stop_preview = false; + let output = self.prefs.preview_output; + if let (Some(p), Some(h)) = (self.preview_player.as_mut(), self.handle.as_mut()) { + let mut preview_state = st; + preview_state.mix = st.preview; + if output == clubcraft_engine::command::PreviewOutput::Headphones && !crate::preview::headphones_available(&h.stream_info()) { + messages.push("Headphone output is unavailable; preview stopped".into()); + stop_preview = true; + } else if st.preview.schedule_id == p.schedule_id() && st.preview.finished { + stop_preview = true; + } else { + let mut sink = clubcraft_engine::player::PreviewSink { sink: h, output }; + match p.poll(&mut sink, &preview_state, &loader) { + Ok(status) if !status.failed.is_empty() => { + messages.push("Preview could not be loaded".into()); + stop_preview = true; + } + Err(e) => { messages.push(format!("Preview: {e:#}")); stop_preview = true; } + _ => {} + } + } + } + if stop_preview { self.stop_preview(); } // Persist hot cues the user set or moved. for d in 0..2 { let ds = &st.decks[d]; diff --git a/crates/app/src/live/view.rs b/crates/app/src/live/view.rs index a54b94d..0efe2ae 100644 --- a/crates/app/src/live/view.rs +++ b/crates/app/src/live/view.rs @@ -562,7 +562,7 @@ impl LiveView { if widgets::knob(ui, &mut f, 0.0..=1.0, 0.5, "FILTER", Color32::from_rgb(120, 220, 255), 31.0).changed() { out.push(LiveAction::Filter(i, f)); } - if widgets::toggle(ui, d.pfl, "🎧", accent, vec2(40.0, 20.0)).on_hover_text("Headphone cue").clicked() { + if widgets::toggle(ui, d.pfl, "🎧", accent, vec2(40.0, 20.0)).on_hover_text("Monitor this deck before its fader. CUE·MIX controls how much master is heard.").clicked() { out.push(LiveAction::Pfl(i, !d.pfl)); } ui.add_space(8.0); @@ -599,7 +599,7 @@ impl LiveView { ui.horizontal(|ui| { ui.add_space((ui.available_width() - 72.0).max(0.0) / 2.0); let mut hm = m.headphone_mix; - if widgets::knob(ui, &mut hm, 0.0..=1.0, 0.0, "CUE·MIX", theme::TEXT, 32.0).changed() { + if widgets::knob(ui, &mut hm, 0.0..=1.0, 0.0, "CUE·MIX", theme::TEXT, 32.0).on_hover_text("CUE: selected decks only; MIX: master. With no CUE selected, the CUE end is silent.").changed() { out.push(LiveAction::HeadphoneMix(hm)); } let mut hv = m.headphone_vol; diff --git a/crates/app/src/main.rs b/crates/app/src/main.rs index da941f3..c5e43e3 100644 --- a/crates/app/src/main.rs +++ b/crates/app/src/main.rs @@ -22,6 +22,7 @@ mod menu; mod pipeline; mod platform; mod prefs; +mod preview; mod settings; mod studio; mod studio_timeline; diff --git a/crates/app/src/mashup_view.rs b/crates/app/src/mashup_view.rs index 73feba6..4f42d42 100644 --- a/crates/app/src/mashup_view.rs +++ b/crates/app/src/mashup_view.rs @@ -21,7 +21,7 @@ pub enum Target { } pub enum MashupAction { - Preview(Match), + Preview(Match, usize), StopPreview, NewMix(Match), Insert(Match), @@ -56,6 +56,7 @@ pub struct MashupView { transition_bars: Option<(i32, i32)>, job: Option, results: Vec, + pub revision: u64, message: String, pub previewing: Option, run_next_frame: bool, @@ -81,6 +82,7 @@ impl Default for MashupView { transition_bars: None, job: None, results: Vec::new(), + revision: 0, message: String::new(), previewing: None, run_next_frame: false, @@ -116,6 +118,7 @@ impl MashupView { self.inst_only = None; self.transition_bars = None; self.auto_phrase = true; + self.revision = self.revision.wrapping_add(1); self.results.clear(); self.message.clear(); self.vocal = vocal.filter(|id| sh.analyses.get(id).is_some_and(|a| a.stems_model.is_some())); @@ -207,11 +210,16 @@ impl MashupView { }) .ok(); self.job = Some(Job { rx, progress, cancel }); + self.revision = self.revision.wrapping_add(1); self.results.clear(); self.previewing = None; self.message.clear(); } + pub fn has_preview_row(&self, row: usize, track: TrackId) -> bool { + self.results.get(row).is_some_and(|m| m.vocal_track == track) + } + /// Close the finder (cancels a running search and stops a preview). pub fn close(&mut self, out: &mut Vec) { self.open = false; @@ -243,13 +251,13 @@ impl MashupView { ui.ctx().request_repaint_after(std::time::Duration::from_millis(100)); } } - if !preview_playing { - self.previewing = None; - } + self.previewing = sh.preview.item.filter(|p| p.source == crate::preview::PreviewSource::Mashups && sh.preview.mashup_revision == self.revision).map(|p| p.row); + if !preview_playing { self.previewing = None; } self.contents(ui, sh, mix, out); } fn contents(&mut self, ui: &mut Ui, sh: &Shared, mix: &Mix, out: &mut Vec) { + sh.preview.label(ui); let with_stems: Vec = sh.tracks.iter().filter(|t| sh.analyses.get(&t.id).is_some_and(|a| a.stems_model.is_some() && a.grid.is_some())).map(|t| t.id).collect(); // ------------------------------------------------ query let mut close = false; @@ -411,12 +419,12 @@ impl MashupView { ui.label(m.learned.map(|l| format!("{:.0}", l * 100.0)).unwrap_or_else(|| "–".into())); ui.horizontal(|ui| { let playing = self.previewing == Some(i); - if ui.button(if playing { "■" } else { "▶" }).on_hover_text(if playing { "Stop" } else { "Preview: vocals over this instrumental" }).clicked() { + if sh.preview.button(ui, crate::preview::PreviewItem { source: crate::preview::PreviewSource::Mashups, track: m.vocal_track, row: i }, true).on_hover_text(if playing { "Stop" } else { "Preview: vocals over this instrumental" }).clicked() { if playing { out.push(MashupAction::StopPreview); self.previewing = None; } else { - out.push(MashupAction::Preview(m.clone())); + out.push(MashupAction::Preview(m.clone(), i)); self.previewing = Some(i); } } diff --git a/crates/app/src/prefs.rs b/crates/app/src/prefs.rs index fd4818f..f347a3a 100644 --- a/crates/app/src/prefs.rs +++ b/crates/app/src/prefs.rs @@ -124,6 +124,7 @@ impl AudioFormat { #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] #[serde(default)] pub struct Prefs { + pub preview_output: clubcraft_engine::command::PreviewOutput, // ------------------------------------------------------------ general / display pub key_notation: KeyNotation, /// UI zoom (1.0 = 100 %). @@ -187,6 +188,7 @@ pub struct Prefs { impl Default for Prefs { fn default() -> Self { Prefs { + preview_output: Default::default(), key_notation: KeyNotation::Camelot, ui_scale: 1.0, start_on_home: true, @@ -328,6 +330,17 @@ impl Prefs { mod migration_tests { use super::*; + #[test] + fn preview_output_defaults_to_master_and_round_trips() { + use clubcraft_engine::command::PreviewOutput; + let old: Prefs = serde_json::from_str(r#"{"version": 3}"#).unwrap(); + assert_eq!(old.preview_output, PreviewOutput::Master); + assert_eq!(Prefs::default().preview_output, PreviewOutput::Master); + let prefs = Prefs { preview_output: PreviewOutput::Headphones, ..Default::default() }; + let loaded: Prefs = serde_json::from_str(&serde_json::to_string(&prefs).unwrap()).unwrap(); + assert_eq!(loaded.preview_output, PreviewOutput::Headphones); + } + #[test] fn old_files_get_the_white_accent() { let old: Prefs = serde_json::from_str(r#"{"accent": "Pink", "ui_scale": 1.2}"#).unwrap(); diff --git a/crates/app/src/preview.rs b/crates/app/src/preview.rs new file mode 100644 index 0000000..66a1943 --- /dev/null +++ b/crates/app/src/preview.rs @@ -0,0 +1,178 @@ +//! Shared browser preview identity and presentation. +use clubcraft_core::TrackId; +use clubcraft_engine::command::PreviewOutput; +use eframe::egui; + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub enum PreviewSource { + Library { + playlist: Option, + mix: Option, + }, + LiveBrowser { + playlist: Option, + mix: Option, + }, + LiveQueue, + Playlist, + Mashups, + AddTracks, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PreviewItem { + pub source: PreviewSource, + pub track: TrackId, + pub row: usize, +} + +#[derive(Default)] +pub struct PreviewState { + pub item: Option, + pub output: PreviewOutput, + pub loading: bool, + pub mix_serial: u64, + pub mashup_revision: u64, +} + +impl PreviewState { + pub fn playing(&self, source: PreviewSource, track: TrackId, row: usize) -> bool { + self.item == Some(PreviewItem { source, track, row }) + } + + pub fn label(&self, ui: &mut egui::Ui) { + ui.label( + egui::RichText::new(format!("Preview: {}", self.output.label())) + .small() + .color(crate::theme::TEXT_DIM), + ); + } + + pub fn button(&self, ui: &mut egui::Ui, item: PreviewItem, enabled: bool) -> egui::Response { + let playing = self.playing(item.source, item.track, item.row); + crate::widgets::preview_button(ui, playing, enabled, crate::theme::PREVIEW_BUTTON_SIZE) + .on_hover_text(if playing { + if self.loading { + "Loading preview - click to stop".to_string() + } else { + "Stop preview".to_string() + } + } else if item.source == PreviewSource::Mashups { + format!( + "Preview vocals over this instrumental in {}", + self.output.label() + ) + } else { + format!("Preview in {} from the first drop", self.output.label()) + }) + } +} + +pub fn headphones_available(info: &clubcraft_engine::StreamInfo) -> bool { + info.cue_channels.is_some() + && !info.master.failed + && info.headphones.as_ref().is_none_or(|h| !h.failed) +} + +#[cfg(test)] +pub(crate) mod test_ui { + use eframe::egui::{self, Event, Modifiers, PointerButton, RawInput}; + + pub fn click_preview(mut draw: impl FnMut(&mut egui::Ui)) { + let ctx = egui::Context::default(); + let mut frame = |events: Vec| { + let input = RawInput { + screen_rect: Some(egui::Rect::from_min_size( + egui::Pos2::ZERO, + egui::vec2(1600.0, 900.0), + )), + events, + ..Default::default() + }; + let mut output = ctx.run_ui(input, |ui| draw(ui)); + output.textures_delta.clear(); + }; + frame(vec![]); + frame(vec![]); + let rect = ctx + .interactive_rects_last_pass() + .into_iter() + .find(|r| { + (r.width() - crate::theme::PREVIEW_BUTTON_SIZE).abs() < 0.1 + && (r.height() - crate::theme::PREVIEW_BUTTON_SIZE).abs() < 0.1 + }) + .expect("preview button is visible"); + let pos = rect.center(); + frame(vec![ + Event::PointerMoved(pos), + Event::PointerButton { + pos, + button: PointerButton::Primary, + pressed: true, + modifiers: Modifiers::default(), + }, + ]); + frame(vec![Event::PointerButton { + pos, + button: PointerButton::Primary, + pressed: false, + modifiers: Modifiers::default(), + }]); + } +} + +#[cfg(test)] +mod tests { + use super::*; + use clubcraft_engine::{EndpointInfo, StreamInfo}; + + fn output() -> StreamInfo { + let endpoint = EndpointInfo { + device: "test".into(), + id: "test".into(), + sample_rate: 44100, + channels: 2, + sample_format: "f32".into(), + requested_buffer_frames: None, + observed_buffer_frames: None, + estimated_latency_ms: None, + failed: false, + errors: 0, + }; + StreamInfo { + device: "test".into(), + sample_rate: 44100, + channels: 2, + buffer_frames: None, + master_channels: [0, 1], + cue_channels: None, + split: false, + master: endpoint, + headphones: None, + warning: None, + cue_underruns: 0, + cue_overflows: 0, + estimated_offset_ms: None, + master_delay_ms: 0.0, + cue_delay_ms: 0.0, + } + } + + #[test] + fn preview_requires_a_running_cue_output_not_just_a_saved_selection() { + let mut info = output(); + assert!(!headphones_available(&info)); + info.cue_channels = Some([2, 3]); + assert!(headphones_available(&info)); + info.split = true; + info.cue_channels = Some([0, 1]); + assert!(headphones_available(&info)); + info.headphones = Some(info.master.clone()); + assert!(headphones_available(&info)); + info.headphones.as_mut().unwrap().failed = true; + assert!(!headphones_available(&info)); + info.headphones = None; + info.master.failed = true; + assert!(!headphones_available(&info)); + } +} diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index 4eefc25..585f415 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -213,7 +213,7 @@ impl Settings { Tab::General => general_ui(ui, prefs), Tab::Decks => decks_ui(ui, prefs), Tab::Mixer => mixer_ui(ui, prefs), - Tab::Audio => self.audio_ui(ui, handle), + Tab::Audio => self.audio_ui(ui, handle, prefs), Tab::Waveforms => waveforms_ui(ui, prefs), Tab::Analysis => analysis_ui(ui, prefs, actions), Tab::Studio => studio_ui(ui, prefs), @@ -233,7 +233,19 @@ impl Settings { } } - fn audio_ui(&mut self, ui: &mut egui::Ui, handle: Option<&EngineHandle>) { + fn audio_ui(&mut self, ui: &mut egui::Ui, handle: Option<&EngineHandle>, prefs: &mut Prefs) { + use clubcraft_engine::command::PreviewOutput; + section(ui, "Preview"); + ui.horizontal(|ui| { + ui.label("Preview output"); + ui.selectable_value(&mut prefs.preview_output, PreviewOutput::Headphones, "Headphones"); + ui.selectable_value(&mut prefs.preview_output, PreviewOutput::Master, "Master"); + }); + hint(ui, "Applies immediately to track and mashup previews. Changing the output stops the current preview."); + if prefs.preview_output == PreviewOutput::Headphones && handle.is_none_or(|h| !crate::preview::headphones_available(&h.stream_info())) { + ui.colored_label(theme::WARN, "Headphone output is unavailable. Configure and Apply an output below to preview in headphones."); + } + ui.add_space(8.0); section(ui, "Audio output"); if self.devices.is_empty() { self.devices = clubcraft_engine::devices().unwrap_or_default(); diff --git a/crates/app/src/studio.rs b/crates/app/src/studio.rs index 0fb0c52..eb9fc62 100644 --- a/crates/app/src/studio.rs +++ b/crates/app/src/studio.rs @@ -34,6 +34,7 @@ pub enum StudioAction { DeleteSavepoint(i64), /// Listen to a library track from this many seconds (the "Add tracks" dialog). PreviewTrack(TrackId, f64), + PreviewPlaylist(usize), StopPreview, } @@ -777,6 +778,7 @@ impl StudioView { } ui.label(RichText::new(format!("{} tracks · {} · drag ☰ to reorder", self.mix.tracks.len(), theme::fmt_time_short(self.timeline.total_secs))).size(11.0).color(theme::TEXT_DIM)); }); + sh.preview.label(ui); ui.add_space(4.0); if self.mix.tracks.is_empty() { ui.label(RichText::new("No tracks yet: use + Add tracks, or drag tracks here from the Library.").color(theme::TEXT_DIM)); @@ -805,6 +807,7 @@ impl StudioView { .striped(true) .sense(Sense::click()) .cell_layout(Layout::left_to_right(Align::Center)) + .column(egui_extras::Column::exact(28.0)) .column(egui_extras::Column::exact(22.0)) .column(egui_extras::Column::exact(14.0)) .column(egui_extras::Column::exact(30.0)) @@ -819,7 +822,7 @@ impl StudioView { .column(egui_extras::Column::exact(70.0)) .column(egui_extras::Column::exact(28.0)) .header(20.0, |mut h| { - for t in ["", "", "#", "TITLE", "ARTIST", "GENRE", "TRANSITION IN", "TIME", "KEY", "MATCH", "NRG", "BPM", ""] { + for t in ["", "", "", "#", "TITLE", "ARTIST", "GENRE", "TRANSITION IN", "TIME", "KEY", "MATCH", "NRG", "BPM", ""] { h.col(|ui| { ui.label(RichText::new(t).size(10.5).color(theme::TEXT_DIM)); }); @@ -842,6 +845,13 @@ impl StudioView { egui::Painter::new(ui.ctx().clone(), ui.layer_id(), r).rect_filled(r, 0.0, c); } }; + let mut preview_click = false; + row.col(|ui| { + tint(ui); + let item = crate::preview::PreviewItem { source: crate::preview::PreviewSource::Playlist, track: mt.track_id, row: i }; + preview_click = sh.preview.button(ui, item, t.is_some()).clicked(); + if preview_click { self.pending.push(StudioAction::PreviewPlaylist(i)); } + }); row.col(|ui| { tint(ui); let tip = if linked.is_some() { "Drag to reorder (with the tracks linked to it)" } else { "Drag to reorder" }; @@ -982,7 +992,7 @@ impl StudioView { if r.dnd_hover_payload::().is_some() { ui_line(&r); } - if r.clicked() { + if r.clicked() && !preview_click { select = Some(Selection::Track(i)); } }); @@ -2026,3 +2036,23 @@ mod tests { assert!(s.recutting.is_empty(), "cut again: {:?}", s.recutting); } } + +#[cfg(test)] +mod preview_tests { + use super::*; + + #[test] + fn playlist_preview_click_does_not_select_edit_or_start_the_mix() { + let mut sh = Shared { tracks: vec![clubcraft_core::Track { id: 1, title: "First".into(), duration: 120.0, ..Default::default() }], ..Default::default() }; + sh.by_id.insert(1, 0); + let mut studio = StudioView::default(); + studio.mix.tracks.push(MixTrack { track_id: 1, mix_in: 0.0, mix_out: 120.0, key_shift: 0, gain_db: 0.0, stems: Vec::new() }); + studio.selection = Selection::None; + let before = studio.mix.clone(); + crate::preview::test_ui::click_preview(|ui| studio.playlist_panel(ui, &sh)); + assert_eq!(studio.pending, vec![StudioAction::PreviewPlaylist(0)]); + assert_eq!(studio.selection, Selection::None); + assert_eq!(studio.mix, before); + assert!(!studio.playing); + } +} diff --git a/crates/app/src/theme.rs b/crates/app/src/theme.rs index 4960bed..7f3562f 100644 --- a/crates/app/src/theme.rs +++ b/crates/app/src/theme.rs @@ -1,6 +1,9 @@ use eframe::egui::{self, Color32, CornerRadius, FontFamily, FontId, Stroke, TextStyle, Visuals}; use std::sync::atomic::{AtomicBool, AtomicU32, Ordering}; +/// Compact Play/Stop control shared by browser preview lists. +pub const PREVIEW_BUTTON_SIZE: f32 = 18.0; + pub const BG: Color32 = Color32::from_rgb(14, 15, 18); pub const PANEL: Color32 = Color32::from_rgb(24, 26, 31); pub const PANEL_HI: Color32 = Color32::from_rgb(34, 37, 44); diff --git a/crates/app/src/track_picker.rs b/crates/app/src/track_picker.rs index 180b892..db2b14e 100644 --- a/crates/app/src/track_picker.rs +++ b/crates/app/src/track_picker.rs @@ -88,9 +88,8 @@ impl TrackPicker { if !self.open { return; } - if !preview_playing { - self.previewing = None; - } + self.previewing = sh.preview.item.filter(|p| p.source == crate::preview::PreviewSource::AddTracks).map(|p| p.track); + if !preview_playing { self.previewing = None; } let last_a = last.and_then(|id| sh.analyses.get(&id)); let q = self.query.to_lowercase(); let mut rows: Vec<(&Track, Option<&Analysis>, Option<(f32, f64)>)> = sh @@ -162,6 +161,7 @@ impl TrackPicker { }); }); ui.add_space(10.0); + sh.preview.label(ui); self.preview_strip(ui, sh, preview_pos, out); ui.add_space(10.0); // the track table @@ -209,7 +209,7 @@ impl TrackPicker { row.set_selected(sel || playing); let mut preview_click = false; row.col(|ui| { - preview_click = crate::widgets::play_button(ui, playing, a.is_some(), 24.0).on_hover_text(if playing { "Stop" } else { "Listen from the drop" }).clicked(); + preview_click = sh.preview.button(ui, crate::preview::PreviewItem { source: crate::preview::PreviewSource::AddTracks, track: t.id, row: 0 }, true).on_hover_text(if playing { "Stop" } else { "Listen from the drop" }).clicked(); }); row.col(|ui| { if tick_box(ui, sel).clicked() { diff --git a/crates/app/src/widgets.rs b/crates/app/src/widgets.rs index 140e4df..a815dd2 100644 --- a/crates/app/src/widgets.rs +++ b/crates/app/src/widgets.rs @@ -239,6 +239,15 @@ pub fn vu(ui: &mut Ui, l: f32, r: f32, size: egui::Vec2) { /// Round play / pause button with a drawn (optically centred) symbol. pub fn play_button(ui: &mut Ui, playing: bool, enabled: bool, d: f32) -> Response { + transport_button(ui, playing, enabled, d, false) +} + +/// Browser preview uses Stop, while the main transport uses Pause. +pub fn preview_button(ui: &mut Ui, playing: bool, enabled: bool, d: f32) -> Response { + transport_button(ui, playing, enabled, d, true) +} + +fn transport_button(ui: &mut Ui, playing: bool, enabled: bool, d: f32, stop: bool) -> Response { let (rect, resp) = ui.allocate_exact_size(egui::vec2(d, d), if enabled { Sense::click() } else { Sense::hover() }); let p = ui.painter(); let c = rect.center(); @@ -246,7 +255,9 @@ pub fn play_button(ui: &mut Ui, playing: bool, enabled: bool, d: f32) -> Respons p.circle_filled(c, d * 0.5, fill); let ink = Color32::from_gray(16); let s = d * 0.36; - if playing { + if playing && stop { + p.rect_filled(egui::Rect::from_center_size(c, egui::vec2(s, s)), 1.5, ink); + } else if playing { let (w, h) = (s * 0.3, s * 0.95); for dx in [-s * 0.27, s * 0.27] { p.rect_filled(egui::Rect::from_center_size(c + egui::vec2(dx, 0.0), egui::vec2(w, h)), 1.5, ink); diff --git a/crates/engine/src/command.rs b/crates/engine/src/command.rs index a9d72ef..59d214d 100644 --- a/crates/engine/src/command.rs +++ b/crates/engine/src/command.rs @@ -22,6 +22,20 @@ pub enum EqBand { High = 2, } +/// Destination of the independent browser preview. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +pub enum PreviewOutput { + Headphones, + #[default] + Master, +} + +impl PreviewOutput { + pub fn label(self) -> &'static str { + match self { Self::Headphones => "Headphones", Self::Master => "Master" } + } +} + /// Every action the engine understands. #[derive(Debug)] pub enum Command { @@ -177,6 +191,15 @@ pub enum Command { /// allocation free: send it on every knob movement. SetMixLanes([clubcraft_core::LaneSettings; clubcraft_core::MIX_LANES]), + // Independent preview commands never address the main mix or its decks. + PreviewPlay { schedule: Box, start: f64, output: PreviewOutput }, + PreviewStop, + PreviewSeek(f64), + PreviewPause, + PreviewResume, + PreviewSetLanes([clubcraft_core::LaneSettings; clubcraft_core::MIX_LANES]), + PreviewTrackReady { schedule: u64, index: usize, track: Arc }, + // ---------------------------------------------------------------- engine /// 2 or 4 decks. SetDeckCount(usize), diff --git a/crates/engine/src/core.rs b/crates/engine/src/core.rs index 76a4770..b9b0b1a 100644 --- a/crates/engine/src/core.rs +++ b/crates/engine/src/core.rs @@ -39,6 +39,7 @@ pub struct EngineCore { master: Option, quantize_beats: f64, conductor: Conductor, + preview: crate::preview::PreviewRenderer, garbage: Option>, recorder: Option>, rec_frames: u64, @@ -74,6 +75,7 @@ impl EngineCore { master: None, quantize_beats: 1.0, conductor: Conductor::default(), + preview: crate::preview::PreviewRenderer::new(sample_rate), garbage: None, recorder: None, rec_frames: 0, @@ -129,12 +131,14 @@ impl EngineCore { self.mixer.headphone_mix = old.headphone_mix; self.mixer.headphone_gain_db = old.headphone_gain_db; self.mixer.auto_gain = old.auto_gain; + self.mixer.preview_output = old.preview_output; self.mixer.limiter.enabled = old.limiter.enabled; self.mixer.limiter.set_ceiling_db(crate::dsp::gain_to_db(old.limiter.ceiling())); for d in self.decks.iter_mut() { d.set_output_rate(sr); } self.ctxs = [FxCtx::free(sr as f32); MAX_DECKS]; + self.preview.set_sample_rate(sr); self.sr = sr; } @@ -388,6 +392,30 @@ impl EngineCore { } } } + PreviewPlay { schedule, start, output } => { + if schedule.decks == [0, 1] && !schedule.is_empty() { + self.mixer.preview_output = output; + let garbage = &mut self.garbage; + let old = self.preview.start(schedule, start, &mut |t| Self::dispose(garbage, Garbage::Track(t))); + if let Some(old) = old { Self::dispose(&mut self.garbage, Garbage::Schedule(old)); } + } else { Self::dispose(&mut self.garbage, Garbage::Schedule(schedule)); } + } + PreviewStop => { + let garbage = &mut self.garbage; + let old = self.preview.stop(&mut |t| Self::dispose(garbage, Garbage::Track(t))); + if let Some(old) = old { Self::dispose(&mut self.garbage, Garbage::Schedule(old)); } + } + PreviewSeek(t) => self.preview.conductor.seek(t), + PreviewPause => self.preview.conductor.pause(&mut self.preview.decks, &mut self.preview.mixer), + PreviewResume => { + if self.preview.conductor.sched.is_some() { self.preview.conductor.playing = true; } + } + PreviewSetLanes(lanes) => self.preview.conductor.set_lanes(lanes), + PreviewTrackReady { schedule, index, track } => { + if let Some(t) = self.preview.conductor.set_track(schedule, index, track) { + Self::dispose(&mut self.garbage, Garbage::Track(t)); + } + } PlayMix { schedule, start } => { let mut ok = schedule.decks.iter().all(|d| *d < MAX_DECKS) && schedule.decks[0] != schedule.decks[1]; ok &= !schedule.is_empty(); @@ -565,6 +593,10 @@ impl EngineCore { } } let tm = std::time::Instant::now(); + { + let garbage = &mut self.garbage; + self.preview.process(self.sr, n, &mut self.mixer.preview, &mut |t| Self::dispose(garbage, Garbage::Track(t))); + } self.mixer.process(&mut self.deck_bufs, &self.ctxs, active, n, &mut self.master_buf, &mut self.cue_buf); self.prof[6] += tm.elapsed().as_micros() as u32; if let Some(rec) = &mut self.recorder { @@ -644,6 +676,7 @@ impl EngineCore { st.quantize_beats = self.quantize_beats; st.auto_gain = m.auto_gain; st.mix = self.conductor.state(); + st.preview = self.preview.state(); st.recording.active = self.recorder.is_some(); st.recording.seconds = self.rec_frames as f64 / self.sr as f64; st.recording.dropped = self.rec_dropped; diff --git a/crates/engine/src/deck.rs b/crates/engine/src/deck.rs index 29b92e3..d76e1f6 100644 --- a/crates/engine/src/deck.rs +++ b/crates/engine/src/deck.rs @@ -474,6 +474,14 @@ impl Deck { self.src.track.replace(track) } + /// Independent auditions never crossfade audio from a previous session/output. + pub(crate) fn clear_preview_history(&mut self) { + self.cur_path = Path::Silent; + self.xf_active = false; + self.stretch_live = false; + self.stem_echo.clear(); + } + /// Eject the track. Returns it for deferred dropping. pub fn unload(&mut self) -> Option> { self.capture_tail(); diff --git a/crates/engine/src/dsp.rs b/crates/engine/src/dsp.rs index 57ecdb9..4ffc507 100644 --- a/crates/engine/src/dsp.rs +++ b/crates/engine/src/dsp.rs @@ -244,6 +244,12 @@ impl Eq3 { Eq3 { ch: [c, c], gains: [Smoother::new(1.0, 0.01, sample_rate); 3] } } + pub(crate) fn clear_history(&mut self) { + for c in &mut self.ch { + for band in [&mut c.lp1a, &mut c.lp1b, &mut c.ap2, &mut c.hp1a, &mut c.hp1b, &mut c.lp2a, &mut c.lp2b, &mut c.hp2a, &mut c.hp2b] { band.reset(); } + } + } + /// Knob positions 0..1 (0 = kill, 0.5 = unity, 1 = +6 dB). pub fn set_knobs(&mut self, low: f32, mid: f32, high: f32) { self.gains[0].set(eq_knob_gain(low)); @@ -334,6 +340,13 @@ impl DjFilter { DjFilter { sr, knob: Smoother::new(0.5, 0.03, sr), resonance: 0.3, s1: Svf::default(), s2: Svf::default(), counter: 0, wet: 0.0, hp: false } } + pub(crate) fn clear_history(&mut self) { + self.s1.reset(); + self.s2.reset(); + self.wet = 0.0; + self.counter = 0; + } + /// Jump to the knob without smoothing. pub fn snap(&mut self) { self.knob.reset(self.knob.target); diff --git a/crates/engine/src/fx.rs b/crates/engine/src/fx.rs index 9a74a48..42cbcaa 100644 --- a/crates/engine/src/fx.rs +++ b/crates/engine/src/fx.rs @@ -177,6 +177,8 @@ impl Echo { pub fn clear(&mut self) { self.line.clear(); + self.lp = [0.0; 2]; + self.hp = [0.0; 2]; self.energy = 0.0; } @@ -275,6 +277,12 @@ impl Reverb { Reverb { combs: [cl, cr], aps: [al, ar], energy: 0.0 } } + pub(crate) fn clear(&mut self) { + for comb in self.combs.iter_mut().flatten() { comb.buf.fill(0.0); comb.i = 0; comb.store = 0.0; } + for ap in self.aps.iter_mut().flatten() { ap.buf.fill(0.0); ap.i = 0; } + self.energy = 0.0; + } + pub fn is_silent(&self) -> bool { self.energy < 1e-5 } @@ -661,6 +669,24 @@ impl LaneFx { } } + /// A new preview must not inherit audio from the previous audition. + pub(crate) fn clear_history(&mut self) { + self.reset(); + self.reverb_fx.clear(); + self.reverb_amt.reset(0.0); + self.noise_amt.reset(0.0); + self.brake_amt.reset(0.0); + self.noise_svf.reset(); + self.lp.state = LoopState::Idle; + self.lp.rec = 0; + self.lp.play = 0; + self.tape.fill([0.0; 2]); + self.tape_w = 0; + self.lag = 0.0; + self.resume = 1.0; + self.pump_env = 1.0; + } + /// All lane values back to neutral (tails keep ringing). pub fn reset(&mut self) { self.reverb = 0.0; diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index b6eb686..9f67157 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -41,6 +41,7 @@ pub mod fx; pub mod midi; pub mod mixer; pub mod player; +mod preview; pub mod render; pub mod samples; pub mod state; diff --git a/crates/engine/src/mixer.rs b/crates/engine/src/mixer.rs index 52db352..a48f1be 100644 --- a/crates/engine/src/mixer.rs +++ b/crates/engine/src/mixer.rs @@ -144,6 +144,15 @@ impl Channel { self.lane_fx.reset(); } + pub(crate) fn clear_preview_history(&mut self) { + self.reset_automation(); + self.eq.clear_history(); + self.filter.clear_history(); + self.send.clear(); + self.send_amt.reset(0.0); + self.lane_fx.clear_history(); + } + /// `buf`: deck audio in; on return holds the pre-fader (post-FX) signal for PFL. /// `post` receives the post-fader signal (crossfader gain `xf` applied) plus the echo send. pub fn process(&mut self, buf: &mut [f32], post: &mut [f32], ctx: &FxCtx, curve: FaderCurve, xf: f32, auto_gain_on: bool) { @@ -225,6 +234,10 @@ pub struct Mixer { /// Extra signal added to the master before its gain and limiter (sample lanes), `n` frames. pub extra: Vec, pub extra_on: bool, + /// Independent preview, inserted before master gain or after Cue/Master blending. + pub preview: Vec, + pub preview_output: crate::command::PreviewOutput, + /// One channel strip per sample lane, driven by its clips' curves. pub sample_channels: Vec, /// Each sample lane's audio of the block, and its channel output. @@ -252,6 +265,8 @@ impl Mixer { post: vec![0.0; MAX_BLOCK * 2], extra: vec![0.0; MAX_BLOCK * 2], extra_on: false, + preview: vec![0.0; MAX_BLOCK * 2], + preview_output: Default::default(), sample_channels: (0..clubcraft_core::SAMPLE_LANES).map(|_| Channel::new(sr)).collect(), sample_bufs: (0..clubcraft_core::SAMPLE_LANES).map(|_| vec![0.0; MAX_BLOCK * 2]).collect(), sample_post: vec![0.0; MAX_BLOCK * 2], @@ -270,9 +285,8 @@ impl Mixer { Levels { peak: self.hp_meter.peak, rms: self.hp_meter.rms() } } - /// Mix `active` deck buffers (each `n` frames interleaved, modified in place) into `master` - /// and `cue` (headphones, already blended with the master per `headphone_mix`). - pub fn process(&mut self, decks: &mut [Vec], ctxs: &[FxCtx], active: usize, n: usize, master: &mut [f32], cue: &mut [f32]) { + /// Channel strips and sample lanes, before either output bus applies gain or limiting. + pub(crate) fn process_channels(&mut self, decks: &mut [Vec], ctxs: &[FxCtx], active: usize, n: usize, master: &mut [f32], cue: &mut [f32]) { let master = &mut master[..n * 2]; let cue = &mut cue[..n * 2]; master.fill(0.0); @@ -284,7 +298,6 @@ impl Mixer { let (b0, b1) = self.xf_gain[1].advance(n); let fc = self.fader_curve; let ag = self.auto_gain; - let mut any_pfl = false; for (i, ch) in self.channels.iter_mut().enumerate().take(active) { let buf = &mut decks[i][..n * 2]; let xf = match ch.assign { @@ -298,7 +311,6 @@ impl Mixer { *m += *p; } if ch.pfl { - any_pfl = true; for (c, b) in cue.iter_mut().zip(buf.iter()) { *c += *b; } @@ -309,6 +321,16 @@ impl Mixer { *m += *e; } } + } + + /// Mix channels and preview into the final master and headphone output buses. + pub fn process(&mut self, decks: &mut [Vec], ctxs: &[FxCtx], active: usize, n: usize, master: &mut [f32], cue: &mut [f32]) { + self.process_channels(decks, ctxs, active, n, master, cue); + let master = &mut master[..n * 2]; + let cue = &mut cue[..n * 2]; + if self.preview_output == crate::command::PreviewOutput::Master { + for (m, p) in master.iter_mut().zip(&self.preview[..n * 2]) { *m += *p; } + } self.master_gain.set(db_to_gain(self.master_gain_db)); for f in master.as_chunks_mut::<2>().0 { let g = self.master_gain.next(); @@ -317,11 +339,12 @@ impl Mixer { } self.limiter.process(master); self.master_meter.process(master); - // headphones: cue bus blended with master (master only when nothing is cued) - let mix = if any_pfl { self.headphone_mix.clamp(0.0, 1.0) } else { 1.0 }; + // Only the Cue/Master control determines master monitoring, even with no PFL selected. + let mix = self.headphone_mix.clamp(0.0, 1.0); let hg = db_to_gain(self.headphone_gain_db); - for (c, m) in cue.iter_mut().zip(master.iter()) { - *c = soft_clip((*c * (1.0 - mix) + *m * mix) * hg); + for ((c, m), p) in cue.iter_mut().zip(master.iter()).zip(&self.preview[..n * 2]) { + let preview = if self.preview_output == crate::command::PreviewOutput::Headphones { *p } else { 0.0 }; + *c = soft_clip((*c * (1.0 - mix) + *m * mix + preview) * hg); } self.hp_meter.process(cue); } @@ -331,6 +354,42 @@ impl Mixer { mod tests { use super::*; + fn render(mixer: &mut Mixer) -> (Vec, Vec) { + let mut decks = vec![vec![0.1; MAX_BLOCK * 2]]; + let mut master = vec![0.0; MAX_BLOCK * 2]; + let mut cue = master.clone(); + mixer.process(&mut decks, &[FxCtx::free(44100.0)], 1, MAX_BLOCK, &mut master, &mut cue); + (master, cue) + } + + #[test] + fn no_pfl_is_silent_at_cue_and_master_monitoring_requires_the_mix_control() { + let mut mixer = Mixer::new(44100.0, 1); + let (master, cue) = render(&mut mixer); + assert!(master.iter().any(|v| v.abs() > 0.01)); + assert!(cue.iter().all(|v| *v == 0.0)); + for blend in [0.5, 1.0, 0.0] { + mixer.headphone_mix = blend; + let (master, cue) = render(&mut mixer); + assert!(master.iter().any(|v| v.abs() > 0.01)); + assert!(master.iter().zip(cue).all(|(m, c)| (c - m * blend).abs() < 1e-6)); + } + } + + #[test] + fn pfl_selection_controls_cue_before_the_channel_fader() { + let mut mixer = Mixer::new(44100.0, 1); + mixer.channels[0].fader = 0.0; + for _ in 0..20 { render(&mut mixer); } + mixer.channels[0].pfl = true; + let (master, cue) = render(&mut mixer); + assert!(master.iter().all(|v| v.abs() < 1e-6)); + assert!(cue.iter().any(|v| v.abs() > 0.01)); + mixer.channels[0].pfl = false; + let (_, cue) = render(&mut mixer); + assert!(cue.iter().all(|v| *v == 0.0)); + } + #[test] fn crossfader_curves() { let (a, b) = CrossfaderCurve::Smooth.gains(0.5); diff --git a/crates/engine/src/player.rs b/crates/engine/src/player.rs index cb434cc..dc7cd54 100644 --- a/crates/engine/src/player.rs +++ b/crates/engine/src/player.rs @@ -180,6 +180,10 @@ impl MixPlayer { } } + pub fn schedule_id(&self) -> u64 { + self.schedule_id + } + pub fn timeline(&self) -> &MixTimeline { &self.timeline } @@ -241,6 +245,7 @@ impl MixPlayer { /// Stop; the audio thread hands every resident track back for dropping. pub fn stop(&mut self, sink: &mut dyn CommandSink) -> Result<()> { self.schedule_id = 0; + if let Some(pf) = &self.prefetch { pf.want.lock().clear(); } self.target = None; self.sent.clear(); sink.submit(Command::MixStop) @@ -396,3 +401,25 @@ impl MixPlayer { state.mix.time } } + +/// Routes an existing mix player exclusively to the browser preview renderer. +pub struct PreviewSink<'a> { + pub sink: &'a mut dyn CommandSink, + pub output: crate::command::PreviewOutput, +} + +impl CommandSink for PreviewSink<'_> { + fn submit(&mut self, cmd: Command) -> Result<()> { + let cmd = match cmd { + Command::PlayMix { schedule, start } => Command::PreviewPlay { schedule, start, output: self.output }, + Command::MixStop => Command::PreviewStop, + Command::MixSeek(t) => Command::PreviewSeek(t), + Command::MixPause => Command::PreviewPause, + Command::MixResume => Command::PreviewResume, + Command::SetMixLanes(lanes) => Command::PreviewSetLanes(lanes), + Command::MixTrackReady { schedule, index, track } => Command::PreviewTrackReady { schedule, index, track }, + _ => return Err(anyhow!("unsupported preview transport command")), + }; + self.sink.submit(cmd) + } +} diff --git a/crates/engine/src/preview.rs b/crates/engine/src/preview.rs new file mode 100644 index 0000000..f7b161d --- /dev/null +++ b/crates/engine/src/preview.rs @@ -0,0 +1,113 @@ +//! Isolated preview decks. Rendered by the main callback, never enrolled in DJ sync. +use crate::conductor::{Conductor, MixSchedule}; +use crate::deck::Deck; +use crate::dsp::MAX_BLOCK; +use crate::fx::FxCtx; +use crate::mixer::Mixer; +use crate::state::MixPlaybackState; +use crate::track::LoadedTrack; +use std::sync::Arc; + +pub(crate) struct PreviewRenderer { + pub conductor: Conductor, + pub decks: Vec, + pub mixer: Mixer, + buffers: Vec>, + cue: Vec, +} + +impl PreviewRenderer { + pub fn new(sr: u32) -> Self { + let mixer = Mixer::new(sr as f32, 2); + Self { + conductor: Conductor::default(), + decks: (0..2).map(|_| Deck::new(sr)).collect(), + mixer, + buffers: (0..2).map(|_| vec![0.0; MAX_BLOCK * 2]).collect(), + cue: vec![0.0; MAX_BLOCK * 2], + } + } + + pub fn set_sample_rate(&mut self, sr: u32) { + self.mixer = Mixer::new(sr as f32, 2); + for deck in &mut self.decks { + deck.set_output_rate(sr); + } + } + + pub fn start( + &mut self, + schedule: Box, + start: f64, + drop_track: &mut dyn FnMut(Arc), + ) -> Option> { + for deck in &mut self.decks { + deck.clear_preview_history(); + } + for channel in &mut self.mixer.channels { + channel.clear_preview_history(); + } + self.conductor.start( + schedule, + start, + &mut self.decks, + &mut self.mixer, + drop_track, + ) + } + + pub fn stop( + &mut self, + drop_track: &mut dyn FnMut(Arc), + ) -> Option> { + let old = self + .conductor + .stop(&mut self.decks, &mut self.mixer, drop_track); + for deck in &mut self.decks { + if let Some(track) = deck.unload() { + drop_track(track); + } + deck.clear_preview_history(); + } + old + } + + pub fn state(&self) -> MixPlaybackState { + self.conductor.state() + } + + pub fn process( + &mut self, + sr: u32, + n: usize, + out: &mut [f32], + drop_track: &mut dyn FnMut(Arc), + ) { + out[..n * 2].fill(0.0); + self.conductor + .step(&mut self.decks, &mut self.mixer, n, sr as f64, drop_track); + if self.conductor.sched.is_none() || self.conductor.finished { + return; + } + let ctxs = std::array::from_fn::<_, 2, _>(|d| { + let deck = &self.decks[d]; + let bpm = deck.effective_bpm().unwrap_or(120.0).max(1.0); + FxCtx { + sr: sr as f32, + bpm, + beat: if deck.is_playing() { + deck.beat_position() + } else { + None + }, + beats_per_frame: bpm / 60.0 / sr as f64, + } + }); + for (deck, buf) in self.decks.iter_mut().zip(&mut self.buffers) { + deck.process(&mut buf[..n * 2]); + } + // Final gain/limiting belongs to the selected destination, not this private mixer. + self.mixer + .process_channels(&mut self.buffers, &ctxs, 2, n, out, &mut self.cue); + } +} diff --git a/crates/engine/src/state.rs b/crates/engine/src/state.rs index e7a5f98..ea6667e 100644 --- a/crates/engine/src/state.rs +++ b/crates/engine/src/state.rs @@ -296,6 +296,9 @@ pub struct EngineState { pub quantize_beats: f64, pub auto_gain: bool, pub mix: MixPlaybackState, + /// Independent browser/mashup preview; never owns the main decks. + #[serde(default)] + pub preview: MixPlaybackState, pub recording: RecordingState, /// Audio callback time / buffer duration (0..1+), smoothed. pub cpu_load: f32, diff --git a/crates/engine/tests/preview.rs b/crates/engine/tests/preview.rs new file mode 100644 index 0000000..7b7ba07 --- /dev/null +++ b/crates/engine/tests/preview.rs @@ -0,0 +1,338 @@ +//! Offline signal tests: these never open a device or touch the user's library. +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] +use clubcraft_audio::AudioBuffer; +use clubcraft_core::{BeatGrid, Mix, MixTrack, TempoMode, Transition, TransitionStyle}; +use clubcraft_engine::command::PreviewOutput; +use clubcraft_engine::conductor::MixSchedule; +use clubcraft_engine::player::PreviewSink; +use clubcraft_engine::*; +use std::sync::Arc; + +const SR: u32 = 44100; +const FRAMES: usize = 256; + +fn audio() -> Arc { + let samples: Vec = (0..SR * 6) + .map(|i| (i as f32 * 440.0 * std::f32::consts::TAU / SR as f32).sin() * 0.1) + .collect(); + Arc::new( + LoadedTrack::new( + "preview-test", + Arc::new(AudioBuffer::new(SR, samples.clone(), samples)), + ) + .with_grid(BeatGrid::new(120.0, 0.0)), + ) +} + +fn mix() -> Mix { + let mut mix = Mix { + tempo: TempoMode::Glide, + keylock: false, + ..Default::default() + }; + mix.tracks.push(MixTrack { + track_id: 1, + mix_in: 0.0, + mix_out: 4.0, + key_shift: 0, + gain_db: 0.0, + stems: Vec::new(), + }); + mix.normalize(); + mix +} + +fn start(core: &mut EngineCore, output: PreviewOutput, track: &Arc) -> MixPlayer { + let mut p = MixPlayer::new(&mix(), &|_| Some(track.clone()), [0, 1]).unwrap(); + p.play(&mut PreviewSink { sink: core, output }, 0.0) + .unwrap(); + p +} + +fn block(core: &mut EngineCore) -> (Vec, Vec) { + let mut m = vec![0.0; FRAMES * 2]; + let mut c = m.clone(); + core.process(&mut m, &mut c); + (m, c) +} + +#[test] +fn headphones_preview_never_enters_master_or_recording() { + let mut core = EngineCore::new(SR, 4); + let t = audio(); + let _p = start(&mut core, PreviewOutput::Headphones, &t); + let (producer, mut recorded) = rtrb::RingBuffer::new(FRAMES * 4); + core.apply(Command::SetRecorder(Some(producer))); + for master_gain in [-60.0, 0.0, 12.0] { + core.apply(Command::SetMasterGain(master_gain)); + for blend in [0.0, 1.0] { + core.apply(Command::SetHeadphoneMix(blend)); + core.apply(Command::SetPfl(0, blend == 1.0)); + core.apply(Command::SetCrossfader(blend)); + let (m, c) = block(&mut core); + assert!(m.iter().all(|v| *v == 0.0)); + assert!( + c.iter().any(|v| v.abs() > 0.01), + "preview bypasses Cue/Master" + ); + while let Ok(sample) = recorded.pop() { + assert_eq!(sample, 0.0); + } + } + } + assert!(core.snapshot().recording.seconds > 0.0); + assert!(!core.snapshot().mix.active); + assert!(core.snapshot().preview.playing); +} + +#[test] +fn headphone_volume_controls_preview() { + let t = audio(); + let mut loud = EngineCore::new(SR, 2); + let mut quiet = EngineCore::new(SR, 2); + loud.apply(Command::SetMasterGain(-80.0)); + quiet.apply(Command::SetMasterGain(-80.0)); + quiet.apply(Command::SetHeadphoneGain(-20.0)); + let _a = start(&mut loud, PreviewOutput::Headphones, &t); + let _b = start(&mut quiet, PreviewOutput::Headphones, &t); + let (_, a) = block(&mut loud); + let (_, b) = block(&mut quiet); + let energy = |x: &[f32]| x.iter().map(|v| v * v).sum::(); + let ratio = energy(&b) / energy(&a); + assert!( + (ratio - 0.01).abs() < 0.002, + "20 dB headphone attenuation: {ratio}" + ); +} + +#[test] +fn preview_does_not_change_live_or_studio_mix_or_decks() { + let t = audio(); + for decks in [[0, 1], [2, 3]] { + for output in [PreviewOutput::Headphones, PreviewOutput::Master] { + let mut core = EngineCore::new(SR, 4); + let mut reference = EngineCore::new(SR, 4); + let mut main = MixPlayer::new(&mix(), &|_| Some(t.clone()), decks).unwrap(); + let mut other = MixPlayer::new(&mix(), &|_| Some(t.clone()), decks).unwrap(); + main.play(&mut core, 0.0).unwrap(); + other.play(&mut reference, 0.0).unwrap(); + let mut preview = start(&mut core, output, &t); + for i in 0..30 { + let mut sink = PreviewSink { + sink: &mut core, + output, + }; + match i { + 5 => preview.pause(&mut sink).unwrap(), + 7 => preview.resume(&mut sink).unwrap(), + 8 => preview.seek(&mut sink, 1.0).unwrap(), + 10 => preview.stop(&mut sink).unwrap(), + 20 => preview = start(&mut core, output, &t), + _ => {} + } + let (actual, _) = block(&mut core); + let (expected, _) = block(&mut reference); + if output == PreviewOutput::Headphones { + assert_eq!(actual, expected, "master samples remain identical"); + } else if i == 0 { + assert!( + actual + .iter() + .zip(&expected) + .any(|(a, b)| (a - b).abs() > 0.01), + "master mode sums preview over the running mix" + ); + } + let a = core.snapshot(); + let b = reference.snapshot(); + let mut main_state = a.mix; + main_state.schedule_id = b.mix.schedule_id; + assert_eq!(main_state, b.mix); + assert_eq!(a.decks, b.decks); + assert_eq!(a.master_deck, b.master_deck); + } + } + } +} + +#[test] +fn master_preview_is_recorded_and_obeys_master_volume() { + let t = audio(); + let mut core = EngineCore::new(SR, 2); + let _p = start(&mut core, PreviewOutput::Master, &t); + let (producer, mut recorded) = rtrb::RingBuffer::new(FRAMES * 4); + core.apply(Command::SetRecorder(Some(producer))); + let (m, _) = block(&mut core); + assert!(m.iter().any(|v| v.abs() > 0.01)); + for sample in &m { + assert_eq!(recorded.pop().unwrap(), *sample); + } + core.apply(Command::SetMasterGain(-80.0)); + for _ in 0..100 { + block(&mut core); + while recorded.pop().is_ok() {} + } + let (m, _) = block(&mut core); + assert!(m.iter().all(|v| v.abs() < 0.0002)); +} + +#[test] +fn stale_preview_load_cannot_fill_a_new_session_or_main_mix() { + let t = audio(); + let meta = |_: i64| Some(t.analysis()); + let mut core = EngineCore::new(SR, 2); + let old = MixSchedule::lazy(&mix(), &meta, [0, 1]); + let old_id = old.id; + core.apply(Command::PreviewPlay { + schedule: Box::new(old), + start: 0.0, + output: PreviewOutput::Headphones, + }); + let new = MixSchedule::lazy(&mix(), &meta, [0, 1]); + let new_id = new.id; + core.apply(Command::PreviewPlay { + schedule: Box::new(new), + start: 0.0, + output: PreviewOutput::Headphones, + }); + core.apply(Command::PreviewTrackReady { + schedule: old_id, + index: 0, + track: t.clone(), + }); + let (m, c) = block(&mut core); + assert!(m.iter().chain(&c).all(|v| *v == 0.0)); + assert_eq!(core.snapshot().preview.schedule_id, new_id); + assert!(core.snapshot().preview.waiting); + core.apply(Command::PreviewTrackReady { + schedule: new_id, + index: 0, + track: t, + }); + let (_, c) = block(&mut core); + assert!(c.iter().any(|v| v.abs() > 0.01)); + assert!(!core.snapshot().mix.active); +} + +#[test] +fn preview_finishes_and_stops_without_stale_audio() { + let mut core = EngineCore::new(SR, 2); + let t = audio(); + let mut p = MixPlayer::new(&mix(), &|_| Some(t.clone()), [0, 1]).unwrap(); + p.play( + &mut PreviewSink { + sink: &mut core, + output: PreviewOutput::Headphones, + }, + p.timeline().total_secs - 0.05, + ) + .unwrap(); + for _ in 0..20 { + block(&mut core); + } + assert!(core.snapshot().preview.finished); + let (m, c) = block(&mut core); + assert!(m.iter().chain(&c).all(|v| *v == 0.0)); + p.stop(&mut PreviewSink { + sink: &mut core, + output: PreviewOutput::Headphones, + }) + .unwrap(); + block(&mut core); + assert!(!core.snapshot().preview.active); +} + +#[test] +fn both_mashup_orders_play_only_in_headphones() { + let t = audio(); + for style in [TransitionStyle::Mashup, TransitionStyle::MashupIn] { + let mut m = mix(); + m.tracks.push(MixTrack { + track_id: 2, + mix_in: 0.0, + mix_out: 4.0, + key_shift: 0, + gain_db: 0.0, + stems: Vec::new(), + }); + m.transitions.push(Transition::new(style, 4)); + m.normalize(); + let mut core = EngineCore::new(SR, 2); + let mut p = MixPlayer::new(&m, &|_| Some(t.clone()), [0, 1]).unwrap(); + let at = p.timeline().transitions[0].start_sec; + p.play( + &mut PreviewSink { + sink: &mut core, + output: PreviewOutput::Headphones, + }, + at, + ) + .unwrap(); + let mut energy = 0.0; + for _ in 0..20 { + let (master, cue) = block(&mut core); + assert!(master.iter().all(|v| *v == 0.0)); + energy += cue.iter().map(|v| v * v).sum::(); + } + assert!(energy > 0.01); + } +} + +#[test] +fn replacing_a_headphone_preview_with_a_silent_master_preview_leaks_no_tail() { + let t = audio(); + let mut core = EngineCore::new(SR, 2); + let _p = start(&mut core, PreviewOutput::Headphones, &t); + for _ in 0..10 { + block(&mut core); + } + core.apply(Command::PreviewStop); + let silent = Arc::new( + LoadedTrack::new( + "silent", + Arc::new(AudioBuffer::new( + SR, + vec![0.0; SR as usize * 6], + vec![0.0; SR as usize * 6], + )), + ) + .with_grid(BeatGrid::new(120.0, 0.0)), + ); + let _q = start(&mut core, PreviewOutput::Master, &silent); + let (master, _) = block(&mut core); + assert!( + master.iter().all(|v| *v == 0.0), + "old headphone audio must not escape through filter history" + ); +} + +#[test] +fn preview_survives_output_rate_change_without_changing_destination() { + let t = audio(); + let mut core = EngineCore::new(SR, 2); + let p = start(&mut core, PreviewOutput::Headphones, &t); + block(&mut core); + let time = core.snapshot().preview.time; + core.set_sample_rate(48000); + let (master, cue) = block(&mut core); + assert_eq!(core.snapshot().preview.schedule_id, p.schedule_id()); + assert!(core.snapshot().preview.time > time); + assert!(master.iter().all(|v| *v == 0.0)); + assert!(cue.iter().any(|v| v.abs() > 0.01)); +} + +#[test] +fn main_transport_cannot_stop_the_preview() { + let t = audio(); + let mut core = EngineCore::new(SR, 4); + let mut main = MixPlayer::new(&mix(), &|_| Some(t.clone()), [2, 3]).unwrap(); + main.play(&mut core, 0.0).unwrap(); + let p = start(&mut core, PreviewOutput::Headphones, &t); + block(&mut core); + main.stop(&mut core).unwrap(); + let (_, cue) = block(&mut core); + assert!(!core.snapshot().mix.active); + assert_eq!(core.snapshot().preview.schedule_id, p.schedule_id()); + assert!(core.snapshot().preview.playing); + assert!(cue.iter().any(|v| v.abs() > 0.01)); +} diff --git a/docs/audio-output.md b/docs/audio-output.md index 5976119..b883060 100644 --- a/docs/audio-output.md +++ b/docs/audio-output.md @@ -116,3 +116,28 @@ Hardware acceptance still requires checking both outputs, disconnect/reconnect, and analog alignment on Windows, macOS and Linux. Any hardware test must keep master volume at zero. Software timing estimates alone cannot establish analog alignment accuracy. + +## Browser previews + +Settings > Audio output > Preview output selects Master (the default, including older +preferences) or Headphones. Headphone preview is an explicit opt-in. Changing this preference stops the current preview and does not +restart the output device. It applies to Library, Studio Playlist and Mashups, Add tracks, +and the Live browser and Automix queue. + +Previews have their own two private decks and conductor. They never stop or reuse the main +Studio or Live decks. Headphone previews are added after Cue/Master blending, before the +headphone gain and overload protection; they never enter the master or its recording. +Master previews are summed before master gain and limiting, and are included in recordings. +Offline project exports do not include previews. A missing or failed headphone output stops +or rejects the preview without falling back to master. Leaving the source screen/list stops +its preview. Track previews start at the first analysed drop, otherwise a third into the +track, at native tempo and key. + +## Live headphone monitoring + +The headphone buttons beside each deck's filter select its pre-fader CUE signal; they do +not change its master output. CUE?MIX blends selected CUE channels with the master. At the +CUE end, headphones are silent when all deck headphone buttons are off (unless an independent +headphone preview is playing). Master monitoring is enabled only by turning CUE?MIX towards +MIX; it is never substituted automatically when no deck is selected. PHONES controls the +combined headphone volume. From 278163dd9c5c2410edd348dcb6c28c7665817ed7 Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Thu, 5 Nov 2026 11:19:45 +0300 Subject: [PATCH 2/4] Refine audio output settings and shared preview routing --- crates/app/src/app.rs | 4 +- crates/app/src/live/adapter.rs | 1 + crates/app/src/live/model.rs | 3 +- crates/app/src/live/view.rs | 2 + crates/app/src/preview.rs | 8 +- crates/app/src/settings.rs | 192 +++++++++++++++++++++------------ crates/engine/src/core.rs | 5 + crates/engine/src/engine.rs | 64 ++++++++--- crates/engine/src/mixer.rs | 26 ++++- crates/engine/src/output.rs | 52 +++++++-- crates/engine/tests/preview.rs | 31 ++++++ docs/audio-output.md | 22 ++-- 12 files changed, 305 insertions(+), 105 deletions(-) diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index d6f3969..5da0c74 100644 --- a/crates/app/src/app.rs +++ b/crates/app/src/app.rs @@ -674,7 +674,7 @@ impl App { self.sh.preview.item = Some(item); self.sh.preview.mix_serial = self.studio.mix_serial; self.sh.preview.mashup_revision = self.studio.mashup.revision; - self.status = format!("Preview in {}: {}", self.prefs.preview_output.label(), self.sh.track(item.track).map(|t| t.display_name()).unwrap_or_default()); + self.status = format!("Preview in {}: {}", self.sh.preview.output_label(), self.sh.track(item.track).map(|t| t.display_name()).unwrap_or_default()); } Err(e) => self.status = format!("Preview: {e:#}"), } @@ -699,6 +699,7 @@ impl App { fn reconcile_preview(&mut self) { use crate::preview::PreviewSource as P; + self.sh.preview.main_output = self.eng.handle.as_ref().is_some_and(|h| h.audio_config().headphones == clubcraft_engine::HeadphoneRouting::MainOutput); let Some(item) = self.sh.preview.item else { return; }; let visible = match item.source { P::Library { playlist, mix } => self.view == View::Library && playlist == self.library.playlist && mix == self.library.mix, @@ -1484,6 +1485,7 @@ impl eframe::App for App { self.handle_home_actions(home_actions); let mut sa = Vec::new(); self.settings.ui(&ctx, self.eng.handle.as_ref(), &mut sa, &mut self.prefs); + if std::mem::take(&mut self.settings.stop_preview) { self.stop_preview(); } if std::mem::take(&mut self.settings.restart_audio) && self.eng.handle.is_none() { self.eng = crate::live::adapter::LiveEngine::start(self.settings.audio.clone()); if self.eng.handle.is_some() { diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index d9e5b18..357f066 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -1028,6 +1028,7 @@ pub fn mixer_ui(st: &EngineState, eng: &LiveEngine) -> MixerUi { crossfader: st.master.crossfader * 2.0 - 1.0, master: db_knob(st.master.gain_db, 0.8), headphone_mix: st.master.headphone_mix, + shared_output: eng.handle.as_ref().is_some_and(|h| h.audio_config().headphones == clubcraft_engine::HeadphoneRouting::MainOutput), headphone_vol: db_knob(st.master.headphone_gain_db, 0.7), master_vu: st.master.level.peak, recording: st.recording.active, diff --git a/crates/app/src/live/model.rs b/crates/app/src/live/model.rs index 65991ca..7fadfb0 100644 --- a/crates/app/src/live/model.rs +++ b/crates/app/src/live/model.rs @@ -110,6 +110,7 @@ pub struct MixerUi { pub crossfader: f32, pub master: f32, pub headphone_mix: f32, + pub shared_output: bool, pub headphone_vol: f32, pub master_vu: [f32; 2], pub recording: bool, @@ -191,6 +192,6 @@ pub enum LiveAction { impl Default for MixerUi { fn default() -> Self { - MixerUi { crossfader: 0.0, master: 0.8, headphone_mix: 0.0, headphone_vol: 0.7, master_vu: [0.0; 2], recording: false, record_secs: 0.0, master_bpm: None, automix: false, output_name: String::new() } + MixerUi { crossfader: 0.0, master: 0.8, headphone_mix: 0.0, shared_output: false, headphone_vol: 0.7, master_vu: [0.0; 2], recording: false, record_secs: 0.0, master_bpm: None, automix: false, output_name: String::new() } } } diff --git a/crates/app/src/live/view.rs b/crates/app/src/live/view.rs index 0efe2ae..66ecd55 100644 --- a/crates/app/src/live/view.rs +++ b/crates/app/src/live/view.rs @@ -599,9 +599,11 @@ impl LiveView { ui.horizontal(|ui| { ui.add_space((ui.available_width() - 72.0).max(0.0) / 2.0); let mut hm = m.headphone_mix; + ui.add_enabled_ui(!m.shared_output, |ui| { if widgets::knob(ui, &mut hm, 0.0..=1.0, 0.0, "CUE·MIX", theme::TEXT, 32.0).on_hover_text("CUE: selected decks only; MIX: master. With no CUE selected, the CUE end is silent.").changed() { out.push(LiveAction::HeadphoneMix(hm)); } + }).response.on_disabled_hover_text("Master already plays through Main output."); let mut hv = m.headphone_vol; if widgets::knob(ui, &mut hv, 0.0..=1.0, 0.7, "PHONES", theme::TEXT, 32.0).changed() { out.push(LiveAction::HeadphoneVol(hv)); diff --git a/crates/app/src/preview.rs b/crates/app/src/preview.rs index 66a1943..c9b0213 100644 --- a/crates/app/src/preview.rs +++ b/crates/app/src/preview.rs @@ -30,19 +30,21 @@ pub struct PreviewItem { pub struct PreviewState { pub item: Option, pub output: PreviewOutput, + pub main_output: bool, pub loading: bool, pub mix_serial: u64, pub mashup_revision: u64, } impl PreviewState { + pub fn output_label(&self) -> &'static str { if self.main_output { "Main output" } else { self.output.label() } } pub fn playing(&self, source: PreviewSource, track: TrackId, row: usize) -> bool { self.item == Some(PreviewItem { source, track, row }) } pub fn label(&self, ui: &mut egui::Ui) { ui.label( - egui::RichText::new(format!("Preview: {}", self.output.label())) + egui::RichText::new(format!("Preview: {}", self.output_label())) .small() .color(crate::theme::TEXT_DIM), ); @@ -60,10 +62,10 @@ impl PreviewState { } else if item.source == PreviewSource::Mashups { format!( "Preview vocals over this instrumental in {}", - self.output.label() + self.output_label() ) } else { - format!("Preview in {} from the first drop", self.output.label()) + format!("Preview in {} from the first drop", self.output_label()) }) } } diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index 585f415..64eb539 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -24,6 +24,34 @@ fn device_label(devices: &[DeviceInfo], selected: Option<&str>, empty: &str) -> } } +fn output_channels(devices: &[DeviceInfo], id: Option<&str>) -> u16 { + devices.iter().find(|d| id.map_or(d.is_default, |id| d.id == id || d.name == id)) + .map_or(4, |d| d.max_channels) +} + +fn master_pair(cfg: &AudioConfig) -> [u16; 2] { + match cfg.headphones { HeadphoneRouting::Channels { master, .. } => master, _ => cfg.master_pair } +} + +fn cue_pair(cfg: &AudioConfig) -> [u16; 2] { + match cfg.headphones { + HeadphoneRouting::Channels { cue, .. } => cue, + HeadphoneRouting::Auto => [2, 3], + _ => cfg.headphone_pair, + } +} + +fn channel_pair(ui: &mut Ui, id: &str, pair: &mut [u16; 2], channels: u16, blocked: Option<[u16; 2]>) { + if channels == 2 && *pair == [0, 1] { ui.label("1/2 (stereo)"); return; } + egui::ComboBox::from_id_salt(id).selected_text(format!("{}/{}", pair[0] + 1, pair[1] + 1)).show_ui(ui, |ui| { + for left in (0..channels.saturating_sub(1)).step_by(2) { + let candidate = [left, left + 1]; + let overlap = blocked.is_some_and(|other| candidate.iter().any(|c| other.contains(c))); + ui.add_enabled_ui(!overlap, |ui| { ui.selectable_value(pair, candidate, format!("{}/{}", left + 1, left + 2)); }); + } + }); +} + pub fn mapping_path() -> std::path::PathBuf { clubcraft_core::paths::data_dir().join("midi-mapping.json") } @@ -74,7 +102,9 @@ pub struct Settings { pub open: bool, pub audio: AudioConfig, audio_draft: AudioConfig, + preview_draft: Option, pub restart_audio: bool, + pub stop_preview: bool, devices: Vec, midi_ports: Vec, pub midi_port: Option, @@ -122,8 +152,10 @@ impl Settings { Settings { open: false, audio_draft: audio.clone(), + preview_draft: None, audio, restart_audio: false, + stop_preview: false, devices: vec![], midi_ports: vec![], midi_port, @@ -235,92 +267,100 @@ impl Settings { fn audio_ui(&mut self, ui: &mut egui::Ui, handle: Option<&EngineHandle>, prefs: &mut Prefs) { use clubcraft_engine::command::PreviewOutput; - section(ui, "Preview"); - ui.horizontal(|ui| { - ui.label("Preview output"); - ui.selectable_value(&mut prefs.preview_output, PreviewOutput::Headphones, "Headphones"); - ui.selectable_value(&mut prefs.preview_output, PreviewOutput::Master, "Master"); - }); - hint(ui, "Applies immediately to track and mashup previews. Changing the output stops the current preview."); - if prefs.preview_output == PreviewOutput::Headphones && handle.is_none_or(|h| !crate::preview::headphones_available(&h.stream_info())) { - ui.colored_label(theme::WARN, "Headphone output is unavailable. Configure and Apply an output below to preview in headphones."); - } - ui.add_space(8.0); - section(ui, "Audio output"); if self.devices.is_empty() { self.devices = clubcraft_engine::devices().unwrap_or_default(); } let mut cfg = self.audio_draft.clone(); - egui::Grid::new("audio").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { - ui.label("Master device"); - ui.horizontal(|ui| { - let label = device_label(&self.devices, cfg.device.as_deref(), "System default"); - egui::ComboBox::from_id_salt("dev").width(300.0).selected_text(label).show_ui(ui, |ui| { - ui.selectable_value(&mut cfg.device, None, "System default"); - for d in &self.devices { - ui.add_enabled_ui(!d.id.is_empty(), |ui| { - ui.selectable_value(&mut cfg.device, Some(d.id.clone()), device_choice(d, &self.devices)); - }); - } - }); - if ui.small_button("↻").on_hover_text("Rescan devices").clicked() { - self.devices = clubcraft_engine::devices().unwrap_or_default(); + let mut preview = *self.preview_draft.get_or_insert(prefs.preview_output); + section(ui, "Master"); + let mut master = master_pair(&cfg); + let mut cue = cue_pair(&cfg); + egui::Grid::new("master_output").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { + ui.label("Device"); + egui::ComboBox::from_id_salt("dev").width(300.0).selected_text(device_label(&self.devices, cfg.device.as_deref(), "System default")).show_ui(ui, |ui| { + ui.selectable_value(&mut cfg.device, None, "System default"); + for d in &self.devices { + ui.add_enabled_ui(!d.id.is_empty(), |ui| { ui.selectable_value(&mut cfg.device, Some(d.id.clone()), device_choice(d, &self.devices)); }); } }); ui.end_row(); - ui.label("Sample rate"); - egui::ComboBox::from_id_salt("sr").selected_text(cfg.sample_rate.map(|r| format!("{r} Hz")).unwrap_or("Auto".into())).show_ui(ui, |ui| { - ui.selectable_value(&mut cfg.sample_rate, None, "Auto"); - ui.selectable_value(&mut cfg.sample_rate, Some(44100), "44100 Hz"); - ui.selectable_value(&mut cfg.sample_rate, Some(48000), "48000 Hz"); - }); + ui.label("Channels"); + channel_pair(ui, "master_channels", &mut master, output_channels(&self.devices, cfg.device.as_deref()), None); ui.end_row(); - ui.label("Buffer"); - egui::ComboBox::from_id_salt("buf").selected_text(cfg.buffer_frames.map(|b| format!("{b} frames")).unwrap_or("Device default".into())).show_ui(ui, |ui| { - for b in [128u32, 256, 512, 1024] { - let sr = cfg.sample_rate.or_else(|| handle.map(|h| h.stream_info().sample_rate)).unwrap_or(44100); - ui.selectable_value(&mut cfg.buffer_frames, Some(b), format!("{b} frames ({:.1} ms)", b as f64 * 1000.0 / sr as f64)); - } - ui.selectable_value(&mut cfg.buffer_frames, None, "Device default"); - }); - ui.end_row(); - ui.label("Headphones"); + }); + section(ui, "Preview / headphones"); + // Legacy Master preferences are displayed as Main output and converted only on Apply. + let legacy_main = preview == PreviewOutput::Master; + if legacy_main { cfg.headphones = HeadphoneRouting::MainOutput; } + egui::Grid::new("preview_output").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { + ui.label("Device"); let label = match cfg.headphones { - HeadphoneRouting::Auto => "Auto (outputs 3/4 if available)".to_string(), - HeadphoneRouting::Off => "Off".into(), - HeadphoneRouting::Split => "Split cable (master L / cue R)".into(), - HeadphoneRouting::Channels { master, cue } => format!("Master {}/{} · Cue {}/{}", master[0] + 1, master[1] + 1, cue[0] + 1, cue[1] + 1), - HeadphoneRouting::SeparateDevice => "Separate device (stereo cue)".into(), + HeadphoneRouting::MainOutput | HeadphoneRouting::Off => "Main output".into(), + HeadphoneRouting::SeparateDevice => device_label(&self.devices, cfg.headphone_device.as_deref(), "Select device..."), + HeadphoneRouting::Split => "Split cable (saved configuration)".into(), + _ => device_label(&self.devices, cfg.device.as_deref(), "System default"), }; - egui::ComboBox::from_id_salt("hp").width(300.0).selected_text(label).show_ui(ui, |ui| { - ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Auto, "Auto (outputs 3/4 if available)"); - ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Off, "Off"); - ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Split, "Split cable (master L / cue R)"); - ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Channels { master: [0, 1], cue: [2, 3] }, "Master 1/2 · Cue 3/4"); - ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Channels { master: [2, 3], cue: [0, 1] }, "Master 3/4 · Cue 1/2"); - ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::SeparateDevice, "Separate device (stereo cue)"); + egui::ComboBox::from_id_salt("preview_device").width(300.0).selected_text(label).show_ui(ui, |ui| { + if ui.selectable_label(matches!(cfg.headphones, HeadphoneRouting::MainOutput | HeadphoneRouting::Off), "Main output").clicked() { + cfg.headphones = HeadphoneRouting::MainOutput; + preview = PreviewOutput::Headphones; + } + for d in &self.devices { + let same = cfg.device.as_deref().map_or(d.is_default, |id| d.id == id || d.name == id); + let selected = if same { matches!(cfg.headphones, HeadphoneRouting::Channels { .. } | HeadphoneRouting::Auto | HeadphoneRouting::Split) } + else { cfg.headphones == HeadphoneRouting::SeparateDevice && cfg.headphone_device.as_deref() == Some(&d.id) }; + if ui.add_enabled(!d.id.is_empty() && (!same || d.max_channels >= 4), egui::Button::selectable(selected, device_choice(d, &self.devices))).clicked() { + preview = PreviewOutput::Headphones; + if same { cfg.headphones = HeadphoneRouting::Channels { master, cue: [2, 3] }; cue = [2, 3]; } + else { cfg.headphones = HeadphoneRouting::SeparateDevice; cfg.headphone_device = Some(d.id.clone()); cue = [0, 1]; } + } + } }); ui.end_row(); - if cfg.headphones == HeadphoneRouting::SeparateDevice { - ui.label("Headphone device"); - let label = device_label(&self.devices, cfg.headphone_device.as_deref(), "Select device…"); - egui::ComboBox::from_id_salt("cue_device").width(300.0).selected_text(label).show_ui(ui, |ui| { - for d in &self.devices { - ui.add_enabled_ui(!d.id.is_empty(), |ui| { - ui.selectable_value(&mut cfg.headphone_device, Some(d.id.clone()), device_choice(d, &self.devices)); - }); - } + if !matches!(cfg.headphones, HeadphoneRouting::MainOutput | HeadphoneRouting::Off | HeadphoneRouting::Split) { + ui.label("Channels"); + let separate = cfg.headphones == HeadphoneRouting::SeparateDevice; + let channels = output_channels(&self.devices, if separate { cfg.headphone_device.as_deref() } else { cfg.device.as_deref() }); + channel_pair(ui, "cue_channels", &mut cue, channels, if separate { None } else { Some(master) }); + ui.end_row(); + } + }); + if let HeadphoneRouting::Channels { .. } | HeadphoneRouting::Auto = cfg.headphones { + cfg.headphones = HeadphoneRouting::Channels { master, cue }; + } + cfg.master_pair = master; + cfg.headphone_pair = cue; + if matches!(cfg.headphones, HeadphoneRouting::MainOutput | HeadphoneRouting::Off) { + hint(ui, "MASTER controls the main mix; PHONES controls previews and headphone cue. Only the main mix is recorded."); + } else { + hint(ui, "Shared output for list previews and deck headphone buttons. A disconnected output never falls back to master."); + } + if ui.small_button("Rescan devices").clicked() { self.devices = clubcraft_engine::devices().unwrap_or_default(); } + ui.collapsing("Advanced audio settings", |ui| { + egui::Grid::new("audio_advanced").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { + ui.label("Sample rate"); + egui::ComboBox::from_id_salt("sr").selected_text(cfg.sample_rate.map(|r| format!("{r} Hz")).unwrap_or("Auto".into())).show_ui(ui, |ui| { + ui.selectable_value(&mut cfg.sample_rate, None, "Auto"); + for r in [44100, 48000] { ui.selectable_value(&mut cfg.sample_rate, Some(r), format!("{r} Hz")); } }); ui.end_row(); - ui.label("Alignment correction"); - ui.add(egui::DragValue::new(&mut cfg.alignment_ms).range(-500.0..=500.0).speed(0.1).suffix(" ms")) - .on_hover_text("Positive: headphones lag further, so delay master. Negative: delay headphones. Saved for this device pair, rate and buffer."); + ui.label("Buffer"); + egui::ComboBox::from_id_salt("buf").selected_text(cfg.buffer_frames.map(|b| format!("{b} frames")).unwrap_or("Device default".into())).show_ui(ui, |ui| { + for b in [128u32, 256, 512, 1024] { ui.selectable_value(&mut cfg.buffer_frames, Some(b), format!("{b} frames")); } + ui.selectable_value(&mut cfg.buffer_frames, None, "Device default"); + }); ui.end_row(); - } + if cfg.headphones == HeadphoneRouting::SeparateDevice { + ui.label("Alignment correction"); + ui.add(egui::DragValue::new(&mut cfg.alignment_ms).range(-500.0..=500.0).speed(0.1).suffix(" ms")); + ui.end_row(); + } + }); }); + self.preview_draft = Some(preview); let before = &self.audio_draft; if cfg.device != before.device || cfg.headphone_device != before.headphone_device || cfg.headphones != before.headphones - || cfg.sample_rate != before.sample_rate || cfg.buffer_frames != before.buffer_frames { + || cfg.sample_rate != before.sample_rate || cfg.buffer_frames != before.buffer_frames || cfg.master_pair != before.master_pair || cfg.headphone_pair != before.headphone_pair { cfg.alignment_ms = 0.0; cfg.alignment_key = None; } @@ -351,21 +391,33 @@ impl Settings { self.audio_draft = cfg.clone(); ui.horizontal(|ui| { if ui.button("Apply").clicked() { - if let Some(h) = handle { + if cfg == self.audio { + self.stop_preview = true; + prefs.preview_output = PreviewOutput::Headphones; + self.preview_draft = Some(PreviewOutput::Headphones); + self.message = "Audio output changed".into(); + } else if let Some(h) = handle { match h.set_audio_config(cfg) { Ok(()) => { self.sync_audio(h.audio_config()); + self.stop_preview = true; + prefs.preview_output = PreviewOutput::Headphones; + self.preview_draft = Some(PreviewOutput::Headphones); self.message = "Audio output changed".into(); } Err(e) => self.message = format!("Audio: {e:#}"), } } else { self.audio = cfg; + self.stop_preview = true; + prefs.preview_output = PreviewOutput::Headphones; + self.preview_draft = Some(PreviewOutput::Headphones); self.restart_audio = true; } } - if ui.add_enabled(self.audio_draft != self.audio, egui::Button::new("Discard changes")).clicked() { + if ui.add_enabled(self.audio_draft != self.audio || preview != prefs.preview_output, egui::Button::new("Discard changes")).clicked() { self.audio_draft = self.audio.clone(); + self.preview_draft = Some(prefs.preview_output); } }); } diff --git a/crates/engine/src/core.rs b/crates/engine/src/core.rs index b9b0b1a..4a9f4e2 100644 --- a/crates/engine/src/core.rs +++ b/crates/engine/src/core.rs @@ -109,6 +109,10 @@ impl EngineCore { /// Change the output rate. Rebuilds the mixer and FX (allocates) — not for the audio thread. /// Deck state (tracks, positions, cues, loops) is preserved. + pub fn set_shared_output(&mut self, shared: bool) { + self.mixer.shared_output = shared; + } + pub fn set_sample_rate(&mut self, sr: u32) { if sr == self.sr { return; @@ -132,6 +136,7 @@ impl EngineCore { self.mixer.headphone_gain_db = old.headphone_gain_db; self.mixer.auto_gain = old.auto_gain; self.mixer.preview_output = old.preview_output; + self.mixer.shared_output = old.shared_output; self.mixer.limiter.enabled = old.limiter.enabled; self.mixer.limiter.set_ceiling_db(crate::dsp::gain_to_db(old.limiter.ceiling())); for d in self.decks.iter_mut() { diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index a03caea..b1250d0 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -25,6 +25,8 @@ use std::time::{Duration, Instant}; /// Where the headphone (cue) bus goes. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] pub enum HeadphoneRouting { + /// Independent cue/preview volume summed into the physical master output. + MainOutput, /// Channels 3/4 when the device has ≥ 4 outputs, otherwise no headphone output. #[default] Auto, @@ -51,6 +53,10 @@ pub struct AudioConfig { pub headphones: HeadphoneRouting, #[serde(default)] pub headphone_device: Option, + #[serde(default = "stereo_pair")] + pub master_pair: [u16; 2], + #[serde(default = "stereo_pair")] + pub headphone_pair: [u16; 2], /// Positive values mean the headphones lag further: delay the master. #[serde(default)] pub alignment_ms: f64, @@ -61,10 +67,12 @@ pub struct AudioConfig { pub decks: usize, } +fn stereo_pair() -> [u16; 2] { [0, 1] } + impl Default for AudioConfig { fn default() -> Self { - AudioConfig { device: None, sample_rate: None, buffer_frames: Some(256), headphones: HeadphoneRouting::Auto, - headphone_device: None, alignment_ms: 0.0, alignment_key: None, decks: 4 } + AudioConfig { device: None, sample_rate: None, buffer_frames: Some(256), headphones: HeadphoneRouting::MainOutput, + headphone_device: None, master_pair: [0, 1], headphone_pair: [0, 1], alignment_ms: 0.0, alignment_key: None, decks: 4 } } } @@ -364,7 +372,7 @@ struct Prepared { fn bind_config(config: &mut AudioConfig, p: &Prepared) { let master = p.device.id().map(|i| i.to_string()).unwrap_or_default(); let cue = p.cue_device.as_ref().and_then(|d| d.id().ok()).map(|i| i.to_string()); - let key = format!("{:?}", (&master, &cue, p.sr, p.channels, config.buffer_frames)); + let key = format!("{:?}", (&master, &cue, p.sr, p.channels, config.buffer_frames, config.master_pair, config.headphone_pair)); bind_alignment(config, key); // Keep None as the explicit system-default choice. Resolve legacy names once. if config.device.is_some() && !master.is_empty() { config.device = Some(master); } @@ -393,7 +401,14 @@ fn prepare(config: &AudioConfig) -> Result { let max_ch = ranges.iter().map(|r| r.channels()).max().unwrap_or(2); let (want_ch, master_ch, cue_ch, split) = match config.headphones { HeadphoneRouting::Auto if max_ch >= 4 => (4u16, [0u16, 1], Some([2u16, 3]), false), - HeadphoneRouting::Auto | HeadphoneRouting::Off | HeadphoneRouting::SeparateDevice => (2, [0, 1], None, false), + HeadphoneRouting::Auto => (2, [0, 1], None, false), + HeadphoneRouting::MainOutput | HeadphoneRouting::Off | HeadphoneRouting::SeparateDevice => { + let master = config.master_pair; + if master[0] == master[1] { bail!("select distinct left and right master channels"); } + let need = master.iter().copied().max().unwrap_or(1).checked_add(1).ok_or_else(|| anyhow!("invalid master channels"))?; + if need > max_ch { bail!("master device has only {max_ch} outputs"); } + (need.max(2), master, if config.headphones == HeadphoneRouting::MainOutput { Some(master) } else { None }, false) + }, HeadphoneRouting::Channels { master, cue } => { let need = master.iter().chain(cue.iter()).copied().max().unwrap_or(1).checked_add(1) .ok_or_else(|| anyhow!("invalid output channel"))?; @@ -429,7 +444,7 @@ fn prepare(config: &AudioConfig) -> Result { fn choose_format(ranges: &[cpal::SupportedStreamConfigRange], cue_ranges: Option<&[cpal::SupportedStreamConfigRange]>, config: &AudioConfig, want_ch: u16) -> Result<(u16, u32)> { let strict = config.headphones == HeadphoneRouting::SeparateDevice || cue_ranges.is_some(); let master_ok = |c: &cpal::SupportedStreamConfigRange, sr| c.sample_format() == cpal::SampleFormat::F32 - && c.channels() >= want_ch && (!strict || c.channels() == 2) && c.contains_rate(sr) + && c.channels() >= want_ch && c.contains_rate(sr) && (!strict || supports_buffer(c, config.buffer_frames)); let preferred: Vec = match config.sample_rate { Some(r) if strict => vec![r], @@ -439,7 +454,7 @@ fn choose_format(ranges: &[cpal::SupportedStreamConfigRange], cue_ranges: Option let chosen = preferred .iter() .find(|r| ranges.iter().any(|c| master_ok(c, **r)) - && cue_ranges.is_none_or(|rs| rs.iter().any(|c| c.channels() == 2 && c.sample_format() == cpal::SampleFormat::F32 + && cue_ranges.is_none_or(|rs| rs.iter().any(|c| c.channels() >= config.headphone_pair.iter().copied().max().unwrap_or(1).saturating_add(1) && c.sample_format() == cpal::SampleFormat::F32 && c.contains_rate(**r) && supports_buffer(c, config.buffer_frames)))) .copied(); let sr = chosen.ok_or_else(|| anyhow!("no common F32 output format for the selected rate, channels and buffer"))?; @@ -482,7 +497,14 @@ fn open_stream( let Prepared { device, cue_device, channels, sr, master_ch, cue_ch, split } = prepared; let name = device_name(&device); let master_info = endpoint(&device, sr, channels, config.buffer_frames); - let cue_info = cue_device.as_ref().map(|d| endpoint(d, sr, 2, config.buffer_frames)); + let cue_channels = if let Some(d) = &cue_device { + if config.headphone_pair[0] == config.headphone_pair[1] { bail!("select distinct left and right headphone channels"); } + d.supported_output_configs()?.filter(|c| c.sample_format() == cpal::SampleFormat::F32 && c.contains_rate(sr) + && c.channels() >= config.headphone_pair.iter().copied().max().unwrap_or(1).saturating_add(1) + && supports_buffer(c, config.buffer_frames)).map(|c| c.channels()).min() + .ok_or_else(|| anyhow!("headphone channels unavailable at the selected rate and buffer"))? + } else { 2 }; + let cue_info = cue_device.as_ref().map(|d| endpoint(d, sr, cue_channels, config.buffer_frames)); let buffer_size = match config.buffer_frames { Some(f) => cpal::BufferSize::Fixed(f), None => cpal::BufferSize::Default, @@ -503,13 +525,14 @@ fn open_stream( let cue_errors = errors.clone(); let halted = stop.clone(); let failed = health.clone(); + let cue_pair = config.headphone_pair; let stream = d.build_output_stream::( - cpal::StreamConfig { channels: 2, sample_rate: sr, buffer_size }, + cpal::StreamConfig { channels: cue_channels, sample_rate: sr, buffer_size }, move |data, info| { - failed.cue.heartbeat(data.len() / 2); + failed.cue.heartbeat(data.len() / cue_channels as usize); if halted.load(Ordering::Acquire) || failed.cue.failed.load(Ordering::Relaxed) || failed.master.failed.load(Ordering::Relaxed) { data.fill(0.0); - } else { output.render(data, info); } + } else { output.render_channels(data, info, cue_channels as usize, cue_pair); } }, move |error| { err_health.cue.report_error(error.kind()); @@ -523,7 +546,10 @@ fn open_stream( let mut last_start: Option = None; let mut window = (0f32, 0f32); // (peak in the current ~2 s window, seconds in it) let mc = master_ch; + let shared = config.headphones == HeadphoneRouting::MainOutput; let cc = cue_ch; + let mut shared_limiter = crate::dsp::Limiter::new(sr as f32); + let mut shared_buffer = vec![0.0; SCRATCH_FRAMES * 2]; let err2 = errors.clone(); let data_cb = move |data: &mut [f32], callback: &cpal::OutputCallbackInfo| { let t0 = Instant::now(); @@ -554,6 +580,9 @@ fn open_stream( let n = (frames - done).min(SCRATCH_FRAMES); let (m, c) = (&mut side.master[..n * 2], &mut side.cue[..n * 2]); side.core.process(m, c); + if shared { + output::mix_shared_output(m, c, &mut shared_buffer[..n * 2], &mut shared_limiter); + } let out = &mut data[done * ch..(done + n) * ch]; out.fill(0.0); for f in 0..n { @@ -569,9 +598,9 @@ fn open_stream( } else { let sample = if separate { delay.process([m[f * 2], m[f * 2 + 1]], master_delay) } else { [m[f * 2], m[f * 2 + 1]] }; - o[mc[0] as usize] = sample[0]; - o[mc[1] as usize] = sample[1]; - if let Some(cc) = cc { + o[mc[0] as usize] = if shared { shared_buffer[f * 2] } else { sample[0] }; + o[mc[1] as usize] = if shared { shared_buffer[f * 2 + 1] } else { sample[1] }; + if let Some(cc) = cc.filter(|_| !shared) { o[cc[0] as usize] = c[f * 2]; o[cc[1] as usize] = c[f * 2 + 1]; } @@ -639,6 +668,7 @@ fn open_stream( if separate { opening_health.cue.arm(); } let core = side.as_mut().ok_or_else(|| anyhow!("audio core has not returned from previous stream"))?; core.core.set_sample_rate(sr); + core.core.set_shared_output(config.headphones == HeadphoneRouting::MainOutput); core.core.apply(Command::SetDeckCount(config.decks)); if let Some(s) = side.take() { if let Err(rtrb::PushError::Full(s)) = lend.push(s) { @@ -652,7 +682,7 @@ fn open_stream( channels, buffer_frames: config.buffer_frames, master_channels: master_ch, - cue_channels: if separate { Some([0, 1]) } else { cue_ch }, + cue_channels: if separate { Some(config.headphone_pair) } else { cue_ch }, split, master: master_info, headphones: cue_info, @@ -907,7 +937,11 @@ mod tests { config.buffer_frames = Some(64); assert!(choose_format(&master, Some(&cue), &config, 2).is_err()); config.buffer_frames = None; - assert!(choose_format(&[range(4, 44100, 48000)], Some(&cue), &config, 2).is_err()); + assert_eq!(choose_format(&[range(4, 44100, 48000)], Some(&cue), &config, 2).unwrap(), (4, 48000)); + config.headphone_pair = [2, 3]; + assert!(choose_format(&master, Some(&cue), &config, 2).is_err()); + assert_eq!(choose_format(&master, Some(&[range(4, 48000, 48000)]), &config, 2).unwrap(), (2, 48000)); + config.headphone_pair = [0, 1]; let integer_cue = [cpal::SupportedStreamConfigRange::new(2, 44100, 48000, cpal::SupportedBufferSize::Unknown, cpal::SampleFormat::I16)]; assert!(choose_format(&master, Some(&integer_cue), &config, 2).is_err()); diff --git a/crates/engine/src/mixer.rs b/crates/engine/src/mixer.rs index a48f1be..0489176 100644 --- a/crates/engine/src/mixer.rs +++ b/crates/engine/src/mixer.rs @@ -227,6 +227,7 @@ pub struct Mixer { pub limiter: crate::dsp::Limiter, master_meter: Meter, pub headphone_mix: f32, + pub shared_output: bool, pub headphone_gain_db: f32, hp_meter: Meter, pub auto_gain: bool, @@ -259,6 +260,7 @@ impl Mixer { limiter: crate::dsp::Limiter::new(sr), master_meter: Meter::new(sr), headphone_mix: 0.0, + shared_output: false, headphone_gain_db: 0.0, hp_meter: Meter::new(sr), auto_gain: true, @@ -328,7 +330,7 @@ impl Mixer { self.process_channels(decks, ctxs, active, n, master, cue); let master = &mut master[..n * 2]; let cue = &mut cue[..n * 2]; - if self.preview_output == crate::command::PreviewOutput::Master { + if !self.shared_output && self.preview_output == crate::command::PreviewOutput::Master { for (m, p) in master.iter_mut().zip(&self.preview[..n * 2]) { *m += *p; } } self.master_gain.set(db_to_gain(self.master_gain_db)); @@ -340,10 +342,10 @@ impl Mixer { self.limiter.process(master); self.master_meter.process(master); // Only the Cue/Master control determines master monitoring, even with no PFL selected. - let mix = self.headphone_mix.clamp(0.0, 1.0); + let mix = if self.shared_output { 0.0 } else { self.headphone_mix.clamp(0.0, 1.0) }; let hg = db_to_gain(self.headphone_gain_db); for ((c, m), p) in cue.iter_mut().zip(master.iter()).zip(&self.preview[..n * 2]) { - let preview = if self.preview_output == crate::command::PreviewOutput::Headphones { *p } else { 0.0 }; + let preview = if self.shared_output || self.preview_output == crate::command::PreviewOutput::Headphones { *p } else { 0.0 }; *c = soft_clip((*c * (1.0 - mix) + *m * mix + preview) * hg); } self.hp_meter.process(cue); @@ -390,6 +392,24 @@ mod tests { assert!(cue.iter().all(|v| *v == 0.0)); } + #[test] + fn shared_output_never_duplicates_master_and_keeps_pfl_independent() { + let mut mixer = Mixer::new(44100.0, 1); + mixer.shared_output = true; + for blend in [0.0, 0.5, 1.0] { + mixer.headphone_mix = blend; + let (master, cue) = render(&mut mixer); + assert!(master.iter().any(|v| v.abs() > 0.01)); + assert!(cue.iter().all(|v| *v == 0.0)); + } + mixer.channels[0].fader = 0.0; + for _ in 0..20 { render(&mut mixer); } + mixer.channels[0].pfl = true; + let (master, cue) = render(&mut mixer); + assert!(master.iter().all(|v| v.abs() < 1e-6)); + assert!(cue.iter().any(|v| v.abs() > 0.01)); + } + #[test] fn crossfader_curves() { let (a, b) = CrossfaderCurve::Smooth.gains(0.5); diff --git a/crates/engine/src/output.rs b/crates/engine/src/output.rs index 9ccc751..be66883 100644 --- a/crates/engine/src/output.rs +++ b/crates/engine/src/output.rs @@ -219,6 +219,12 @@ pub(crate) fn alignment(offset_ns: f64, correction_ms: f64, sr: u32) -> (f64, f6 (frames.clamp(0.0, sr as f64 * 2.0), (-frames).clamp(0.0, sr as f64 * 2.0)) } +/// Physical-output protection is deliberately downstream of the recorded master bus. +pub(crate) fn mix_shared_output(master: &[f32], cue: &[f32], output: &mut [f32], limiter: &mut crate::dsp::Limiter) { + for ((out, master), cue) in output.iter_mut().zip(master).zip(cue) { *out = master + cue; } + limiter.process(output); +} + pub(crate) struct CueOutput { input: rtrb::Consumer, health: Arc, @@ -286,15 +292,21 @@ impl CueOutput { } } - pub fn render(&mut self, data: &mut [f32], info: &cpal::OutputCallbackInfo) { - let frames = data.len() / 2; + pub fn render_channels(&mut self, data: &mut [f32], info: &cpal::OutputCallbackInfo, channels: usize, pair: [u16; 2]) { + let frames = data.len() / channels; let latency = observe(info, frames, &self.health.cue); let now_ns = self.epoch.elapsed().as_nanos() as u64; - self.render_at(data, latency.map(|ns| now_ns + ns)); + self.render_at_channels(data, latency.map(|ns| now_ns + ns), channels, pair); } + #[cfg(test)] fn render_at(&mut self, data: &mut [f32], playback_ns: Option) { - let frames = data.len() / 2; + self.render_at_channels(data, playback_ns, 2, [0, 1]); + } + + fn render_at_channels(&mut self, data: &mut [f32], playback_ns: Option, channels: usize, pair: [u16; 2]) { + let frames = data.len() / channels; + data.fill(0.0); let block = frames.max(self.health.master.frames.load(Ordering::Relaxed) as usize); let target = (self.sr as usize / 50).max(block * 2); if target + frames + TAPS > self.sr as usize * 2 { @@ -329,7 +341,7 @@ impl CueOutput { .servo .update(self.input.slots() as f64 - frames as f64 - target as f64, frames as f64 / self.sr as f64); let mut measured = false; - for (f, out) in data.as_chunks_mut::<2>().0.iter_mut().enumerate() { + for (f, out) in data.chunks_exact_mut(channels).enumerate() { if self.started { while self.phase >= 1.0 { if let Ok(h) = self.input.pop() { @@ -374,7 +386,8 @@ impl CueOutput { let want = if self.started { 1.0 } else { 0.0 }; self.gain += (want - self.gain).clamp(-1.0 / 128.0, 1.0 / 128.0); let delayed = self.delay.process(self.last, self.health.cue_delay.load(Ordering::Relaxed) as f64); - *out = delayed.map(|s| s * self.gain); + out[pair[0] as usize] = delayed[0] * self.gain; + out[pair[1] as usize] = delayed[1] * self.gain; } } @@ -662,6 +675,33 @@ mod tests { assert_eq!(health.cue_delay.load(Ordering::Relaxed), 0); } + #[test] + fn shared_physical_output_sums_buses_and_limits_without_modifying_recorded_master() { + let master = vec![0.7; 512]; + let cue = vec![0.6; 512]; + let mut output = vec![0.0; 512]; + let mut limiter = crate::dsp::Limiter::new(44100.0); + for _ in 0..10 { mix_shared_output(&master, &cue, &mut output, &mut limiter); } + assert!(output.iter().all(|v| v.is_finite() && v.abs() <= 1.0)); + assert!(output.iter().any(|v| *v > 0.7)); + assert!(master.iter().all(|v| *v == 0.7)); + assert!(cue.iter().all(|v| *v == 0.6)); + } + + #[test] + fn cue_can_use_an_arbitrary_stereo_pair_without_touching_other_channels() { + let health = Arc::new(OutputHealth::default()); + health.master.frames.store(256, Ordering::Relaxed); + let (mut tx, rx) = rtrb::RingBuffer::new(96000); + for _ in 0..2400 { tx.push(CueFrame { samples: [0.25, -0.5], master_ns: 0 }).unwrap(); } + let mut cue = CueOutput::new(rx, health, Instant::now(), 48000, 0.0); + let mut data = vec![9.0; 256 * 6]; + cue.render_at_channels(&mut data, None, 6, [4, 5]); + assert!(data.as_chunks::<6>().0.iter().all(|f| f[..4].iter().all(|s| *s == 0.0))); + assert!((data[data.len() - 2] - 0.25).abs() < 1e-4); + assert!((data[data.len() - 1] + 0.5).abs() < 1e-4); + } + #[test] fn cue_clock_renders_stereo_and_recovers_without_touching_master() { let health = Arc::new(OutputHealth::default()); diff --git a/crates/engine/tests/preview.rs b/crates/engine/tests/preview.rs index 7b7ba07..8695079 100644 --- a/crates/engine/tests/preview.rs +++ b/crates/engine/tests/preview.rs @@ -336,3 +336,34 @@ fn main_transport_cannot_stop_the_preview() { assert!(core.snapshot().preview.playing); assert!(cue.iter().any(|v| v.abs() > 0.01)); } + +#[test] +fn main_output_preview_has_independent_volume_and_never_enters_recording() { + for gain in [-60.0, 0.0, 12.0] { + let mut core = EngineCore::new(SR, 2); + core.set_shared_output(true); + core.apply(Command::SetMasterGain(gain)); + core.apply(Command::SetHeadphoneMix(1.0)); + let t = audio(); + // Also verifies migration of the old Master preview preference. + let _p = start(&mut core, PreviewOutput::Master, &t); + let (producer, mut recorded) = rtrb::RingBuffer::new(FRAMES * 4); + core.apply(Command::SetRecorder(Some(producer))); + let (master, cue) = block(&mut core); + assert!(master.iter().all(|v| *v == 0.0)); + assert!(cue.iter().any(|v| v.abs() > 0.01)); + while let Ok(sample) = recorded.pop() { assert_eq!(sample, 0.0); } + } + let t = audio(); + let mut loud = EngineCore::new(SR, 2); + let mut quiet = EngineCore::new(SR, 2); + loud.set_shared_output(true); + quiet.set_shared_output(true); + quiet.apply(Command::SetHeadphoneGain(-20.0)); + let _a = start(&mut loud, PreviewOutput::Master, &t); + let _b = start(&mut quiet, PreviewOutput::Master, &t); + let (_, a) = block(&mut loud); + let (_, b) = block(&mut quiet); + let energy = |x: &[f32]| x.iter().map(|v| v * v).sum::(); + assert!((energy(&b) / energy(&a) - 0.01).abs() < 0.002); +} diff --git a/docs/audio-output.md b/docs/audio-output.md index b883060..b37120b 100644 --- a/docs/audio-output.md +++ b/docs/audio-output.md @@ -119,10 +119,20 @@ alignment accuracy. ## Browser previews -Settings > Audio output > Preview output selects Master (the default, including older -preferences) or Headphones. Headphone preview is an explicit opt-in. Changing this preference stops the current preview and does not -restart the output device. It applies to Library, Studio Playlist and Mashups, Add tracks, -and the Live browser and Automix queue. +Settings > Audio output contains Master and Preview / headphones sections, with a device +and channel pair for each output. Main output uses the master's physical device and channels +while keeping MASTER and PHONES volumes independent. List previews and selected deck CUE +are summed with master only at the physical output, after recording, with a final limiter. +CUE/MIX is unavailable in this mode, so master is never added twice. Deck CUE can make an +already audible deck louder; all monitoring on this output is audible to the audience. +New installations use Main output by default. Existing settings are preserved until Apply. +Selecting a separate device supports its available stereo channel pairs; on the same device, +master and cue pairs must not overlap. No setting silently moves the master channel pair. +Sample rate, buffer and alignment correction are under Advanced audio settings. +Changes apply together with Apply; failed changes preserve the running output and preview +routing. Discard restores saved selections. Successful Apply stops any active preview. +A disconnected headphone output never falls back to master. These settings apply to Library, +Studio Playlist and Mashups, Add tracks, and the Live browser and Automix queue. Previews have their own two private decks and conductor. They never stop or reuse the main Studio or Live decks. Headphone previews are added after Cue/Master blending, before the @@ -136,8 +146,8 @@ track, at native tempo and key. ## Live headphone monitoring The headphone buttons beside each deck's filter select its pre-fader CUE signal; they do -not change its master output. CUE?MIX blends selected CUE channels with the master. At the +not change its master output. CUE/MIX blends selected CUE channels with the master. At the CUE end, headphones are silent when all deck headphone buttons are off (unless an independent -headphone preview is playing). Master monitoring is enabled only by turning CUE?MIX towards +headphone preview is playing). Master monitoring is enabled only by turning CUE/MIX towards MIX; it is never substituted automatically when no deck is selected. PHONES controls the combined headphone volume. From 0f3b259ad9c5485375cdbebadc519f021f2a69e8 Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Thu, 12 Nov 2026 10:16:53 +0300 Subject: [PATCH 3/4] Fix preview routing isolation and safe output defaults --- crates/app/src/app.rs | 6 +- crates/app/src/live/adapter.rs | 19 ++-- crates/app/src/live/model.rs | 4 +- crates/app/src/live/view.rs | 4 +- crates/app/src/prefs.rs | 37 ++++++-- crates/app/src/preview.rs | 68 +++++++++++++- crates/app/src/settings.rs | 159 +++++++++++++++++++++++---------- crates/engine/src/command.rs | 6 +- crates/engine/src/core.rs | 14 +-- crates/engine/src/engine.rs | 85 +++++++++++------- crates/engine/src/mixer.rs | 34 ++----- crates/engine/src/output.rs | 8 +- crates/engine/src/player.rs | 5 +- crates/engine/tests/preview.rs | 82 +++++++++-------- docs/audio-output.md | 51 ++++++----- 15 files changed, 377 insertions(+), 205 deletions(-) diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index 5da0c74..f62c9fd 100644 --- a/crates/app/src/app.rs +++ b/crates/app/src/app.rs @@ -296,7 +296,8 @@ impl App { } } if self.eng.preview_player.is_none() { self.sh.preview.item = None; } - self.sh.preview.output = self.prefs.preview_output; + self.sh.preview.output = if self.eng.preview_player.is_some() { self.eng.preview_output } + else { self.eng.handle.as_ref().map(|h| crate::preview::target_output(self.prefs.preview_output, &h.audio_config(), &h.stream_info())).unwrap_or(self.prefs.preview_output) }; self.sh.preview.loading = self.eng.preview_player.is_some() && self.eng.state().preview.waiting; // the track a preview would start on, loaded ahead so Space plays at once if self.view == View::Studio && self.eng.studio_player.is_none() { @@ -452,7 +453,6 @@ impl App { let p = self.prefs.clone(); let first = self.applied_prefs.is_none(); if self.applied_prefs.as_ref().is_some_and(|old| old.preview_output != p.preview_output) { self.stop_preview(); } - self.sh.preview.output = p.preview_output; crate::theme::set_key_notation(p.key_notation); crate::theme::set_soft_stems(p.soft_stem_colors); if first || self.applied_prefs.as_ref().map(|o| o.accent) != Some(p.accent) { @@ -671,6 +671,7 @@ impl App { fn start_preview(&mut self, mix: &clubcraft_core::Mix, from: f64, item: crate::preview::PreviewItem) { match self.eng.play_preview(mix, from, &self.sh) { Ok(()) => { + self.sh.preview.output = self.eng.preview_output; self.sh.preview.item = Some(item); self.sh.preview.mix_serial = self.studio.mix_serial; self.sh.preview.mashup_revision = self.studio.mashup.revision; @@ -699,7 +700,6 @@ impl App { fn reconcile_preview(&mut self) { use crate::preview::PreviewSource as P; - self.sh.preview.main_output = self.eng.handle.as_ref().is_some_and(|h| h.audio_config().headphones == clubcraft_engine::HeadphoneRouting::MainOutput); let Some(item) = self.sh.preview.item else { return; }; let visible = match item.source { P::Library { playlist, mix } => self.view == View::Library && playlist == self.library.playlist && mix == self.library.mix, diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index 357f066..c3c3c5c 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -381,6 +381,7 @@ pub struct LiveEngine { pub live_player: Option, /// Independent browser/mashup preview (private decks, separate transport). pub preview_player: Option, + pub preview_output: clubcraft_engine::command::PreviewOutput, pub loading_mix: Option, pub export: Option, pub automix_queue: Vec, @@ -526,6 +527,7 @@ impl LiveEngine { studio_player: None, live_player: None, preview_player: None, + preview_output: clubcraft_engine::command::PreviewOutput::Headphones, loading_mix: None, export: None, automix_queue: Vec::new(), @@ -580,14 +582,11 @@ impl LiveEngine { /// Play a browser/mashup preview on its private decks from `from` seconds. pub fn play_preview(&mut self, mix: &Mix, from: f64, sh: &Shared) -> Result<()> { - use clubcraft_engine::command::PreviewOutput; use clubcraft_engine::player::PreviewSink; - let output = self.prefs.preview_output; let h = self.handle.as_ref().context("Audio output is unavailable")?; - if output == PreviewOutput::Headphones && !crate::preview::headphones_available(&h.stream_info()) { - anyhow::bail!("Headphone output is unavailable. Configure Audio output in Settings."); - } + let output = crate::preview::resolve_output(self.prefs.preview_output, &h.audio_config(), &h.stream_info())?; self.stop_preview(); + self.preview_output = output; let mut p = MixPlayer::lazy(mix, &|id| { let mut a = sh.analyses.get(&id).cloned().unwrap_or_default(); if a.duration <= 0.0 { a.duration = sh.track(id).map(|t| t.duration).unwrap_or(0.0); } @@ -602,7 +601,7 @@ impl LiveEngine { pub fn stop_preview(&mut self) { if let (Some(mut p), Some(h)) = (self.preview_player.take(), self.handle.as_mut()) { - let _ = p.stop(&mut clubcraft_engine::player::PreviewSink { sink: h, output: self.prefs.preview_output }); + let _ = p.stop(&mut clubcraft_engine::player::PreviewSink { sink: h, output: self.preview_output }); } } @@ -728,12 +727,12 @@ impl LiveEngine { } } let mut stop_preview = false; - let output = self.prefs.preview_output; + let output = self.preview_output; if let (Some(p), Some(h)) = (self.preview_player.as_mut(), self.handle.as_mut()) { let mut preview_state = st; preview_state.mix = st.preview; - if output == clubcraft_engine::command::PreviewOutput::Headphones && !crate::preview::headphones_available(&h.stream_info()) { - messages.push("Headphone output is unavailable; preview stopped".into()); + if !crate::preview::output_available(output, &h.stream_info()) { + messages.push(format!("{} is unavailable; preview stopped", output.label())); stop_preview = true; } else if st.preview.schedule_id == p.schedule_id() && st.preview.finished { stop_preview = true; @@ -1028,7 +1027,7 @@ pub fn mixer_ui(st: &EngineState, eng: &LiveEngine) -> MixerUi { crossfader: st.master.crossfader * 2.0 - 1.0, master: db_knob(st.master.gain_db, 0.8), headphone_mix: st.master.headphone_mix, - shared_output: eng.handle.as_ref().is_some_and(|h| h.audio_config().headphones == clubcraft_engine::HeadphoneRouting::MainOutput), + cue_available: eng.handle.as_ref().is_some_and(|h| h.stream_info().cue_channels.is_some()), headphone_vol: db_knob(st.master.headphone_gain_db, 0.7), master_vu: st.master.level.peak, recording: st.recording.active, diff --git a/crates/app/src/live/model.rs b/crates/app/src/live/model.rs index 7fadfb0..e071ec1 100644 --- a/crates/app/src/live/model.rs +++ b/crates/app/src/live/model.rs @@ -110,7 +110,7 @@ pub struct MixerUi { pub crossfader: f32, pub master: f32, pub headphone_mix: f32, - pub shared_output: bool, + pub cue_available: bool, pub headphone_vol: f32, pub master_vu: [f32; 2], pub recording: bool, @@ -192,6 +192,6 @@ pub enum LiveAction { impl Default for MixerUi { fn default() -> Self { - MixerUi { crossfader: 0.0, master: 0.8, headphone_mix: 0.0, shared_output: false, headphone_vol: 0.7, master_vu: [0.0; 2], recording: false, record_secs: 0.0, master_bpm: None, automix: false, output_name: String::new() } + MixerUi { crossfader: 0.0, master: 0.8, headphone_mix: 0.0, cue_available: false, headphone_vol: 0.7, master_vu: [0.0; 2], recording: false, record_secs: 0.0, master_bpm: None, automix: false, output_name: String::new() } } } diff --git a/crates/app/src/live/view.rs b/crates/app/src/live/view.rs index 66ecd55..8e1e634 100644 --- a/crates/app/src/live/view.rs +++ b/crates/app/src/live/view.rs @@ -599,11 +599,11 @@ impl LiveView { ui.horizontal(|ui| { ui.add_space((ui.available_width() - 72.0).max(0.0) / 2.0); let mut hm = m.headphone_mix; - ui.add_enabled_ui(!m.shared_output, |ui| { + ui.add_enabled_ui(m.cue_available, |ui| { if widgets::knob(ui, &mut hm, 0.0..=1.0, 0.0, "CUE·MIX", theme::TEXT, 32.0).on_hover_text("CUE: selected decks only; MIX: master. With no CUE selected, the CUE end is silent.").changed() { out.push(LiveAction::HeadphoneMix(hm)); } - }).response.on_disabled_hover_text("Master already plays through Main output."); + }).response.on_disabled_hover_text("No headphone output is configured."); let mut hv = m.headphone_vol; if widgets::knob(ui, &mut hv, 0.0..=1.0, 0.7, "PHONES", theme::TEXT, 32.0).changed() { out.push(LiveAction::HeadphoneVol(hv)); diff --git a/crates/app/src/prefs.rs b/crates/app/src/prefs.rs index f347a3a..6917f71 100644 --- a/crates/app/src/prefs.rs +++ b/crates/app/src/prefs.rs @@ -132,7 +132,7 @@ pub struct Prefs { /// Open the home page on start (otherwise the last view). pub start_on_home: bool, pub accent: Accent, - /// Preferences format; files older than 2 used the pink accent by default. Missing in old + /// Preferences format; version 4 migrates unsafe preview routing to Auto. Missing in old /// files, so it defaults to 0 there (not to `Prefs::default()`). #[serde(default)] pub version: u32, @@ -193,7 +193,7 @@ impl Default for Prefs { ui_scale: 1.0, start_on_home: true, accent: Accent::White, - version: 3, + version: 4, cue_button: CueButton::Cdj, hot_cue_press: HotCuePress::Preview, load_position: LoadPosition::FirstBeat, @@ -237,6 +237,12 @@ impl Prefs { pub fn load() -> Prefs { let mut p: Prefs = std::fs::read_to_string(Self::path()).ok().and_then(|s| serde_json::from_str(&s).ok()).unwrap_or_default(); + p.migrate(); + p + } + + fn migrate(&mut self) { + let p = self; if p.version < 2 { // white is the new default accent (it used to be pink) p.accent = Accent::White; @@ -246,8 +252,11 @@ impl Prefs { // the background: that kept the machine busy for hours p.separate_stems = false; } - p.version = p.version.max(3); - p + if p.version < 4 { + // Old preview preferences could send previews to the recorded master bus. + p.preview_output = clubcraft_engine::command::PreviewOutput::Auto; + } + p.version = p.version.max(4); } pub fn save(&self) { @@ -331,16 +340,30 @@ mod migration_tests { use super::*; #[test] - fn preview_output_defaults_to_master_and_round_trips() { + fn preview_output_defaults_to_auto_and_round_trips() { use clubcraft_engine::command::PreviewOutput; let old: Prefs = serde_json::from_str(r#"{"version": 3}"#).unwrap(); - assert_eq!(old.preview_output, PreviewOutput::Master); - assert_eq!(Prefs::default().preview_output, PreviewOutput::Master); + assert_eq!(old.preview_output, PreviewOutput::Auto); + assert_eq!(Prefs::default().preview_output, PreviewOutput::Auto); let prefs = Prefs { preview_output: PreviewOutput::Headphones, ..Default::default() }; let loaded: Prefs = serde_json::from_str(&serde_json::to_string(&prefs).unwrap()).unwrap(); assert_eq!(loaded.preview_output, PreviewOutput::Headphones); } + #[test] + fn old_preview_choices_migrate_once_without_changing_other_preferences() { + use clubcraft_engine::command::PreviewOutput; + for choice in ["Master", "Headphones"] { + let mut prefs: Prefs = serde_json::from_str(&format!(r#"{{"version":3,"preview_output":"{choice}","ui_scale":1.25}}"#)).unwrap(); + prefs.migrate(); + assert_eq!(prefs.preview_output, PreviewOutput::Auto); + assert_eq!(prefs.ui_scale, 1.25); + prefs.preview_output = PreviewOutput::Master; + prefs.migrate(); + assert_eq!(prefs.preview_output, PreviewOutput::Master); + } + } + #[test] fn old_files_get_the_white_accent() { let old: Prefs = serde_json::from_str(r#"{"accent": "Pink", "ui_scale": 1.2}"#).unwrap(); diff --git a/crates/app/src/preview.rs b/crates/app/src/preview.rs index c9b0213..8847e2c 100644 --- a/crates/app/src/preview.rs +++ b/crates/app/src/preview.rs @@ -30,14 +30,13 @@ pub struct PreviewItem { pub struct PreviewState { pub item: Option, pub output: PreviewOutput, - pub main_output: bool, pub loading: bool, pub mix_serial: u64, pub mashup_revision: u64, } impl PreviewState { - pub fn output_label(&self) -> &'static str { if self.main_output { "Main output" } else { self.output.label() } } + pub fn output_label(&self) -> &'static str { self.output.label() } pub fn playing(&self, source: PreviewSource, track: TrackId, row: usize) -> bool { self.item == Some(PreviewItem { source, track, row }) } @@ -70,6 +69,34 @@ impl PreviewState { } } +/// Auto uses the running endpoint; a configured but failed headphone route is never a speaker fallback. +pub fn target_output(preference: PreviewOutput, config: &clubcraft_engine::AudioConfig, info: &clubcraft_engine::StreamInfo) -> PreviewOutput { + use clubcraft_engine::HeadphoneRouting as H; + if preference != PreviewOutput::Auto { return preference; } + if info.cue_channels.is_some() || matches!(config.headphones, H::SeparateDevice | H::Channels { .. } | H::Split) { + PreviewOutput::Headphones + } else { + PreviewOutput::Master + } +} + +pub fn output_available(output: PreviewOutput, info: &clubcraft_engine::StreamInfo) -> bool { + match output { + PreviewOutput::Auto => false, + PreviewOutput::Master => !info.master.failed, + PreviewOutput::Headphones => headphones_available(info), + } +} + +pub fn resolve_output(preference: PreviewOutput, config: &clubcraft_engine::AudioConfig, info: &clubcraft_engine::StreamInfo) -> anyhow::Result { + let output = target_output(preference, config, info); + if info.master.failed { anyhow::bail!("Audio output is unavailable. Apply audio settings to retry."); } + if output == PreviewOutput::Headphones && !headphones_available(info) { + anyhow::bail!("Headphone output is unavailable. Configure Audio output in Settings."); + } + Ok(output) +} + pub fn headphones_available(info: &clubcraft_engine::StreamInfo) -> bool { info.cue_channels.is_some() && !info.master.failed @@ -160,6 +187,43 @@ mod tests { } } + #[test] + fn automatic_output_uses_running_routes_and_never_falls_back_from_a_failed_route() { + use clubcraft_engine::{AudioConfig, HeadphoneRouting as H}; + let mut info = output(); + let mut cfg = AudioConfig::default(); + assert_eq!(cfg.headphones, H::Auto); + assert_eq!(resolve_output(PreviewOutput::Auto, &cfg, &info).unwrap(), PreviewOutput::Master); + assert!(resolve_output(PreviewOutput::Headphones, &cfg, &info).is_err()); + info.cue_channels = Some([2, 3]); + assert_eq!(resolve_output(PreviewOutput::Auto, &cfg, &info).unwrap(), PreviewOutput::Headphones); + info.headphones = Some(info.master.clone()); + info.headphones.as_mut().unwrap().failed = true; + assert!(resolve_output(PreviewOutput::Auto, &cfg, &info).is_err()); + info = output(); + cfg.headphones = H::SeparateDevice; + assert!(resolve_output(PreviewOutput::Auto, &cfg, &info).is_err()); + // Legacy shared output has no headphone endpoint and cannot carry deck CUE. + cfg.headphones = H::MainOutput; + assert_eq!(resolve_output(PreviewOutput::Auto, &cfg, &info).unwrap(), PreviewOutput::Master); + info.master.failed = true; + assert!(resolve_output(PreviewOutput::Auto, &cfg, &info).is_err()); + } + + #[test] + fn loss_does_not_retarget_an_active_or_loading_preview() { + use clubcraft_engine::AudioConfig; + let cfg = AudioConfig::default(); + let mut info = output(); + info.cue_channels = Some([2, 3]); + let active = resolve_output(PreviewOutput::Auto, &cfg, &info).unwrap(); + assert_eq!(active, PreviewOutput::Headphones); + info.cue_channels = None; + assert!(!output_available(active, &info)); + // Only a new request on a running stereo fallback can resolve to speakers. + assert_eq!(resolve_output(PreviewOutput::Auto, &cfg, &info).unwrap(), PreviewOutput::Master); + } + #[test] fn preview_requires_a_running_cue_output_not_just_a_saved_selection() { let mut info = output(); diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index 64eb539..8475b96 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -30,7 +30,7 @@ fn output_channels(devices: &[DeviceInfo], id: Option<&str>) -> u16 { } fn master_pair(cfg: &AudioConfig) -> [u16; 2] { - match cfg.headphones { HeadphoneRouting::Channels { master, .. } => master, _ => cfg.master_pair } + match cfg.headphones { HeadphoneRouting::Channels { master, .. } => master, HeadphoneRouting::Auto | HeadphoneRouting::Split => [0, 1], _ => cfg.master_pair } } fn cue_pair(cfg: &AudioConfig) -> [u16; 2] { @@ -265,6 +265,21 @@ impl Settings { } } + fn discard_audio_draft(&mut self, prefs: &Prefs) { + self.audio_draft = self.audio.clone(); + self.preview_draft = Some(prefs.preview_output); + } + + fn apply_audio_draft(&mut self, prefs: &mut Prefs, open: impl FnOnce(&AudioConfig) -> anyhow::Result) -> anyhow::Result<()> { + let audio = open(&self.audio_draft)?; + let preview = self.preview_draft.unwrap_or(prefs.preview_output); + self.sync_audio(audio); + prefs.preview_output = preview; + self.preview_draft = Some(preview); + self.stop_preview = true; + Ok(()) + } + fn audio_ui(&mut self, ui: &mut egui::Ui, handle: Option<&EngineHandle>, prefs: &mut Prefs) { use clubcraft_engine::command::PreviewOutput; if self.devices.is_empty() { @@ -288,36 +303,39 @@ impl Settings { channel_pair(ui, "master_channels", &mut master, output_channels(&self.devices, cfg.device.as_deref()), None); ui.end_row(); }); - section(ui, "Preview / headphones"); - // Legacy Master preferences are displayed as Main output and converted only on Apply. - let legacy_main = preview == PreviewOutput::Master; - if legacy_main { cfg.headphones = HeadphoneRouting::MainOutput; } - egui::Grid::new("preview_output").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { - ui.label("Device"); + let previous_routing = cfg.headphones; + section(ui, "Headphones"); + egui::Grid::new("headphone_output").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { + ui.label("Routing / device"); let label = match cfg.headphones { - HeadphoneRouting::MainOutput | HeadphoneRouting::Off => "Main output".into(), + HeadphoneRouting::Auto => "Auto (outputs 3/4 if available)".into(), + HeadphoneRouting::Off => "Off".into(), + HeadphoneRouting::MainOutput => "Off (legacy Main output)".into(), + HeadphoneRouting::Split => "Split cable (master L / cue R)".into(), HeadphoneRouting::SeparateDevice => device_label(&self.devices, cfg.headphone_device.as_deref(), "Select device..."), - HeadphoneRouting::Split => "Split cable (saved configuration)".into(), - _ => device_label(&self.devices, cfg.device.as_deref(), "System default"), + HeadphoneRouting::Channels { .. } => "Channel pairs on master device".into(), }; - egui::ComboBox::from_id_salt("preview_device").width(300.0).selected_text(label).show_ui(ui, |ui| { - if ui.selectable_label(matches!(cfg.headphones, HeadphoneRouting::MainOutput | HeadphoneRouting::Off), "Main output").clicked() { - cfg.headphones = HeadphoneRouting::MainOutput; - preview = PreviewOutput::Headphones; + egui::ComboBox::from_id_salt("headphone_device").width(300.0).selected_text(label).show_ui(ui, |ui| { + ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Auto, "Auto (outputs 3/4 if available)"); + ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Off, "Off"); + ui.selectable_value(&mut cfg.headphones, HeadphoneRouting::Split, "Split cable (master L / cue R)"); + if ui.add_enabled(output_channels(&self.devices, cfg.device.as_deref()) >= 4, + egui::Button::selectable(matches!(cfg.headphones, HeadphoneRouting::Channels { .. }), "Channel pairs on master device")).clicked() { + cfg.headphones = HeadphoneRouting::Channels { master, cue: [2, 3] }; + cue = [2, 3]; } for d in &self.devices { let same = cfg.device.as_deref().map_or(d.is_default, |id| d.id == id || d.name == id); - let selected = if same { matches!(cfg.headphones, HeadphoneRouting::Channels { .. } | HeadphoneRouting::Auto | HeadphoneRouting::Split) } - else { cfg.headphones == HeadphoneRouting::SeparateDevice && cfg.headphone_device.as_deref() == Some(&d.id) }; - if ui.add_enabled(!d.id.is_empty() && (!same || d.max_channels >= 4), egui::Button::selectable(selected, device_choice(d, &self.devices))).clicked() { - preview = PreviewOutput::Headphones; - if same { cfg.headphones = HeadphoneRouting::Channels { master, cue: [2, 3] }; cue = [2, 3]; } - else { cfg.headphones = HeadphoneRouting::SeparateDevice; cfg.headphone_device = Some(d.id.clone()); cue = [0, 1]; } + let selected = cfg.headphones == HeadphoneRouting::SeparateDevice && cfg.headphone_device.as_deref() == Some(&d.id); + if ui.add_enabled(!d.id.is_empty() && !same, egui::Button::selectable(selected, device_choice(d, &self.devices))).clicked() { + cfg.headphones = HeadphoneRouting::SeparateDevice; + cfg.headphone_device = Some(d.id.clone()); + cue = [0, 1]; } } }); ui.end_row(); - if !matches!(cfg.headphones, HeadphoneRouting::MainOutput | HeadphoneRouting::Off | HeadphoneRouting::Split) { + if matches!(cfg.headphones, HeadphoneRouting::SeparateDevice | HeadphoneRouting::Channels { .. }) { ui.label("Channels"); let separate = cfg.headphones == HeadphoneRouting::SeparateDevice; let channels = output_channels(&self.devices, if separate { cfg.headphone_device.as_deref() } else { cfg.device.as_deref() }); @@ -325,16 +343,28 @@ impl Settings { ui.end_row(); } }); - if let HeadphoneRouting::Channels { .. } | HeadphoneRouting::Auto = cfg.headphones { + if cfg.headphones != previous_routing && matches!(cfg.headphones, HeadphoneRouting::Auto | HeadphoneRouting::Split) { + master = [0, 1]; + cue = if cfg.headphones == HeadphoneRouting::Auto { [2, 3] } else { [0, 1] }; + } + if matches!(cfg.headphones, HeadphoneRouting::Channels { .. }) { + cfg.headphones = HeadphoneRouting::Channels { master, cue }; + } + // Auto and Split have fixed master channels; selecting another pair explicitly leaves those modes. + if matches!(cfg.headphones, HeadphoneRouting::Auto | HeadphoneRouting::Split) && master != [0, 1] { cfg.headphones = HeadphoneRouting::Channels { master, cue }; } cfg.master_pair = master; cfg.headphone_pair = cue; - if matches!(cfg.headphones, HeadphoneRouting::MainOutput | HeadphoneRouting::Off) { - hint(ui, "MASTER controls the main mix; PHONES controls previews and headphone cue. Only the main mix is recorded."); - } else { - hint(ui, "Shared output for list previews and deck headphone buttons. A disconnected output never falls back to master."); - } + section(ui, "Preview"); + ui.horizontal(|ui| { + ui.label("Preview output"); + for output in [PreviewOutput::Auto, PreviewOutput::Headphones, PreviewOutput::Master] { + ui.selectable_value(&mut preview, output, output.label()); + } + }); + hint(ui, "Auto uses headphones when configured, otherwise the main output. Deck CUE never goes to the speakers. Previews are never recorded; PHONES controls their volume."); + if preview == PreviewOutput::Master { ui.colored_label(theme::WARN, "Main output previews are audible to the audience."); } if ui.small_button("Rescan devices").clicked() { self.devices = clubcraft_engine::devices().unwrap_or_default(); } ui.collapsing("Advanced audio settings", |ui| { egui::Grid::new("audio_advanced").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { @@ -391,33 +421,29 @@ impl Settings { self.audio_draft = cfg.clone(); ui.horizontal(|ui| { if ui.button("Apply").clicked() { - if cfg == self.audio { - self.stop_preview = true; - prefs.preview_output = PreviewOutput::Headphones; - self.preview_draft = Some(PreviewOutput::Headphones); - self.message = "Audio output changed".into(); - } else if let Some(h) = handle { - match h.set_audio_config(cfg) { - Ok(()) => { - self.sync_audio(h.audio_config()); - self.stop_preview = true; - prefs.preview_output = PreviewOutput::Headphones; - self.preview_draft = Some(PreviewOutput::Headphones); - self.message = "Audio output changed".into(); + let previous = self.audio.clone(); + let result = self.apply_audio_draft(prefs, |cfg| { + if let Some(h) = handle { + // A preview-only change need not restart a healthy, unchanged stream. + let info = h.stream_info(); + if *cfg != previous || h.audio_config() != *cfg || info.master.failed + || info.headphones.as_ref().is_some_and(|h| h.failed) + || (cfg.headphones == HeadphoneRouting::SeparateDevice && info.cue_channels.is_none()) { + h.set_audio_config(cfg.clone())?; } - Err(e) => self.message = format!("Audio: {e:#}"), + Ok(h.audio_config()) + } else { Ok(cfg.clone()) } + }); + match result { + Ok(()) => { + self.restart_audio = handle.is_none(); + self.message = "Audio output changed".into(); } - } else { - self.audio = cfg; - self.stop_preview = true; - prefs.preview_output = PreviewOutput::Headphones; - self.preview_draft = Some(PreviewOutput::Headphones); - self.restart_audio = true; + Err(e) => self.message = format!("Audio: {e:#}"), } } if ui.add_enabled(self.audio_draft != self.audio || preview != prefs.preview_output, egui::Button::new("Discard changes")).clicked() { - self.audio_draft = self.audio.clone(); - self.preview_draft = Some(prefs.preview_output); + self.discard_audio_draft(prefs); } }); } @@ -795,3 +821,38 @@ fn export_ui(ui: &mut Ui, p: &mut Prefs) { }); hint(ui, &format!("Recordings go to {}", clubcraft_core::paths::recordings_dir().display())); } + +#[cfg(test)] +mod audio_tests { + use super::*; + use clubcraft_engine::command::PreviewOutput; + + #[test] + fn failed_apply_keeps_running_settings_and_preview_and_discard_restores_drafts() { + let mut settings = Settings::new(AudioConfig::default(), None); + let mut prefs = Prefs::default(); + let old = settings.audio.clone(); + settings.audio_draft.headphones = HeadphoneRouting::SeparateDevice; + settings.preview_draft = Some(PreviewOutput::Master); + assert!(settings.apply_audio_draft(&mut prefs, |_| anyhow::bail!("device unavailable")).is_err()); + assert_eq!(settings.audio, old); + assert_eq!(prefs.preview_output, PreviewOutput::Auto); + assert!(!settings.stop_preview); + settings.discard_audio_draft(&prefs); + assert_eq!(settings.audio_draft, old); + assert_eq!(settings.preview_draft, Some(PreviewOutput::Auto)); + } + + #[test] + fn successful_apply_commits_both_drafts_and_stops_preview() { + let mut settings = Settings::new(AudioConfig::default(), None); + let mut prefs = Prefs::default(); + settings.audio_draft.headphones = HeadphoneRouting::Off; + settings.preview_draft = Some(PreviewOutput::Master); + settings.apply_audio_draft(&mut prefs, |cfg| Ok(cfg.clone())).unwrap(); + assert_eq!(settings.audio.headphones, HeadphoneRouting::Off); + assert_eq!(prefs.preview_output, PreviewOutput::Master); + assert!(settings.stop_preview); + assert_eq!(settings.audio, settings.audio_draft); + } +} diff --git a/crates/engine/src/command.rs b/crates/engine/src/command.rs index 59d214d..e4f92f9 100644 --- a/crates/engine/src/command.rs +++ b/crates/engine/src/command.rs @@ -25,14 +25,16 @@ pub enum EqBand { /// Destination of the independent browser preview. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, serde::Serialize, serde::Deserialize)] pub enum PreviewOutput { - Headphones, #[default] + Auto, + Headphones, + /// Physical main output only, downstream of the recorded master bus. Master, } impl PreviewOutput { pub fn label(self) -> &'static str { - match self { Self::Headphones => "Headphones", Self::Master => "Master" } + match self { Self::Auto => "Auto", Self::Headphones => "Headphones", Self::Master => "Main output" } } } diff --git a/crates/engine/src/core.rs b/crates/engine/src/core.rs index 4a9f4e2..df2314d 100644 --- a/crates/engine/src/core.rs +++ b/crates/engine/src/core.rs @@ -109,10 +109,6 @@ impl EngineCore { /// Change the output rate. Rebuilds the mixer and FX (allocates) — not for the audio thread. /// Deck state (tracks, positions, cues, loops) is preserved. - pub fn set_shared_output(&mut self, shared: bool) { - self.mixer.shared_output = shared; - } - pub fn set_sample_rate(&mut self, sr: u32) { if sr == self.sr { return; @@ -136,7 +132,6 @@ impl EngineCore { self.mixer.headphone_gain_db = old.headphone_gain_db; self.mixer.auto_gain = old.auto_gain; self.mixer.preview_output = old.preview_output; - self.mixer.shared_output = old.shared_output; self.mixer.limiter.enabled = old.limiter.enabled; self.mixer.limiter.set_ceiling_db(crate::dsp::gain_to_db(old.limiter.ceiling())); for d in self.decks.iter_mut() { @@ -620,6 +615,12 @@ impl EngineCore { /// Render `master.len() / 2` frames. `master` and `cue` are interleaved stereo of equal /// length (`cue` = headphone bus). pub fn process(&mut self, master: &mut [f32], cue: &mut [f32]) { + self.process_outputs(master, cue, &mut []); + } + + /// Render the recorded master, headphone cue and isolated speaker preview buses. + /// Only the device callback sums the third bus into the physical main output. + pub fn process_outputs(&mut self, master: &mut [f32], cue: &mut [f32], preview: &mut [f32]) { let frames = master.len() / 2; let mut done = 0; while done < frames { @@ -629,6 +630,9 @@ impl EngineCore { if cue.len() >= (done + n) * 2 { cue[done * 2..(done + n) * 2].copy_from_slice(&self.cue_buf[..n * 2]); } + if preview.len() >= (done + n) * 2 { + preview[done * 2..(done + n) * 2].copy_from_slice(&self.mixer.speaker_preview[..n * 2]); + } done += n; } let tp = std::time::Instant::now(); diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index b1250d0..7223f9b 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -25,7 +25,7 @@ use std::time::{Duration, Instant}; /// Where the headphone (cue) bus goes. #[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] pub enum HeadphoneRouting { - /// Independent cue/preview volume summed into the physical master output. + /// Legacy main-output preview mode. Deck CUE has no physical output. MainOutput, /// Channels 3/4 when the device has ≥ 4 outputs, otherwise no headphone output. #[default] @@ -71,7 +71,7 @@ fn stereo_pair() -> [u16; 2] { [0, 1] } impl Default for AudioConfig { fn default() -> Self { - AudioConfig { device: None, sample_rate: None, buffer_frames: Some(256), headphones: HeadphoneRouting::MainOutput, + AudioConfig { device: None, sample_rate: None, buffer_frames: Some(256), headphones: HeadphoneRouting::Auto, headphone_device: None, master_pair: [0, 1], headphone_pair: [0, 1], alignment_ms: 0.0, alignment_key: None, decks: 4 } } } @@ -384,22 +384,10 @@ fn bind_alignment(config: &mut AudioConfig, key: String) { config.alignment_key = Some(key); } -fn prepare(config: &AudioConfig) -> Result { - if !config.alignment_ms.is_finite() || config.alignment_ms.abs() > 500.0 { - bail!("headphone alignment must be between -500 and 500 ms"); - } - if ![2, 4].contains(&config.decks) { bail!("select 2 or 4 decks"); } - if config.buffer_frames == Some(0) { bail!("audio buffer must not be zero"); } - let host = cpal::default_host(); - let device = find_device(&host, config.device.as_deref())?; - let name = device_name(&device); - let ranges: Vec = - device.supported_output_configs()?.filter(|c| c.sample_format() == cpal::SampleFormat::F32).collect(); - if ranges.is_empty() { - bail!("device {name} has no f32 output configuration"); - } - let max_ch = ranges.iter().map(|r| r.channels()).max().unwrap_or(2); - let (want_ch, master_ch, cue_ch, split) = match config.headphones { +type ChannelRouting = (u16, [u16; 2], Option<[u16; 2]>, bool); + +fn channel_routing(config: &AudioConfig, max_ch: u16) -> Result { + Ok(match config.headphones { HeadphoneRouting::Auto if max_ch >= 4 => (4u16, [0u16, 1], Some([2u16, 3]), false), HeadphoneRouting::Auto => (2, [0, 1], None, false), HeadphoneRouting::MainOutput | HeadphoneRouting::Off | HeadphoneRouting::SeparateDevice => { @@ -407,13 +395,13 @@ fn prepare(config: &AudioConfig) -> Result { if master[0] == master[1] { bail!("select distinct left and right master channels"); } let need = master.iter().copied().max().unwrap_or(1).checked_add(1).ok_or_else(|| anyhow!("invalid master channels"))?; if need > max_ch { bail!("master device has only {max_ch} outputs"); } - (need.max(2), master, if config.headphones == HeadphoneRouting::MainOutput { Some(master) } else { None }, false) + (need.max(2), master, None, false) }, HeadphoneRouting::Channels { master, cue } => { let need = master.iter().chain(cue.iter()).copied().max().unwrap_or(1).checked_add(1) .ok_or_else(|| anyhow!("invalid output channel"))?; if need > max_ch { - bail!("device {name} has only {max_ch} outputs"); + bail!("master device has only {max_ch} outputs"); } let mut used = [master[0], master[1], cue[0], cue[1]]; used.sort(); @@ -421,7 +409,25 @@ fn prepare(config: &AudioConfig) -> Result { (need.max(2), master, Some(cue), false) } HeadphoneRouting::Split => (2, [0, 1], Some([0, 1]), true), - }; + }) +} + +fn prepare(config: &AudioConfig) -> Result { + if !config.alignment_ms.is_finite() || config.alignment_ms.abs() > 500.0 { + bail!("headphone alignment must be between -500 and 500 ms"); + } + if ![2, 4].contains(&config.decks) { bail!("select 2 or 4 decks"); } + if config.buffer_frames == Some(0) { bail!("audio buffer must not be zero"); } + let host = cpal::default_host(); + let device = find_device(&host, config.device.as_deref())?; + let name = device_name(&device); + let ranges: Vec = + device.supported_output_configs()?.filter(|c| c.sample_format() == cpal::SampleFormat::F32).collect(); + if ranges.is_empty() { + bail!("device {name} has no f32 output configuration"); + } + let max_ch = ranges.iter().map(|r| r.channels()).max().unwrap_or(2); + let (want_ch, master_ch, cue_ch, split) = channel_routing(config, max_ch)?; let cue_device = if config.headphones == HeadphoneRouting::SeparateDevice { let id = config.headphone_device.as_deref().ok_or_else(|| anyhow!("select a headphone output device"))?; let cue = find_device(&host, Some(id))?; @@ -546,10 +552,11 @@ fn open_stream( let mut last_start: Option = None; let mut window = (0f32, 0f32); // (peak in the current ~2 s window, seconds in it) let mc = master_ch; - let shared = config.headphones == HeadphoneRouting::MainOutput; let cc = cue_ch; let mut shared_limiter = crate::dsp::Limiter::new(sr as f32); + let speaker_latency = shared_limiter.latency() as u64; let mut shared_buffer = vec![0.0; SCRATCH_FRAMES * 2]; + let mut preview_buffer = vec![0.0; SCRATCH_FRAMES * 2]; let err2 = errors.clone(); let data_cb = move |data: &mut [f32], callback: &cpal::OutputCallbackInfo| { let t0 = Instant::now(); @@ -579,28 +586,26 @@ fn open_stream( while done < frames { let n = (frames - done).min(SCRATCH_FRAMES); let (m, c) = (&mut side.master[..n * 2], &mut side.cue[..n * 2]); - side.core.process(m, c); - if shared { - output::mix_shared_output(m, c, &mut shared_buffer[..n * 2], &mut shared_limiter); - } + side.core.process_outputs(m, c, &mut preview_buffer[..n * 2]); + output::mix_speaker_preview(m, &preview_buffer[..n * 2], &mut shared_buffer[..n * 2], &mut shared_limiter); let out = &mut data[done * ch..(done + n) * ch]; out.fill(0.0); for f in 0..n { let o = &mut out[f * ch..(f + 1) * ch]; if separate && !master_health.cue.failed.load(Ordering::Relaxed) { let frame = CueFrame { samples: [c[f * 2], c[f * 2 + 1]], master_ns: presentation - .map(|ns| ns + ((done + f) as u64 * 1_000_000_000 / sr as u64)).unwrap_or(0) }; + .map(|ns| ns + (((done + f) as u64 + speaker_latency) * 1_000_000_000 / sr as u64)).unwrap_or(0) }; if cue_tx.push(frame).is_err() { overflow = true; } } if split { - o[0] = 0.5 * (m[f * 2] + m[f * 2 + 1]); + o[0] = 0.5 * (shared_buffer[f * 2] + shared_buffer[f * 2 + 1]); o[1] = 0.5 * (c[f * 2] + c[f * 2 + 1]); } else { - let sample = if separate { delay.process([m[f * 2], m[f * 2 + 1]], master_delay) } - else { [m[f * 2], m[f * 2 + 1]] }; - o[mc[0] as usize] = if shared { shared_buffer[f * 2] } else { sample[0] }; - o[mc[1] as usize] = if shared { shared_buffer[f * 2 + 1] } else { sample[1] }; - if let Some(cc) = cc.filter(|_| !shared) { + let sample = [shared_buffer[f * 2], shared_buffer[f * 2 + 1]]; + let sample = if separate { delay.process(sample, master_delay) } else { sample }; + o[mc[0] as usize] = sample[0]; + o[mc[1] as usize] = sample[1]; + if let Some(cc) = cc { o[cc[0] as usize] = c[f * 2]; o[cc[1] as usize] = c[f * 2 + 1]; } @@ -668,7 +673,6 @@ fn open_stream( if separate { opening_health.cue.arm(); } let core = side.as_mut().ok_or_else(|| anyhow!("audio core has not returned from previous stream"))?; core.core.set_sample_rate(sr); - core.core.set_shared_output(config.headphones == HeadphoneRouting::MainOutput); core.core.apply(Command::SetDeckCount(config.decks)); if let Some(s) = side.take() { if let Err(rtrb::PushError::Full(s)) = lend.push(s) { @@ -883,6 +887,19 @@ mod tests { cpal::SupportedBufferSize::Range { min: 128, max: 1024 }, cpal::SampleFormat::F32) } + #[test] + fn defaults_and_legacy_main_output_never_route_cue_to_speakers() { + let mut cfg = AudioConfig::default(); + assert_eq!(cfg.headphones, HeadphoneRouting::Auto); + assert_eq!(channel_routing(&cfg, 2).unwrap(), (2, [0, 1], None, false)); + assert_eq!(channel_routing(&cfg, 4).unwrap(), (4, [0, 1], Some([2, 3]), false)); + cfg.headphones = HeadphoneRouting::MainOutput; + assert_eq!(channel_routing(&cfg, 4).unwrap(), (2, [0, 1], None, false)); + cfg.master_pair = [2, 3]; + assert_eq!(channel_routing(&cfg, 4).unwrap(), (4, [2, 3], None, false)); + assert!(channel_routing(&cfg, 2).is_err()); + } + #[test] fn legacy_audio_settings_keep_their_routing() { for routing in [HeadphoneRouting::Auto, HeadphoneRouting::Off, HeadphoneRouting::Split, diff --git a/crates/engine/src/mixer.rs b/crates/engine/src/mixer.rs index 0489176..fb21bad 100644 --- a/crates/engine/src/mixer.rs +++ b/crates/engine/src/mixer.rs @@ -227,7 +227,6 @@ pub struct Mixer { pub limiter: crate::dsp::Limiter, master_meter: Meter, pub headphone_mix: f32, - pub shared_output: bool, pub headphone_gain_db: f32, hp_meter: Meter, pub auto_gain: bool, @@ -235,8 +234,9 @@ pub struct Mixer { /// Extra signal added to the master before its gain and limiter (sample lanes), `n` frames. pub extra: Vec, pub extra_on: bool, - /// Independent preview, inserted before master gain or after Cue/Master blending. + /// Independent preview, routed after Cue/Master blending or to the physical output. pub preview: Vec, + pub speaker_preview: Vec, pub preview_output: crate::command::PreviewOutput, /// One channel strip per sample lane, driven by its clips' curves. @@ -260,7 +260,6 @@ impl Mixer { limiter: crate::dsp::Limiter::new(sr), master_meter: Meter::new(sr), headphone_mix: 0.0, - shared_output: false, headphone_gain_db: 0.0, hp_meter: Meter::new(sr), auto_gain: true, @@ -268,6 +267,7 @@ impl Mixer { extra: vec![0.0; MAX_BLOCK * 2], extra_on: false, preview: vec![0.0; MAX_BLOCK * 2], + speaker_preview: vec![0.0; MAX_BLOCK * 2], preview_output: Default::default(), sample_channels: (0..clubcraft_core::SAMPLE_LANES).map(|_| Channel::new(sr)).collect(), sample_bufs: (0..clubcraft_core::SAMPLE_LANES).map(|_| vec![0.0; MAX_BLOCK * 2]).collect(), @@ -330,9 +330,6 @@ impl Mixer { self.process_channels(decks, ctxs, active, n, master, cue); let master = &mut master[..n * 2]; let cue = &mut cue[..n * 2]; - if !self.shared_output && self.preview_output == crate::command::PreviewOutput::Master { - for (m, p) in master.iter_mut().zip(&self.preview[..n * 2]) { *m += *p; } - } self.master_gain.set(db_to_gain(self.master_gain_db)); for f in master.as_chunks_mut::<2>().0 { let g = self.master_gain.next(); @@ -342,10 +339,11 @@ impl Mixer { self.limiter.process(master); self.master_meter.process(master); // Only the Cue/Master control determines master monitoring, even with no PFL selected. - let mix = if self.shared_output { 0.0 } else { self.headphone_mix.clamp(0.0, 1.0) }; + let mix = self.headphone_mix.clamp(0.0, 1.0); let hg = db_to_gain(self.headphone_gain_db); - for ((c, m), p) in cue.iter_mut().zip(master.iter()).zip(&self.preview[..n * 2]) { - let preview = if self.shared_output || self.preview_output == crate::command::PreviewOutput::Headphones { *p } else { 0.0 }; + for (((c, m), p), speaker) in cue.iter_mut().zip(master.iter()).zip(&self.preview[..n * 2]).zip(&mut self.speaker_preview[..n * 2]) { + let preview = if self.preview_output == crate::command::PreviewOutput::Headphones { *p } else { 0.0 }; + *speaker = if self.preview_output == crate::command::PreviewOutput::Master { soft_clip(*p * hg) } else { 0.0 }; *c = soft_clip((*c * (1.0 - mix) + *m * mix + preview) * hg); } self.hp_meter.process(cue); @@ -392,24 +390,6 @@ mod tests { assert!(cue.iter().all(|v| *v == 0.0)); } - #[test] - fn shared_output_never_duplicates_master_and_keeps_pfl_independent() { - let mut mixer = Mixer::new(44100.0, 1); - mixer.shared_output = true; - for blend in [0.0, 0.5, 1.0] { - mixer.headphone_mix = blend; - let (master, cue) = render(&mut mixer); - assert!(master.iter().any(|v| v.abs() > 0.01)); - assert!(cue.iter().all(|v| *v == 0.0)); - } - mixer.channels[0].fader = 0.0; - for _ in 0..20 { render(&mut mixer); } - mixer.channels[0].pfl = true; - let (master, cue) = render(&mut mixer); - assert!(master.iter().all(|v| v.abs() < 1e-6)); - assert!(cue.iter().any(|v| v.abs() > 0.01)); - } - #[test] fn crossfader_curves() { let (a, b) = CrossfaderCurve::Smooth.gains(0.5); diff --git a/crates/engine/src/output.rs b/crates/engine/src/output.rs index be66883..c32a714 100644 --- a/crates/engine/src/output.rs +++ b/crates/engine/src/output.rs @@ -220,8 +220,8 @@ pub(crate) fn alignment(offset_ns: f64, correction_ms: f64, sr: u32) -> (f64, f6 } /// Physical-output protection is deliberately downstream of the recorded master bus. -pub(crate) fn mix_shared_output(master: &[f32], cue: &[f32], output: &mut [f32], limiter: &mut crate::dsp::Limiter) { - for ((out, master), cue) in output.iter_mut().zip(master).zip(cue) { *out = master + cue; } +pub(crate) fn mix_speaker_preview(master: &[f32], preview: &[f32], output: &mut [f32], limiter: &mut crate::dsp::Limiter) { + for ((out, master), preview) in output.iter_mut().zip(master).zip(preview) { *out = master + preview; } limiter.process(output); } @@ -676,12 +676,12 @@ mod tests { } #[test] - fn shared_physical_output_sums_buses_and_limits_without_modifying_recorded_master() { + fn speaker_preview_is_limited_after_the_recorded_master_bus() { let master = vec![0.7; 512]; let cue = vec![0.6; 512]; let mut output = vec![0.0; 512]; let mut limiter = crate::dsp::Limiter::new(44100.0); - for _ in 0..10 { mix_shared_output(&master, &cue, &mut output, &mut limiter); } + for _ in 0..10 { mix_speaker_preview(&master, &cue, &mut output, &mut limiter); } assert!(output.iter().all(|v| v.is_finite() && v.abs() <= 1.0)); assert!(output.iter().any(|v| *v > 0.7)); assert!(master.iter().all(|v| *v == 0.7)); diff --git a/crates/engine/src/player.rs b/crates/engine/src/player.rs index dc7cd54..1dd373b 100644 --- a/crates/engine/src/player.rs +++ b/crates/engine/src/player.rs @@ -411,7 +411,10 @@ pub struct PreviewSink<'a> { impl CommandSink for PreviewSink<'_> { fn submit(&mut self, cmd: Command) -> Result<()> { let cmd = match cmd { - Command::PlayMix { schedule, start } => Command::PreviewPlay { schedule, start, output: self.output }, + Command::PlayMix { schedule, start } => { + if self.output == crate::command::PreviewOutput::Auto { return Err(anyhow!("resolve automatic preview output before starting playback")); } + Command::PreviewPlay { schedule, start, output: self.output } + }, Command::MixStop => Command::PreviewStop, Command::MixSeek(t) => Command::PreviewSeek(t), Command::MixPause => Command::PreviewPause, diff --git a/crates/engine/tests/preview.rs b/crates/engine/tests/preview.rs index 8695079..11bdbb9 100644 --- a/crates/engine/tests/preview.rs +++ b/crates/engine/tests/preview.rs @@ -132,17 +132,7 @@ fn preview_does_not_change_live_or_studio_mix_or_decks() { } let (actual, _) = block(&mut core); let (expected, _) = block(&mut reference); - if output == PreviewOutput::Headphones { - assert_eq!(actual, expected, "master samples remain identical"); - } else if i == 0 { - assert!( - actual - .iter() - .zip(&expected) - .any(|(a, b)| (a - b).abs() > 0.01), - "master mode sums preview over the running mix" - ); - } + assert_eq!(actual, expected, "preview never changes master samples"); let a = core.snapshot(); let b = reference.snapshot(); let mut main_state = a.mix; @@ -156,24 +146,25 @@ fn preview_does_not_change_live_or_studio_mix_or_decks() { } #[test] -fn master_preview_is_recorded_and_obeys_master_volume() { +fn main_output_preview_is_separate_from_master_cue_and_recording() { let t = audio(); let mut core = EngineCore::new(SR, 2); + core.apply(Command::SetMasterGain(-80.0)); let _p = start(&mut core, PreviewOutput::Master, &t); let (producer, mut recorded) = rtrb::RingBuffer::new(FRAMES * 4); core.apply(Command::SetRecorder(Some(producer))); - let (m, _) = block(&mut core); - assert!(m.iter().any(|v| v.abs() > 0.01)); - for sample in &m { - assert_eq!(recorded.pop().unwrap(), *sample); - } - core.apply(Command::SetMasterGain(-80.0)); - for _ in 0..100 { - block(&mut core); - while recorded.pop().is_ok() {} - } - let (m, _) = block(&mut core); - assert!(m.iter().all(|v| v.abs() < 0.0002)); + let (m, c, p) = outputs(&mut core); + assert!(m.iter().chain(&c).all(|v| *v == 0.0)); + assert!(p.iter().any(|v| v.abs() > 0.01)); + for sample in &m { assert_eq!(recorded.pop().unwrap(), *sample); } +} + +fn outputs(core: &mut EngineCore) -> (Vec, Vec, Vec) { + let mut m = vec![0.0; FRAMES * 2]; + let mut c = m.clone(); + let mut p = m.clone(); + core.process_outputs(&mut m, &mut c, &mut p); + (m, c, p) } #[test] @@ -299,9 +290,9 @@ fn replacing_a_headphone_preview_with_a_silent_master_preview_leaks_no_tail() { .with_grid(BeatGrid::new(120.0, 0.0)), ); let _q = start(&mut core, PreviewOutput::Master, &silent); - let (master, _) = block(&mut core); + let (master, _, preview) = outputs(&mut core); assert!( - master.iter().all(|v| *v == 0.0), + master.iter().chain(&preview).all(|v| *v == 0.0), "old headphone audio must not escape through filter history" ); } @@ -341,29 +332,50 @@ fn main_transport_cannot_stop_the_preview() { fn main_output_preview_has_independent_volume_and_never_enters_recording() { for gain in [-60.0, 0.0, 12.0] { let mut core = EngineCore::new(SR, 2); - core.set_shared_output(true); core.apply(Command::SetMasterGain(gain)); core.apply(Command::SetHeadphoneMix(1.0)); let t = audio(); - // Also verifies migration of the old Master preview preference. let _p = start(&mut core, PreviewOutput::Master, &t); let (producer, mut recorded) = rtrb::RingBuffer::new(FRAMES * 4); core.apply(Command::SetRecorder(Some(producer))); - let (master, cue) = block(&mut core); - assert!(master.iter().all(|v| *v == 0.0)); - assert!(cue.iter().any(|v| v.abs() > 0.01)); + let (master, cue, preview) = outputs(&mut core); + assert!(master.iter().chain(&cue).all(|v| *v == 0.0)); + assert!(preview.iter().any(|v| v.abs() > 0.01)); while let Ok(sample) = recorded.pop() { assert_eq!(sample, 0.0); } } let t = audio(); let mut loud = EngineCore::new(SR, 2); let mut quiet = EngineCore::new(SR, 2); - loud.set_shared_output(true); - quiet.set_shared_output(true); quiet.apply(Command::SetHeadphoneGain(-20.0)); let _a = start(&mut loud, PreviewOutput::Master, &t); let _b = start(&mut quiet, PreviewOutput::Master, &t); - let (_, a) = block(&mut loud); - let (_, b) = block(&mut quiet); + let (_, _, a) = outputs(&mut loud); + let (_, _, b) = outputs(&mut quiet); let energy = |x: &[f32]| x.iter().map(|v| v * v).sum::(); assert!((energy(&b) / energy(&a) - 0.01).abs() < 0.002); } + +#[test] +fn deck_cue_cannot_enter_the_speaker_preview_bus() { + let mut core = EngineCore::new(SR, 4); + core.apply(Command::SetMasterGain(-80.0)); + core.apply(Command::LoadTrack(0, audio())); + core.apply(Command::Play(0)); + core.apply(Command::SetPfl(0, true)); + let _p = start(&mut core, PreviewOutput::Master, &audio()); + for _ in 0..10 { outputs(&mut core); } + core.apply(Command::PreviewStop); + for blend in [0.0, 0.5, 1.0] { + core.apply(Command::SetHeadphoneMix(blend)); + let (_, _, preview) = outputs(&mut core); + assert!(preview.iter().all(|v| *v == 0.0), "CUE is never a speaker preview"); + } +} + +#[test] +fn offline_render_does_not_include_speaker_previews() { + let mut core = EngineCore::new(SR, 2); + let _p = start(&mut core, PreviewOutput::Master, &audio()); + let (master, cue) = block(&mut core); + assert!(master.iter().chain(&cue).all(|v| *v == 0.0)); +} diff --git a/docs/audio-output.md b/docs/audio-output.md index b37120b..31b39de 100644 --- a/docs/audio-output.md +++ b/docs/audio-output.md @@ -119,29 +119,36 @@ alignment accuracy. ## Browser previews -Settings > Audio output contains Master and Preview / headphones sections, with a device -and channel pair for each output. Main output uses the master's physical device and channels -while keeping MASTER and PHONES volumes independent. List previews and selected deck CUE -are summed with master only at the physical output, after recording, with a final limiter. -CUE/MIX is unavailable in this mode, so master is never added twice. Deck CUE can make an -already audible deck louder; all monitoring on this output is audible to the audience. -New installations use Main output by default. Existing settings are preserved until Apply. -Selecting a separate device supports its available stereo channel pairs; on the same device, -master and cue pairs must not overlap. No setting silently moves the master channel pair. +Settings > Audio output keeps Master and Headphones routing separate from Preview output. +Headphones offers Auto (the default: master 1/2 and cue 3/4 when available), Off, Split cable, +channel pairs on the master device, and a separate device. Channel pairs must not overlap. +The legacy MainOutput routing remains readable but has no physical deck CUE output. Sample rate, buffer and alignment correction are under Advanced audio settings. -Changes apply together with Apply; failed changes preserve the running output and preview -routing. Discard restores saved selections. Successful Apply stops any active preview. -A disconnected headphone output never falls back to master. These settings apply to Library, -Studio Playlist and Mashups, Add tracks, and the Live browser and Automix queue. - -Previews have their own two private decks and conductor. They never stop or reuse the main -Studio or Live decks. Headphone previews are added after Cue/Master blending, before the -headphone gain and overload protection; they never enter the master or its recording. -Master previews are summed before master gain and limiting, and are included in recordings. -Offline project exports do not include previews. A missing or failed headphone output stops -or rejects the preview without falling back to master. Leaving the source screen/list stops -its preview. Track previews start at the first analysed drop, otherwise a third into the -track, at native tempo and key. + +Preview output offers Auto / Headphones / Main output. Auto selects the running headphone +route when configured, otherwise the physical main output. A configured but unavailable +headphone route rejects playback, including a separate-device startup with master only. +An active preview's destination is fixed; headphone failure stops it without speaker fallback. +A new preview after a system-default startup fallback uses that running configuration. +Preferences older than version 4 migrate the preview choice once to Auto, without changing +the saved device configuration. Later explicit preview choices are preserved. + +Changes apply together with Apply; failed changes preserve the running configuration and +preview preference. Discard restores saved selections. Successful Apply stops any preview. +List labels show the resolved destination rather than a draft setting. + +Previews use two private decks and a conductor and never stop Studio, Automix or Live decks. +Headphone previews are added after CUE/MIX and before PHONES and headphone protection. +Main output previews use an isolated third bus, summed only in the device callback after +the master recording tap, before physical-output limiting. The final limiter's latency is +included in separate-device alignment estimates. PHONES controls either preview destination, +independently of MASTER. Main output previews are audible to the audience; deck CUE is never +summed into that output. Neither preview destination enters the master recording or offline +project exports. + +These settings apply to Library, Studio Playlist and Mashups, Add tracks, and the Live browser +and Automix queue. Leaving the source screen/list stops its preview. Track previews start +at the first analysed drop, otherwise a third into the track, at native tempo and key. ## Live headphone monitoring From 3df46595cb3a35cdd394d19b9388ecbcb889172a Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Fri, 13 Nov 2026 16:28:53 +0300 Subject: [PATCH 4/4] Honor limiter settings and confirm speaker previews during playback --- crates/app/src/app.rs | 55 ++++++++++++++++-- crates/app/src/live/adapter.rs | 3 +- crates/app/src/preview.rs | 103 +++++++++++++++++++++++++++++++-- crates/app/src/settings.rs | 5 +- crates/app/src/theme.rs | 1 + crates/engine/src/engine.rs | 2 +- crates/engine/src/output.rs | 40 ++++++++++++- crates/engine/tests/engine.rs | 49 ++++++++++++++-- docs/audio-output.md | 21 ++++++- 9 files changed, 256 insertions(+), 23 deletions(-) diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index f62c9fd..20e3670 100644 --- a/crates/app/src/app.rs +++ b/crates/app/src/app.rs @@ -155,6 +155,7 @@ pub struct App { full_stems_queued: std::collections::HashSet, /// Export waiting for stem separation. pending_export: Option, + pending_speaker_preview: Option, /// Last seen change from `clubcraft mcp` (marker mtime) and when it was checked. external: (Option, f64), queued: std::collections::HashSet, @@ -189,7 +190,7 @@ impl App { } let audio_cfg: clubcraft_engine::AudioConfig = cc.storage.and_then(|s| eframe::get_value(s, "audio")).unwrap_or_default(); let midi_port: Option = cc.storage.and_then(|s| eframe::get_value(s, "midi_port")); - let mut app = App { lib, sh, jobs, view, library: LibraryView::default(), status: String::new(), devctl: crate::devctl::DevCtl::from_env(), live: Default::default(), decks: vec![Default::default(); 2], mixer: Default::default(), browser: LibraryView::default(), studio: Default::default(), mixes: Vec::new(), eng: crate::live::adapter::LiveEngine::start(audio_cfg.clone()), settings: crate::settings::Settings::new(audio_cfg, midi_port), home: Default::default(), prefs, applied_prefs: None, menu: crate::menu::AppMenu::install(&cc.egui_ctx), ui_ctx_cmd: None, mix_summaries: Vec::new(), prepared: (-1, 0), preview_serial: 0, stems_queued: Default::default(), full_stems_queued: Default::default(), pending_export: None, queued: Default::default(), external: (std::fs::metadata(crate::mcp::change_marker()).and_then(|m| m.modified()).ok(), 0.0) }; + let mut app = App { lib, sh, jobs, view, library: LibraryView::default(), status: String::new(), devctl: crate::devctl::DevCtl::from_env(), live: Default::default(), decks: vec![Default::default(); 2], mixer: Default::default(), browser: LibraryView::default(), studio: Default::default(), mixes: Vec::new(), eng: crate::live::adapter::LiveEngine::start(audio_cfg.clone()), settings: crate::settings::Settings::new(audio_cfg, midi_port), home: Default::default(), prefs, applied_prefs: None, menu: crate::menu::AppMenu::install(&cc.egui_ctx), ui_ctx_cmd: None, mix_summaries: Vec::new(), prepared: (-1, 0), preview_serial: 0, stems_queued: Default::default(), full_stems_queued: Default::default(), pending_export: None, pending_speaker_preview: None, queued: Default::default(), external: (std::fs::metadata(crate::mcp::change_marker()).and_then(|m| m.modified()).ok(), 0.0) }; if let Some(config) = &app.eng.startup_audio_config { app.settings.sync_audio(config.clone()); } app.settings.connect_midi(app.eng.handle.as_ref()); if let Some(e) = &app.eng.error { @@ -669,7 +670,25 @@ impl App { } fn start_preview(&mut self, mix: &clubcraft_core::Mix, from: f64, item: crate::preview::PreviewItem) { - match self.eng.play_preview(mix, from, &self.sh) { + let Some(h) = self.eng.handle.as_ref() else { self.status = "Audio output is unavailable".into(); return; }; + let config = h.audio_config(); + let output = match crate::preview::resolve_output(self.prefs.preview_output, &config, &h.stream_info()) { + Ok(output) => output, + Err(e) => { self.status = format!("Preview: {e:#}"); return; } + }; + if crate::preview::requires_speaker_confirmation(output, &self.eng.state(), self.eng.loading_mix.is_some()) { + self.pending_speaker_preview = Some(crate::preview::PendingSpeakerPreview { + mix: mix.clone(), from, item, config, preference: self.prefs.preview_output, + mix_serial: self.studio.mix_serial, mashup_revision: self.studio.mashup.revision, + }); + return; + } + self.play_preview_now(mix, from, item, output); + } + + fn play_preview_now(&mut self, mix: &clubcraft_core::Mix, from: f64, item: crate::preview::PreviewItem, output: clubcraft_engine::command::PreviewOutput) { + self.pending_speaker_preview = None; + match self.eng.play_preview(mix, from, &self.sh, output) { Ok(()) => { self.sh.preview.output = self.eng.preview_output; self.sh.preview.item = Some(item); @@ -682,6 +701,7 @@ impl App { } fn stop_preview(&mut self) { + self.pending_speaker_preview = None; self.eng.stop_preview(); self.sh.preview.item = None; } @@ -698,20 +718,42 @@ impl App { self.start_preview(&mix, from.clamp(0.0, dur.max(0.0)), item); } - fn reconcile_preview(&mut self) { + fn preview_source_visible(&self, item: crate::preview::PreviewItem, mix_serial: u64, mashup_revision: u64) -> bool { use crate::preview::PreviewSource as P; - let Some(item) = self.sh.preview.item else { return; }; let visible = match item.source { P::Library { playlist, mix } => self.view == View::Library && playlist == self.library.playlist && mix == self.library.mix, P::LiveBrowser { playlist, mix } => self.view == View::Live && playlist == self.browser.playlist && mix == self.browser.mix, P::LiveQueue => self.view == View::Live && self.eng.automix_queue.get(item.row) == Some(&item.track), P::Playlist => self.view == View::Studio && self.studio.tab == Some(crate::studio::Tab::Playlist) && self.studio.mix.tracks.get(item.row).is_some_and(|t| t.track_id == item.track), - P::Mashups => self.view == View::Studio && self.studio.tab == Some(crate::studio::Tab::Mashups) && self.studio.mashup.open && self.sh.preview.mashup_revision == self.studio.mashup.revision && self.studio.mashup.has_preview_row(item.row, item.track), + P::Mashups => self.view == View::Studio && self.studio.tab == Some(crate::studio::Tab::Mashups) && self.studio.mashup.open && mashup_revision == self.studio.mashup.revision && self.studio.mashup.has_preview_row(item.row, item.track), P::AddTracks => self.view == View::Studio && self.studio.picker.open, }; let studio = matches!(item.source, P::Playlist | P::Mashups | P::AddTracks); - if !visible || (studio && self.sh.preview.mix_serial != self.studio.mix_serial) { self.stop_preview(); } + visible && (!studio || mix_serial == self.studio.mix_serial) + } + + fn reconcile_preview(&mut self) { + if let Some(item) = self.sh.preview.item { + if !self.preview_source_visible(item, self.sh.preview.mix_serial, self.sh.preview.mashup_revision) { self.stop_preview(); } + } + if let Some(pending) = &self.pending_speaker_preview { + let unchanged = pending.preference == self.prefs.preview_output + && self.eng.handle.as_ref().is_some_and(|h| h.audio_config() == pending.config); + if !unchanged || !self.preview_source_visible(pending.item, pending.mix_serial, pending.mashup_revision) { + self.pending_speaker_preview = None; + } + } + } + + fn speaker_preview_confirmation(&mut self, ctx: &egui::Context) { + if self.pending_speaker_preview.is_none() { return; } + let Some(confirm) = crate::preview::speaker_confirmation_ui(ctx) else { return; }; + let Some(pending) = self.pending_speaker_preview.take() else { return; }; + if confirm { + // Revalidate the destination in the adapter; approval never carries over to another route or item. + self.play_preview_now(&pending.mix, pending.from, pending.item, clubcraft_engine::command::PreviewOutput::Master); + } } fn handle_mashup_actions(&mut self, actions: Vec) { @@ -1497,6 +1539,7 @@ impl eframe::App for App { } self.apply_prefs(&ctx); self.reconcile_preview(); + self.speaker_preview_confirmation(&ctx); for a in sa { match a { crate::settings::SettingsAction::ProcessAll => { diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index c3c3c5c..a657e3b 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -581,10 +581,11 @@ impl LiveEngine { } /// Play a browser/mashup preview on its private decks from `from` seconds. - pub fn play_preview(&mut self, mix: &Mix, from: f64, sh: &Shared) -> Result<()> { + pub fn play_preview(&mut self, mix: &Mix, from: f64, sh: &Shared, expected_output: clubcraft_engine::command::PreviewOutput) -> Result<()> { use clubcraft_engine::player::PreviewSink; let h = self.handle.as_ref().context("Audio output is unavailable")?; let output = crate::preview::resolve_output(self.prefs.preview_output, &h.audio_config(), &h.stream_info())?; + if output != expected_output { anyhow::bail!("Preview output changed; try preview again."); } self.stop_preview(); self.preview_output = output; let mut p = MixPlayer::lazy(mix, &|id| { diff --git a/crates/app/src/preview.rs b/crates/app/src/preview.rs index 8847e2c..dc69313 100644 --- a/crates/app/src/preview.rs +++ b/crates/app/src/preview.rs @@ -42,11 +42,9 @@ impl PreviewState { } pub fn label(&self, ui: &mut egui::Ui) { - ui.label( - egui::RichText::new(format!("Preview: {}", self.output_label())) - .small() - .color(crate::theme::TEXT_DIM), - ); + let color = if self.output == PreviewOutput::Master { crate::theme::WARN } else { crate::theme::TEXT_DIM }; + ui.label(egui::RichText::new(format!("Preview: {}", self.output_label())).small().color(color)) + .on_hover_text(if self.output == PreviewOutput::Master { "Previews are audible through the speakers." } else { "Preview output" }); } pub fn button(&self, ui: &mut egui::Ui, item: PreviewItem, enabled: bool) -> egui::Response { @@ -69,6 +67,36 @@ impl PreviewState { } } +pub struct PendingSpeakerPreview { + pub mix: clubcraft_core::Mix, + pub from: f64, + pub item: PreviewItem, + pub mix_serial: u64, + pub mashup_revision: u64, + pub config: clubcraft_engine::AudioConfig, + pub preference: PreviewOutput, +} + +pub fn requires_speaker_confirmation(output: PreviewOutput, state: &clubcraft_engine::EngineState, main_loading: bool) -> bool { + output == PreviewOutput::Master && (main_loading || state.mix.playing || state.decks.iter().any(|d| d.playing)) +} + +pub fn speaker_confirmation_ui(ctx: &egui::Context) -> Option { + let response = egui::Modal::new(egui::Id::new("speaker-preview-confirmation")) + .frame(egui::Frame::window(&ctx.global_style()).fill(crate::theme::PANEL)) + .show(ctx, |ui| { + ui.set_width(crate::theme::PREVIEW_CONFIRM_WIDTH); + ui.heading("Play preview through speakers?"); + ui.label("The main playback is running. This preview will be audible to the audience."); + ui.horizontal(|ui| { + if ui.button("Cancel").clicked() { return Some(false); } + if ui.button("Play through speakers").clicked() { return Some(true); } + None + }).inner + }); + if response.should_close() { Some(false) } else { response.inner } +} + /// Auto uses the running endpoint; a configured but failed headphone route is never a speaker fallback. pub fn target_output(preference: PreviewOutput, config: &clubcraft_engine::AudioConfig, info: &clubcraft_engine::StreamInfo) -> PreviewOutput { use clubcraft_engine::HeadphoneRouting as H; @@ -187,6 +215,71 @@ mod tests { } } + #[test] + fn speaker_confirmation_covers_live_studio_automix_and_loading_but_not_headphones() { + let mut state = clubcraft_engine::EngineState::default(); + assert!(!requires_speaker_confirmation(PreviewOutput::Master, &state, false)); + assert!(requires_speaker_confirmation(PreviewOutput::Master, &state, true)); + state.preview.playing = true; + assert!(!requires_speaker_confirmation(PreviewOutput::Master, &state, false)); + state.mix.playing = true; + assert!(requires_speaker_confirmation(PreviewOutput::Master, &state, false)); + assert!(!requires_speaker_confirmation(PreviewOutput::Headphones, &state, false)); + state.mix.playing = false; + for deck in 0..state.decks.len() { + state.decks[deck].playing = true; + assert!(requires_speaker_confirmation(PreviewOutput::Master, &state, false)); + state.decks[deck].playing = false; + } + } + + #[test] + fn speaker_confirmation_does_not_auto_accept_and_escape_cancels() { + let ctx = egui::Context::default(); + let mut decision = None; + for _ in 0..2 { + let mut output = ctx.run_ui(egui::RawInput::default(), |_| { decision = speaker_confirmation_ui(&ctx); }); + output.textures_delta.clear(); + assert_eq!(decision, None); + } + let input = egui::RawInput { events: vec![egui::Event::Key { + key: egui::Key::Escape, physical_key: None, pressed: true, repeat: false, modifiers: egui::Modifiers::NONE, + }], ..Default::default() }; + let mut output = ctx.run_ui(input, |_| { decision = speaker_confirmation_ui(&ctx); }); + output.textures_delta.clear(); + assert_eq!(decision, Some(false)); + } + + #[test] + fn speaker_confirmation_requires_the_explicit_play_button() { + for (label, expected) in [("Cancel", false), ("Play through speakers", true)] { + let ctx = egui::Context::default(); + let mut decision = None; + let mut position = None; + let mut frame = |events| { + let input = egui::RawInput { screen_rect: Some(egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(800.0, 600.0))), events, ..Default::default() }; + let mut output = ctx.run_ui(input, |_| { decision = speaker_confirmation_ui(&ctx); }); + position = output.shapes.iter().find_map(|shape| match &shape.shape { + egui::Shape::Text(text) if text.galley.text() == label => Some(text.pos + text.galley.size() * 0.5), + _ => None, + }); + output.textures_delta.clear(); + (decision, position) + }; + frame(vec![]); + let (decision, position) = frame(vec![]); + assert_eq!(decision, None); + let pos = position.expect("confirmation button is visible"); + frame(vec![egui::Event::PointerMoved(pos), egui::Event::PointerButton { + pos, button: egui::PointerButton::Primary, pressed: true, modifiers: egui::Modifiers::NONE, + }]); + let (decision, _) = frame(vec![egui::Event::PointerButton { + pos, button: egui::PointerButton::Primary, pressed: false, modifiers: egui::Modifiers::NONE, + }]); + assert_eq!(decision, Some(expected)); + } + } + #[test] fn automatic_output_uses_running_routes_and_never_falls_back_from_a_failed_route() { use clubcraft_engine::{AudioConfig, HeadphoneRouting as H}; diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index 8475b96..66e4355 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -364,7 +364,10 @@ impl Settings { } }); hint(ui, "Auto uses headphones when configured, otherwise the main output. Deck CUE never goes to the speakers. Previews are never recorded; PHONES controls their volume."); - if preview == PreviewOutput::Master { ui.colored_label(theme::WARN, "Main output previews are audible to the audience."); } + let resolved = handle.map(|h| crate::preview::target_output(preview, &h.audio_config(), &h.stream_info())); + if resolved == Some(PreviewOutput::Master) || preview == PreviewOutput::Master { + ui.colored_label(theme::WARN, "Main output previews are audible to the audience. Playback during a set requires confirmation."); + } if ui.small_button("Rescan devices").clicked() { self.devices = clubcraft_engine::devices().unwrap_or_default(); } ui.collapsing("Advanced audio settings", |ui| { egui::Grid::new("audio_advanced").num_columns(2).spacing([12.0, 6.0]).show(ui, |ui| { diff --git a/crates/app/src/theme.rs b/crates/app/src/theme.rs index 7f3562f..dadb057 100644 --- a/crates/app/src/theme.rs +++ b/crates/app/src/theme.rs @@ -3,6 +3,7 @@ use std::sync::atomic::{AtomicBool, AtomicU32, Ordering}; /// Compact Play/Stop control shared by browser preview lists. pub const PREVIEW_BUTTON_SIZE: f32 = 18.0; +pub const PREVIEW_CONFIRM_WIDTH: f32 = 380.0; pub const BG: Color32 = Color32::from_rgb(14, 15, 18); pub const PANEL: Color32 = Color32::from_rgb(24, 26, 31); diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 7223f9b..a77f1e1 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -587,7 +587,7 @@ fn open_stream( let n = (frames - done).min(SCRATCH_FRAMES); let (m, c) = (&mut side.master[..n * 2], &mut side.cue[..n * 2]); side.core.process_outputs(m, c, &mut preview_buffer[..n * 2]); - output::mix_speaker_preview(m, &preview_buffer[..n * 2], &mut shared_buffer[..n * 2], &mut shared_limiter); + output::mix_speaker_preview(m, &preview_buffer[..n * 2], &mut shared_buffer[..n * 2], &mut shared_limiter, &side.core.mixer().limiter); let out = &mut data[done * ch..(done + n) * ch]; out.fill(0.0); for f in 0..n { diff --git a/crates/engine/src/output.rs b/crates/engine/src/output.rs index c32a714..5a25d98 100644 --- a/crates/engine/src/output.rs +++ b/crates/engine/src/output.rs @@ -220,7 +220,10 @@ pub(crate) fn alignment(offset_ns: f64, correction_ms: f64, sr: u32) -> (f64, f6 } /// Physical-output protection is deliberately downstream of the recorded master bus. -pub(crate) fn mix_speaker_preview(master: &[f32], preview: &[f32], output: &mut [f32], limiter: &mut crate::dsp::Limiter) { +pub(crate) fn mix_speaker_preview(master: &[f32], preview: &[f32], output: &mut [f32], limiter: &mut crate::dsp::Limiter, master_limiter: &crate::dsp::Limiter) { + // Read the audio core directly: no UI snapshot, lock or callback allocation. + limiter.enabled = master_limiter.enabled; + limiter.set_ceiling_db(crate::dsp::gain_to_db(master_limiter.ceiling())); for ((out, master), preview) in output.iter_mut().zip(master).zip(preview) { *out = master + preview; } limiter.process(output); } @@ -681,13 +684,46 @@ mod tests { let cue = vec![0.6; 512]; let mut output = vec![0.0; 512]; let mut limiter = crate::dsp::Limiter::new(44100.0); - for _ in 0..10 { mix_speaker_preview(&master, &cue, &mut output, &mut limiter); } + let settings = crate::dsp::Limiter::new(44100.0); + for _ in 0..10 { mix_speaker_preview(&master, &cue, &mut output, &mut limiter, &settings); } assert!(output.iter().all(|v| v.is_finite() && v.abs() <= 1.0)); assert!(output.iter().any(|v| *v > 0.7)); assert!(master.iter().all(|v| *v == 0.7)); assert!(cue.iter().all(|v| *v == 0.6)); } + #[test] + fn physical_limiter_follows_live_master_settings_with_and_without_preview() { + use crate::{Command, EngineCore}; + for preview_gain in [0.0, 0.2] { + let mut core = EngineCore::new(44100, 2); + let master = vec![0.99; 512]; + let preview = vec![preview_gain; 512]; + let mut output = vec![0.0; 512]; + let mut limiter = crate::dsp::Limiter::new(44100.0); + let latency = limiter.latency(); + for (enabled, ceiling_db) in [(true, -6.0), (false, -6.0), (true, 0.0), (true, -12.0)] { + core.apply(Command::SetLimiter { enabled, ceiling_db }); + for _ in 0..100 { + mix_speaker_preview(&master, &preview, &mut output, &mut limiter, &core.mixer().limiter); + } + assert_eq!(limiter.enabled, enabled); + assert_eq!(limiter.latency(), latency); + let peak = output.iter().copied().fold(0.0_f32, f32::max); + if enabled { + let ceiling = crate::dsp::db_to_gain(ceiling_db); + assert!(peak <= ceiling + 1e-6); + if ceiling_db == 0.0 { assert!(peak > 0.97, "old fixed -0.3 dB ceiling must not remain"); } + } else { + assert!(peak >= 0.99, "disabled limiter must not apply its gain reduction"); + assert!(peak <= 1.0, "retain the existing digital safety clamp"); + } + assert!(master.iter().all(|v| *v == 0.99)); + assert!(preview.iter().all(|v| *v == preview_gain)); + } + } + } + #[test] fn cue_can_use_an_arbitrary_stereo_pair_without_touching_other_channels() { let health = Arc::new(OutputHealth::default()); diff --git a/crates/engine/tests/engine.rs b/crates/engine/tests/engine.rs index fbf9058..2437ee7 100644 --- a/crates/engine/tests/engine.rs +++ b/crates/engine/tests/engine.rs @@ -339,9 +339,19 @@ fn noise(n: usize, seed: u32, amp: f32) -> Vec { /// `cargo test --release -p clubcraft-engine --test engine cpu_budget -- --nocapture`. #[test] fn cpu_budget_4_decks_keylock_stems_fx() { + run_cpu_budget(false); +} + +#[test] +fn cpu_budget_4_decks_plus_2_mashup_preview_decks() { + run_cpu_budget(true); +} + +fn run_cpu_budget(with_preview: bool) { let secs = 10.0; let n = (SR as f64 * 40.0) as usize; let mut core = EngineCore::new(48000, 4); + let mut preview_track = None; for d in 0..4 { let tone: Vec = (0..n).map(|i| (i as f32 * 0.031 * (d + 1) as f32).sin() * 0.3).collect(); let nz = noise(n, d as u32 + 1, 0.1); @@ -349,7 +359,9 @@ fn cpu_budget_4_decks_keylock_stems_fx() { let stems: [(Vec, Vec); 4] = std::array::from_fn(|s| (noise(n, 10 + s as u32, 0.1), noise(n, 20 + s as u32, 0.1))); let st = Arc::new(StemTrack::from_planar("bench", &stems)); let t = LoadedTrack::new("bench", Arc::new(AudioBuffer::new(SR, l.clone(), l))).with_grid(BeatGrid::new(124.0, 0.0)).with_stems(st); - core.apply(Command::LoadTrack(d, Arc::new(t))); + let t = Arc::new(t); + if d == 0 { preview_track = Some(t.clone()); } + core.apply(Command::LoadTrack(d, t)); core.apply(Command::SetKeylock(d, true)); core.apply(Command::SetTempo(d, 1.03)); if d % 2 == 1 { @@ -365,6 +377,24 @@ fn cpu_budget_4_decks_keylock_stems_fx() { core.apply(Command::SetFilter(d, 0.35)); core.apply(Command::Play(d)); } + let preview_player = if with_preview { + let track = preview_track.unwrap(); + let mut mix = Mix { tempo: TempoMode::Fixed(128.0), keylock: true, ..Default::default() }; + for track_id in [100, 101] { + mix.tracks.push(MixTrack { track_id, mix_in: 0.0, mix_out: 4.0, key_shift: 1, + gain_db: 0.0, stems: Vec::new() }); + } + mix.transitions.push(Transition::new(TransitionStyle::Mashup, 64)); + mix.normalize(); + let mut player = MixPlayer::new(&mix, &|_| Some(track.clone()), [0, 1]).unwrap(); + // The entire measured interval is inside the overlap, so both private decks render. + let overlap = &player.timeline().transitions[0]; + let from = overlap.start_sec + 1.0; + assert!(from + secs < overlap.end_sec); + player.play(&mut clubcraft_engine::player::PreviewSink { sink: &mut core, + output: clubcraft_engine::command::PreviewOutput::Headphones }, from).unwrap(); + Some(player) + } else { None }; let block = 256usize; let mut m = vec![0f32; block * 2]; let mut c = vec![0f32; block * 2]; @@ -386,12 +416,13 @@ fn cpu_budget_4_decks_keylock_stems_fx() { static START: std::sync::OnceLock = std::sync::OnceLock::new(); START.get_or_init(std::time::Instant::now).elapsed().as_secs_f64() } + let mut preview = vec![0.0; block * 2]; let mut times = Vec::with_capacity(blocks); let wall = std::time::Instant::now(); let t0 = cpu_now(); for _ in 0..blocks { let tb = cpu_now(); - core.process(&mut m, &mut c); + core.process_outputs(&mut m, &mut c, &mut preview); times.push(cpu_now() - tb); } let el = cpu_now() - t0; @@ -406,19 +437,27 @@ fn cpu_budget_4_decks_keylock_stems_fx() { eprintln!("block times: first {:.3} ms, p99 {:.3} ms, p99.9 {:.3} ms, max(after start) {:.3} ms", first * 1e3, p99 * 1e3, p999 * 1e3, worst_block * 1e3); let st = core.snapshot(); assert!(st.decks.iter().all(|d| d.playing && d.stretching)); + if let Some(player) = preview_player { + assert_eq!(st.preview.schedule_id, player.schedule_id()); + assert!(st.preview.playing && st.preview.transition.is_some()); + assert_eq!(st.preview.resident_count(), 2); + assert!(c.iter().any(|v| v.abs() > 1e-5)); + } + let deck_count = if with_preview { 6 } else { 4 }; let rt = el / secs; let block_budget = block as f64 / 48000.0; eprintln!( - "10 s of 4 decks (keylock + stems + 2 FX each) in {:.3} s {timing} → {:.2} % realtime factor total, {:.2} % per deck; worst block {:.3} ms of {:.3} ms budget ({:.1} %)", + "10 s of {deck_count} decks (4 live with keylock/stems/FX, optional 2-deck mashup) in {:.3} s {timing} → {:.2} % realtime factor total, {:.2} % per deck; worst block {:.3} ms of {:.3} ms budget ({:.1} %)", el, rt * 100.0, - rt * 25.0, + rt * 100.0 / deck_count as f64, worst_block * 1000.0, block_budget * 1000.0, worst_block / block_budget * 100.0 ); if !cfg!(debug_assertions) && cfg!(unix) { - assert!(rt < 0.25, "realtime factor {rt}"); + let limit = if with_preview { 0.4 } else { 0.25 }; + assert!(rt < limit, "realtime factor {rt}, limit {limit}"); } } diff --git a/docs/audio-output.md b/docs/audio-output.md index 31b39de..674ae11 100644 --- a/docs/audio-output.md +++ b/docs/audio-output.md @@ -142,8 +142,16 @@ Headphone previews are added after CUE/MIX and before PHONES and headphone prote Main output previews use an isolated third bus, summed only in the device callback after the master recording tap, before physical-output limiting. The final limiter's latency is included in separate-device alignment estimates. PHONES controls either preview destination, -independently of MASTER. Main output previews are audible to the audience; deck CUE is never -summed into that output. Neither preview destination enters the master recording or offline +independently of MASTER. The final physical-output limiter follows the master limiter's +on/off state and ceiling, including changes during playback. Disabling limiting preserves +the existing digital safety clamp and fixed processing latency. + +Main output previews are audible to the audience; deck CUE is never summed into that output. +The resolved main output is highlighted even when selected by Auto. Starting a speaker preview +while a deck, Studio mix or Automix is playing (or a mix is loading) requires confirmation for +that request. Cancel, Escape or dismissing the dialog leaves playback unchanged. Leaving its +source or changing the output invalidates the request. Confirmation is not remembered for +another track or destination. Neither preview destination enters the master recording or offline project exports. These settings apply to Library, Studio Playlist and Mashups, Add tracks, and the Live browser @@ -158,3 +166,12 @@ CUE end, headphones are silent when all deck headphone buttons are off (unless a headphone preview is playing). Master monitoring is enabled only by turning CUE/MIX towards MIX; it is never substituted automatically when no deck is selected. PHONES controls the combined headphone volume. + +## Preview CPU budget + +`cargo test -p clubcraft-engine --test engine cpu_budget_4_decks_plus_2_mashup_preview_decks -j 4 -- --nocapture` +measures ten seconds of four live decks with keylock, stems and FX while two private preview +decks play a stem mashup throughout the overlap. It reports first-block, p99, p99.9 and worst +block times. Release builds on Unix enforce a thread-CPU realtime factor below 0.4; Windows +reports elapsed timing without a machine-load-dependent hard threshold. Run these memory-heavy +tests one at a time. No output device is opened.