diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index 8926996..83a970b 100644 --- a/crates/app/src/app.rs +++ b/crates/app/src/app.rs @@ -189,6 +189,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) }; + 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 { app.status = e.clone(); @@ -1436,6 +1437,15 @@ 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.restart_audio) && self.eng.handle.is_none() { + self.eng = crate::live::adapter::LiveEngine::start(self.settings.audio.clone()); + if self.eng.handle.is_some() { + if let Some(config) = &self.eng.startup_audio_config { self.settings.sync_audio(config.clone()); } + self.settings.connect_midi(self.eng.handle.as_ref()); + self.applied_prefs = None; + } + self.settings.message = self.eng.error.clone().unwrap_or_else(|| "Audio output started".into()); + } self.apply_prefs(&ctx); for a in sa { match a { diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index 32baa57..3c526a6 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -365,6 +365,9 @@ pub struct Export { pub struct LiveEngine { pub handle: Option, pub error: Option, + /// Canonical settings only when the requested setup started. A temporary + /// system-default fallback must never replace the user's persisted choice. + pub startup_audio_config: Option, pub cache: TrackCache, pub sep: Arc, tx: Sender, @@ -387,12 +390,118 @@ pub struct LiveEngine { pub prefs: crate::prefs::Prefs, } +// Keep the legacy startup recovery for one-device setups. SeparateDevice must +// never substitute the selected master or reroute cue onto the system speakers. +struct AudioStartup { + handle: T, + warning: Option, + used_fallback: bool, +} + +impl AudioStartup { + fn config_to_save(&self, resolved: AudioConfig) -> Option { + if self.used_fallback { None } else { Some(resolved) } + } +} + +fn start_audio(config: AudioConfig, mut open: impl FnMut(AudioConfig) -> anyhow::Result) -> anyhow::Result> { + let separate = config.headphones == clubcraft_engine::HeadphoneRouting::SeparateDevice; + open(config).map(|handle| AudioStartup { handle, warning: None, used_fallback: false }).or_else(|error| { + if separate { return Err(error); } + log::warn!("Saved audio setup unavailable; trying system default: {error:#}"); + open(AudioConfig::default()).map(|handle| AudioStartup { + handle, warning: Some(format!("Saved audio setup unavailable; using system default: {error:#}")), used_fallback: true, + }) + .map_err(|fallback| fallback.context(format!("saved audio setup failed: {error:#}"))) + }) +} + +#[cfg(test)] +mod audio_start_tests { + use super::*; + use clubcraft_engine::HeadphoneRouting; + + #[test] + fn missing_single_device_retries_system_default_and_reports_fallback() { + for routing in [HeadphoneRouting::Auto, HeadphoneRouting::Off, HeadphoneRouting::Split, + HeadphoneRouting::Channels { master: [2, 3], cue: [0, 1] }] { + let config = AudioConfig { device: Some("disconnected".into()), headphones: routing, ..AudioConfig::default() }; + let mut attempts = Vec::new(); + let started = start_audio(config.clone(), |candidate| { + attempts.push(candidate.clone()); + if candidate.device.is_some() { anyhow::bail!("device missing"); } + Ok(()) + }).unwrap(); + assert_eq!(attempts, [config, AudioConfig::default()]); + assert!(started.warning.as_ref().unwrap().contains("using system default")); + assert!(started.used_fallback); + } + } + + #[test] + fn fallback_keeps_saved_config_across_exit_and_retries_the_original_device() { + let original = AudioConfig { device: Some("external-interface".into()), sample_rate: Some(48000), + buffer_frames: Some(512), headphones: HeadphoneRouting::Split, ..AudioConfig::default() }; + let mut saved = original.clone(); + // Both initial startup and a restart from Settings use the same optional + // canonical config; neither may sync the fallback into persisted audio. + for _ in 0..2 { + let started = start_audio(saved.clone(), |candidate| { + if candidate.device.is_some() { anyhow::bail!("interface unplugged"); } + Ok(candidate) + }).unwrap(); + assert_eq!(started.handle, AudioConfig::default()); + if let Some(config) = started.config_to_save(started.handle.clone()) { saved = config; } + saved = serde_json::from_str(&serde_json::to_string(&saved).unwrap()).unwrap(); + assert_eq!(saved, original); + } + let recovered = start_audio(saved.clone(), |candidate| { + assert_eq!(candidate.device, original.device); + let mut resolved = candidate; + resolved.device = Some("resolved-interface-id".into()); + Ok(resolved) + }).unwrap(); + let canonical = recovered.config_to_save(recovered.handle.clone()).unwrap(); + assert_eq!(canonical.device.as_deref(), Some("resolved-interface-id")); + assert_eq!(canonical.sample_rate, original.sample_rate); + } + + #[test] + fn separate_device_never_substitutes_system_default() { + let config = AudioConfig { headphones: HeadphoneRouting::SeparateDevice, ..AudioConfig::default() }; + let mut attempts = 0; + let result = start_audio::<()>(config, |_| { + attempts += 1; + anyhow::bail!("master unavailable") + }); + assert!(result.is_err()); + assert_eq!(attempts, 1); + } + + #[test] + fn working_setup_is_not_reopened_and_double_failure_is_reported() { + let config = AudioConfig::default(); + let mut attempts = 0; + let started = start_audio(config.clone(), |_| { attempts += 1; Ok(()) }).unwrap(); + assert_eq!(attempts, 1); + assert!(started.warning.is_none()); + assert!(!started.used_fallback); + let failure = start_audio::<()>(config, |_| anyhow::bail!("device missing")).err().unwrap(); + assert!(format!("{failure:#}").contains("saved audio setup failed")); + } +} + impl LiveEngine { pub fn start(config: AudioConfig) -> LiveEngine { let (tx, rx) = unbounded(); - let (handle, error) = match Engine::start(config).or_else(|_| Engine::start(AudioConfig::default())) { - Ok(h) => (Some(h), None), - Err(e) => (None, Some(format!("Audio output unavailable: {e:#}"))), + let started = start_audio(config, Engine::start); + let (handle, error, startup_audio_config) = match started { + Ok(started) => { + let config_to_save = started.config_to_save(started.handle.audio_config()); + let warning = started.warning.or_else(|| started.handle.stream_info().warning); + (Some(started.handle), warning, config_to_save) + } + Err(e) => (None, Some(format!("Audio output unavailable: {e:#}")), None), }; if let Some(h) = &handle { let _ = h.send(Command::SetAutoGain(true)); @@ -405,6 +514,7 @@ impl LiveEngine { LiveEngine { handle, error, + startup_audio_config, cache, sep: Arc::new(LiveSeparator::new()), tx, @@ -897,7 +1007,15 @@ pub fn mixer_ui(st: &EngineState, eng: &LiveEngine) -> MixerUi { automix: eng.live_player.is_some() || (eng.loading_mix.is_some()), output_name: eng.handle.as_ref().map(|h| { let i = h.stream_info(); - format!("{} · {} Hz", i.device, i.sample_rate) + if i.master.failed { + "Master output stopped · open Audio settings to retry".into() + } else if i.headphones.as_ref().is_some_and(|cue| cue.failed) { + format!("{} · headphones stopped · open Audio settings", i.device) + } else if let Some(warning) = i.warning { + format!("{} · {warning}", i.device) + } else { + format!("{} · {} Hz", i.device, i.sample_rate) + } }).or_else(|| eng.error.clone()).unwrap_or_default(), } } diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index 5239d16..4eefc25 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -10,6 +10,20 @@ use eframe::egui::{self, RichText, Ui}; use parking_lot::Mutex; use std::sync::Arc; +fn device_choice(d: &DeviceInfo, devices: &[DeviceInfo]) -> String { + if devices.iter().filter(|other| other.name == d.name).count() > 1 { + format!("{} ({} ch) · {}", d.name, d.max_channels, d.id) + } else { format!("{} ({} ch)", d.name, d.max_channels) } +} + +fn device_label(devices: &[DeviceInfo], selected: Option<&str>, empty: &str) -> String { + match selected { + None => empty.into(), + Some(id) => devices.iter().find(|d| d.id == id || d.name == id).map(|d| device_choice(d, devices)) + .unwrap_or_else(|| format!("Unavailable: {id}")), + } +} + pub fn mapping_path() -> std::path::PathBuf { clubcraft_core::paths::data_dir().join("midi-mapping.json") } @@ -59,6 +73,8 @@ const LEARN: &[(&str, &str, bool)] = &[ pub struct Settings { pub open: bool, pub audio: AudioConfig, + audio_draft: AudioConfig, + pub restart_audio: bool, devices: Vec, midi_ports: Vec, pub midi_port: Option, @@ -105,7 +121,9 @@ impl Settings { let mapper = MidiMapper::new(mapping).unwrap_or_else(|_| MidiMapper::unmapped("My controller")); Settings { open: false, + audio_draft: audio.clone(), audio, + restart_audio: false, devices: vec![], midi_ports: vec![], midi_port, @@ -117,6 +135,11 @@ impl Settings { } } + pub fn sync_audio(&mut self, audio: AudioConfig) { + self.audio_draft = audio.clone(); + self.audio = audio; + } + pub fn connect_midi(&mut self, handle: Option<&EngineHandle>) { self.connection = None; let (Some(port), Some(h)) = (self.midi_port.clone(), handle) else { return }; @@ -215,18 +238,23 @@ impl Settings { if self.devices.is_empty() { self.devices = clubcraft_engine::devices().unwrap_or_default(); } - let mut cfg = self.audio.clone(); + let mut cfg = self.audio_draft.clone(); egui::Grid::new("audio").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(cfg.device.clone().unwrap_or("System default".into())).show_ui(ui, |ui| { - ui.selectable_value(&mut cfg.device, None, "System default"); - for d in &self.devices { - ui.selectable_value(&mut cfg.device, Some(d.name.clone()), format!("{} ({} ch)", d.name, d.max_channels)); + 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(); } }); - if ui.small_button("↻").on_hover_text("Rescan devices").clicked() { - self.devices = clubcraft_engine::devices().unwrap_or_default(); - } 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| { @@ -238,7 +266,8 @@ impl Settings { 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 ({:.1} ms)", b as f32 / 44.1)); + 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"); }); @@ -249,6 +278,7 @@ impl Settings { 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(), }; 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)"); @@ -256,9 +286,32 @@ impl Settings { 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)"); }); 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)); + }); + } + }); + 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.end_row(); + } }); + 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.alignment_ms = 0.0; + cfg.alignment_key = None; + } if let Some(h) = handle { let i = h.stream_info(); ui.label(RichText::new(format!("Running: {} · {} Hz · {} ch · buffer {}{}", i.device, i.sample_rate, i.channels, i.buffer_frames.map(|b| b.to_string()).unwrap_or("default".into()), if i.cue_channels.is_some() { " · headphone cue on" } else { "" })).size(11.0).color(theme::TEXT_DIM)); @@ -266,16 +319,43 @@ impl Settings { let txt = format!("Audio callback: {} frames · peak load {:.0} % · dropouts {}", a.buffer_frames, a.peak_load * 100.0, a.overruns + a.late); let col = if a.overruns + a.late > 0 { theme::WARN } else { theme::TEXT_DIM }; ui.label(RichText::new(txt).size(11.0).color(col)).on_hover_text("Dropouts = callbacks that took longer than their buffer or started late. If they keep rising while playing, pick a larger buffer."); + for (name, endpoint) in std::iter::once(("Master", &i.master)).chain(i.headphones.as_ref().map(|e| ("Headphones", e))) { + let buffer = endpoint.observed_buffer_frames.map(|n| n.to_string()).unwrap_or_else(|| "waiting".into()); + let latency = endpoint.estimated_latency_ms.map(|n| format!("{n:.1} ms")).unwrap_or_else(|| "unavailable".into()); + ui.label(RichText::new(format!("{name}: {} · {} Hz · {} · {} ch · callback {buffer} frames · driver latency {latency} · errors {}{}", + endpoint.device, endpoint.sample_rate, endpoint.sample_format, endpoint.channels, endpoint.errors, + if endpoint.failed { " · OUTPUT STOPPED — Apply to retry" } else { "" })) + .size(11.0).color(if endpoint.failed { theme::WARN } else { theme::TEXT_DIM })); + } + if i.headphones.is_some() { + let estimate = i.estimated_offset_ms.map(|v| format!("estimated cue lag {v:.1} ms")) + .unwrap_or_else(|| "driver estimate unavailable; internal cue buffering compensated".into()); + hint(ui, &format!("Alignment: {estimate}. Added delay: master {:.1} ms, cue {:.1} ms. Cue underruns {}, overflows {}.", + i.master_delay_ms, i.cue_delay_ms, i.cue_underruns, i.cue_overflows)); + hint(ui, "Delay calibrates after two seconds of cue audio. Driver timing is an estimate; verify by listening and adjust the correction."); + } + if let Some(warning) = &i.warning { ui.colored_label(theme::WARN, warning); } } - if cfg != self.audio { - self.audio = cfg.clone(); - if let Some(h) = handle { - match h.set_audio_config(cfg) { - Ok(()) => self.message = "Audio output changed".into(), - Err(e) => self.message = format!("Audio: {e:#}"), + self.audio_draft = cfg.clone(); + ui.horizontal(|ui| { + if ui.button("Apply").clicked() { + if let Some(h) = handle { + match h.set_audio_config(cfg) { + Ok(()) => { + self.sync_audio(h.audio_config()); + self.message = "Audio output changed".into(); + } + Err(e) => self.message = format!("Audio: {e:#}"), + } + } else { + self.audio = cfg; + self.restart_audio = true; } } - } + if ui.add_enabled(self.audio_draft != self.audio, egui::Button::new("Discard changes")).clicked() { + self.audio_draft = self.audio.clone(); + } + }); } fn midi_ui(&mut self, ui: &mut egui::Ui, handle: Option<&EngineHandle>) { diff --git a/crates/engine/examples/output_probe.rs b/crates/engine/examples/output_probe.rs new file mode 100644 index 0000000..83963b5 --- /dev/null +++ b/crates/engine/examples/output_probe.rs @@ -0,0 +1,57 @@ +//! Silent hardware probe. Run with no arguments to enumerate output IDs; pass +//! master and optional cue IDs to exercise outputs without loading or playing tracks. +use anyhow::{bail, Result}; +use clubcraft_engine::{devices, AudioConfig, Command, Engine, HeadphoneRouting}; +use std::time::Duration; + +fn main() -> Result<()> { + let args: Vec<_> = std::env::args().skip(1).collect(); + if args.is_empty() { + for d in devices()? { + println!("{} | {} | {} ch | {:?}", d.id, d.name, d.max_channels, d.sample_rates); + } + return Ok(()); + } + if args.len() > 2 { + bail!("usage: output_probe [master-device-id [cue-device-id]]"); + } + let separate = args.len() == 2; + let engine = Engine::start_with_commands(AudioConfig { + device: Some(args[0].clone()), + headphone_device: args.get(1).cloned(), + headphones: if separate { HeadphoneRouting::SeparateDevice } else { HeadphoneRouting::Off }, + ..AudioConfig::default() + }, [Command::SetMasterGain(-60.0), Command::SetHeadphoneGain(-60.0)])?; + std::thread::sleep(Duration::from_secs(3)); + let info = engine.stream_info(); + println!("{info:#?}"); + if (separate && info.headphones.is_none()) + || info.master.failed + || info.headphones.as_ref().is_some_and(|h| h.failed) + || info.master.observed_buffer_frames.is_none() + || info.headphones.as_ref().is_some_and(|h| h.observed_buffer_frames.is_none()) + { + bail!("all selected output streams must be running (see diagnostics above)"); + } + // An invalid selection must leave the current streams and the core running. + let mut invalid = engine.audio_config(); + if separate { + invalid.headphone_device = Some("clubcraft-nonexistent-output-probe".into()); + } else { + invalid.device = Some("clubcraft-nonexistent-output-probe".into()); + } + if engine.set_audio_config(invalid).is_ok() { + bail!("missing output device was unexpectedly accepted"); + } + engine.set_audio_config(engine.audio_config())?; + std::thread::sleep(Duration::from_millis(200)); + let reopened = engine.stream_info(); + if reopened.master.failed || reopened.master.observed_buffer_frames.is_none() + || (separate && reopened.headphones.is_none()) + || reopened.headphones.as_ref().is_some_and(|h| h.failed || h.observed_buffer_frames.is_none()) { + bail!("output did not reopen successfully"); + } + if engine.state().master.gain_db != -60.0 { bail!("core settings were lost while reopening output"); } + println!("All selected silent output streams opened and reopened successfully."); + Ok(()) +} diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 8d1e813..a03caea 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -6,11 +6,11 @@ //! each callback; [`EngineHandle::state`] returns the latest copy. //! * Garbage: tracks / schedules / recorder rings replaced on the audio thread are pushed to a //! ring that a collector thread drains and drops. -//! * Headphones: on devices with ≥ 4 outputs the cue bus goes to channels 3/4 (configurable); -//! on stereo devices an optional split mode puts mono master left and mono cue right. +//! * Headphones: channel pairs, mono split, or a second stereo device with drift correction. use crate::command::Command; use crate::core::{EngineCore, Garbage}; +use crate::output::{self, CueFrame, CueOutput, Delay, OutputHealth}; use crate::state::EngineState; use crate::wav::{RecorderThread, WavFormat}; use anyhow::{anyhow, bail, Context, Result}; @@ -34,25 +34,37 @@ pub enum HeadphoneRouting { Channels { master: [u16; 2], cue: [u16; 2] }, /// Stereo device with a splitter cable: mono master on the left, mono cue on the right. Split, + /// Stereo cue on a second output device; master remains on channels 1/2. + SeparateDevice, } /// Audio output configuration. #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct AudioConfig { - /// Output device name (as listed by [`devices`]); `None` = system default. + /// Output device ID (legacy names are accepted); `None` = system default. pub device: Option, - /// Preferred sample rate (44 100 or 48 000). `None` = 44.1 kHz if supported, else 48 kHz. + /// Preferred rate for one device; required for SeparateDevice. + /// `None` = 44.1 kHz if supported, else 48 kHz (then device default for one device). pub sample_rate: Option, /// Requested buffer size in frames (`None` = device default). 256 ≈ 5.8 ms at 44.1 kHz. pub buffer_frames: Option, pub headphones: HeadphoneRouting, + #[serde(default)] + pub headphone_device: Option, + /// Positive values mean the headphones lag further: delay the master. + #[serde(default)] + pub alignment_ms: f64, + /// Binds the saved correction to resolved devices, rate and buffer. + #[serde(default)] + pub alignment_key: Option, /// 2 or 4 decks. pub decks: usize, } impl Default for AudioConfig { fn default() -> Self { - AudioConfig { device: None, sample_rate: None, buffer_frames: Some(256), headphones: HeadphoneRouting::Auto, decks: 4 } + 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 } } } @@ -75,10 +87,33 @@ pub struct StreamInfo { pub sample_rate: u32, pub channels: u16, pub buffer_frames: Option, - /// Output channel pairs used for master / cue (cue `None` = no headphone output). + /// Output channel pairs; cue refers to `headphones` when a second device is open. + /// `None` means no headphone output. pub master_channels: [u16; 2], pub cue_channels: Option<[u16; 2]>, pub split: bool, + pub master: EndpointInfo, + pub headphones: Option, + pub warning: Option, + pub cue_underruns: u32, + pub cue_overflows: u32, + pub estimated_offset_ms: Option, + pub master_delay_ms: f64, + pub cue_delay_ms: f64, +} + +#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] +pub struct EndpointInfo { + pub device: String, + pub id: String, + pub sample_rate: u32, + pub channels: u16, + pub sample_format: String, + pub requested_buffer_frames: Option, + pub observed_buffer_frames: Option, + pub estimated_latency_ms: Option, + pub failed: bool, + pub errors: u32, } fn device_name(d: &cpal::Device) -> String { @@ -88,7 +123,7 @@ fn device_name(d: &cpal::Device) -> String { /// List output devices. pub fn devices() -> Result> { let host = cpal::default_host(); - let default = host.default_output_device().map(|d| device_name(&d)); + let default = host.default_output_device().and_then(|d| d.id().ok()).map(|id| id.to_string()); let mut out = Vec::new(); for d in host.output_devices()? { let name = device_name(&d); @@ -96,7 +131,7 @@ pub fn devices() -> Result> { let mut max_ch = 0u16; let mut rates = Vec::new(); if let Ok(cfgs) = d.supported_output_configs() { - for c in cfgs { + for c in cfgs.filter(|c| c.sample_format() == cpal::SampleFormat::F32) { max_ch = max_ch.max(c.channels()); for r in [44100u32, 48000, 88200, 96000] { if c.contains_rate(r) && !rates.contains(&r) { @@ -109,7 +144,7 @@ pub fn devices() -> Result> { if max_ch == 0 { continue; } - out.push(DeviceInfo { is_default: Some(&name) == default.as_ref(), name, id, max_channels: max_ch, sample_rates: rates }); + out.push(DeviceInfo { is_default: Some(&id) == default.as_ref(), name, id, max_channels: max_ch, sample_rates: rates }); } Ok(out) } @@ -140,9 +175,7 @@ const SCRATCH_FRAMES: usize = 4096; pub struct EngineHandle { sender: CommandSender, state: Mutex>, - stream: Mutex>, - eject: Mutex>, - ret: Mutex>>, + runtime: Mutex, config: Mutex, info: Mutex, errors: Arc, @@ -151,19 +184,127 @@ pub struct EngineHandle { recorder: Mutex>, } +/// The core is parked here whenever no device can be opened. Stream destruction +/// returns its loan through a ring, including when a disconnected device stops callbacks. +struct Runtime { + streams: Option, + parked: Option>, + returns: rtrb::Consumer>, + health: Arc, +} + +struct Streams { + master: cpal::Stream, + cue: Option, + stop: Arc, +} + +impl Drop for Streams { + fn drop(&mut self) { + self.stop.store(true, Ordering::Release); + let _ = self.master.pause(); + if let Some(cue) = &self.cue { let _ = cue.pause(); } + } +} + +struct CoreLoan { + side: Option>, + incoming: rtrb::Consumer>, + returns: rtrb::Producer>, +} + +impl CoreLoan { + fn get(&mut self) -> Option<&mut AudioSide> { + if self.side.is_none() { self.side = self.incoming.pop().ok(); } + self.side.as_deref_mut() + } +} + +impl Runtime { + fn reclaim(&mut self) -> Result<()> { + drop(self.streams.take()); + if self.parked.is_none() { + let deadline = Instant::now() + Duration::from_secs(1); + loop { + if let Ok(side) = self.returns.pop() { self.parked = Some(side); break; } + if Instant::now() >= deadline { bail!("audio stream has not released the core yet; retry Apply"); } + std::thread::sleep(Duration::from_millis(5)); + } + } + Ok(()) + } + + fn open(&mut self, config: &AudioConfig, prepared: Prepared, errors: Arc) -> Result { + if self.parked.is_none() { bail!("audio core is still returning; retry Apply"); } + let (rp, rc) = rtrb::RingBuffer::new(2); + let health = Arc::new(OutputHealth::default()); + health.offset_us.store(i32::MIN, Ordering::Relaxed); + let (streams, info) = open_stream(config, prepared, &mut self.parked, rp, health.clone(), errors)?; + self.returns = rc; + self.health = health; + self.streams = Some(streams); + Ok(info) + } +} + +impl Drop for CoreLoan { + fn drop(&mut self) { + // Exactly one core is lent and the return ring has capacity two. + if let Some(side) = self.side.take().or_else(|| self.incoming.pop().ok()) { + let _ = self.returns.push(side); + } + } +} + /// Entry point. pub struct Engine; impl Engine { /// Open the output device and start the engine. pub fn start(config: AudioConfig) -> Result { + Self::start_with_commands(config, std::iter::empty()) + } + + /// Apply initial settings before starting either output callback. Diagnostic + /// tools can set minimum gains without racing a running audio stream. + pub fn start_with_commands(mut config: AudioConfig, commands: impl IntoIterator) -> Result { + let prepared = prepare(&config); + let (prepared, warning) = match prepared { + Ok(p) => (p, None), + Err(e) if config.headphones == HeadphoneRouting::SeparateDevice => { + let mut master_only = config.clone(); + master_only.headphones = HeadphoneRouting::Off; + (prepare(&master_only)?, Some(format!("Headphones unavailable: {e:#}. Master only; select devices and Apply to retry."))) + } + Err(e) => return Err(e), + }; + if warning.is_none() { bind_config(&mut config, &prepared); } let (gp, mut gc) = rtrb::RingBuffer::::new(1024); let (cp, cc) = rtrb::RingBuffer::::new(4096); - let (rp, rc) = rtrb::RingBuffer::>::new(2); + let (_, rc) = rtrb::RingBuffer::>::new(2); let (sin, sout) = triple_buffer::triple_buffer(&EngineState::default()); let collector_stop = Arc::new(AtomicBool::new(false)); let stop = collector_stop.clone(); - let collector = std::thread::Builder::new() + let mut core = Box::new(EngineCore::new(prepared.sr, config.decks)); + core.set_garbage(gp); + core.set_state_output(sin); + for command in commands { core.apply(command); } + let side = Box::new(AudioSide { core, cmds: cc, master: vec![0.0; SCRATCH_FRAMES * 2], cue: vec![0.0; SCRATCH_FRAMES * 2] }); + let errors = Arc::new(AtomicU32::new(0)); + let health = Arc::new(OutputHealth::default()); + let mut runtime = Runtime { streams: None, parked: Some(side), returns: rc, health }; + let info = match runtime.open(&config, prepared, errors.clone()) { + Ok(mut info) => { info.warning = warning; info } + Err(e) if config.headphones == HeadphoneRouting::SeparateDevice => { + let mut master_only = config.clone(); + master_only.headphones = HeadphoneRouting::Off; + let mut info = runtime.open(&master_only, prepare(&master_only)?, errors.clone())?; + info.warning = Some(format!("Headphones unavailable: {e:#}. Master only; Apply to retry.")); + info + } + Err(e) => return Err(e), + }; + let collector_result = std::thread::Builder::new() .name("clubcraft-gc".into()) .spawn(move || { while !stop.load(Ordering::Relaxed) { @@ -176,20 +317,12 @@ impl Engine { drop(g); } }) - .context("spawn collector")?; - let mut core = Box::new(EngineCore::new(config.sample_rate.unwrap_or(44100), config.decks)); - core.set_garbage(gp); - core.set_state_output(sin); - let side = Box::new(AudioSide { core, cmds: cc, master: vec![0.0; SCRATCH_FRAMES * 2], cue: vec![0.0; SCRATCH_FRAMES * 2] }); - let errors = Arc::new(AtomicU32::new(0)); - let eject = Arc::new(AtomicBool::new(false)); - let (stream, info, _) = open_stream(&config, side, eject.clone(), rp, errors.clone())?; + .context("spawn collector"); + let collector = collector_result?; Ok(EngineHandle { sender: CommandSender { inner: Arc::new(Mutex::new(cp)) }, state: Mutex::new(sout), - stream: Mutex::new(Some(stream)), - eject: Mutex::new(eject), - ret: Mutex::new(rc), + runtime: Mutex::new(runtime), config: Mutex::new(config), info: Mutex::new(info), errors, @@ -202,25 +335,53 @@ impl Engine { fn find_device(host: &cpal::Host, name: Option<&str>) -> Result { if let Some(n) = name { - for d in host.output_devices()? { - if device_name(&d) == n || d.id().map(|i| i.to_string() == n).unwrap_or(false) { - return Ok(d); - } - } - log::warn!("audio device {n:?} not found, using the default output"); + let candidates: Vec<_> = host.output_devices()?.collect(); + let names: Vec<_> = candidates.iter().map(|d| (device_name(d), d.id().map(|id| id.to_string()).unwrap_or_default())).collect(); + let index = resolve_device(n, &names)?; + return candidates.into_iter().nth(index).ok_or_else(|| anyhow!("audio device disappeared")); } host.default_output_device().ok_or_else(|| anyhow!("no audio output device")) } -type OpenResult = (cpal::Stream, StreamInfo, Option>>); +fn resolve_device(selected: &str, candidates: &[(String, String)]) -> Result { + if let Some(i) = candidates.iter().position(|(_, id)| !id.is_empty() && id == selected) { return Ok(i); } + let mut matches = candidates.iter().enumerate().filter(|(_, (name, _))| name == selected); + let first = matches.next().map(|(i, _)| i).ok_or_else(|| anyhow!("audio device {selected:?} not found"))?; + if matches.next().is_some() { bail!("multiple audio devices named {selected:?}; select a device again by ID"); } + Ok(first) +} -fn open_stream( - config: &AudioConfig, - mut side: Box, - eject: Arc, - ret: rtrb::Producer>, - errors: Arc, -) -> Result { +struct Prepared { + device: cpal::Device, + cue_device: Option, + channels: u16, + sr: u32, + master_ch: [u16; 2], + cue_ch: Option<[u16; 2]>, + split: bool, +} + +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)); + 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); } + if cue.is_some() { config.headphone_device = cue; } +} + +fn bind_alignment(config: &mut AudioConfig, key: String) { + if config.alignment_key.as_ref().is_some_and(|old| old != &key) { config.alignment_ms = 0.0; } + 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); @@ -232,61 +393,147 @@ fn open_stream( 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 => (2, [0, 1], None, false), + HeadphoneRouting::Auto | HeadphoneRouting::Off | HeadphoneRouting::SeparateDevice => (2, [0, 1], None, false), HeadphoneRouting::Channels { master, cue } => { - let need = master.iter().chain(cue.iter()).copied().max().unwrap_or(1) + 1; + 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"); } + let mut used = [master[0], master[1], cue[0], cue[1]]; + used.sort(); + if used.windows(2).any(|w| w[0] == w[1]) { bail!("master and cue require distinct output channels"); } (need.max(2), master, Some(cue), false) } HeadphoneRouting::Split => (2, [0, 1], Some([0, 1]), true), }; + 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))?; + if device.id()? == cue.id()? { bail!("select a different headphone device, or use single-device channel routing"); } + Some(cue) + } else { None }; + let cue_ranges = cue_device.as_ref().map(|d| d.supported_output_configs().map(|r| r.collect::>())).transpose()?; + let format = choose_format(&ranges, cue_ranges.as_deref(), config, want_ch); + let (channels, sr) = match format { + Ok(format) => format, + Err(_) if config.headphones != HeadphoneRouting::SeparateDevice => { + let default = device.default_output_config()?; + default_format(&ranges, want_ch, default.sample_rate())? + } + Err(error) => return Err(error), + }; + Ok(Prepared { device, cue_device, channels, sr, master_ch, cue_ch, split }) +} + +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) + && (!strict || supports_buffer(c, config.buffer_frames)); let preferred: Vec = match config.sample_rate { + Some(r) if strict => vec![r], Some(r) => vec![r, 44100, 48000], None => vec![44100, 48000], }; let chosen = preferred .iter() - .find(|r| ranges.iter().any(|c| c.channels() >= want_ch && c.contains_rate(**r))) + .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 + && c.contains_rate(**r) && supports_buffer(c, config.buffer_frames)))) .copied(); - let (channels, sr) = match chosen { - Some(r) => (want_ch, r), - None => { - let d = device.default_output_config()?; - (d.channels().max(2), d.sample_rate()) - } - }; - if side.core.sample_rate() != sr { - side.core.set_sample_rate(sr); + let sr = chosen.ok_or_else(|| anyhow!("no common F32 output format for the selected rate, channels and buffer"))?; + let channels = ranges.iter().filter(|c| master_ok(c, sr)) + .map(|c| c.channels()).min().ok_or_else(|| anyhow!("no supported output channel count"))?; + Ok((channels, sr)) +} + +fn default_format(ranges: &[cpal::SupportedStreamConfigRange], want_ch: u16, rate: u32) -> Result<(u16, u32)> { + let channels = ranges.iter().filter(|c| c.sample_format() == cpal::SampleFormat::F32 + && c.channels() >= want_ch && c.contains_rate(rate)) + .map(|c| c.channels()).min().ok_or_else(|| anyhow!("device default has no compatible F32 channel layout"))?; + Ok((channels, rate)) +} + +fn supports_buffer(c: &cpal::SupportedStreamConfigRange, frames: Option) -> bool { + match (c.buffer_size(), frames) { + // WASAPI reports the shared engine period as min == max, not the + // accepted request range. Let opening the stream validate the request; + // its actual callback length is reported separately. + (cpal::SupportedBufferSize::Range { min, max }, Some(_)) if cfg!(windows) && min == max => true, + (cpal::SupportedBufferSize::Range { min, max }, Some(n)) => (*min..=*max).contains(&n), + _ => true, } +} + +fn endpoint(device: &cpal::Device, sr: u32, channels: u16, buffer: Option) -> EndpointInfo { + EndpointInfo { device: device_name(device), id: device.id().map(|i| i.to_string()).unwrap_or_default(), sample_rate: sr, channels, + sample_format: "F32".into(), requested_buffer_frames: buffer, observed_buffer_frames: None, estimated_latency_ms: None, failed: false, errors: 0 } +} + +fn open_stream( + config: &AudioConfig, + prepared: Prepared, + side: &mut Option>, + ret: rtrb::Producer>, + health: Arc, + errors: Arc, +) -> Result<(Streams, StreamInfo)> { + 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 buffer_size = match config.buffer_frames { Some(f) => cpal::BufferSize::Fixed(f), None => cpal::BufferSize::Default, }; let stream_config = cpal::StreamConfig { channels, sample_rate: sr, buffer_size }; let ch = channels as usize; - // owned by the audio callback from here on - let mut slot = Some(side); - let mut ret = Some(ret); + let (mut lend, incoming) = rtrb::RingBuffer::new(1); + let mut loan = CoreLoan { side: None, incoming, returns: ret }; + let epoch = Instant::now(); + let stop = Arc::new(AtomicBool::new(false)); + let stopped = stop.clone(); + let (mut cue_tx, cue_rx) = rtrb::RingBuffer::::new(sr as usize * 2); + let mut delay = Delay::new(sr); + let master_health = health.clone(); + let cue_stream = if let Some(d) = cue_device { + let mut output = CueOutput::new(cue_rx, health.clone(), epoch, sr, config.alignment_ms); + let err_health = health.clone(); + let cue_errors = errors.clone(); + let halted = stop.clone(); + let failed = health.clone(); + let stream = d.build_output_stream::( + cpal::StreamConfig { channels: 2, sample_rate: sr, buffer_size }, + move |data, info| { + failed.cue.heartbeat(data.len() / 2); + 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); } + }, + move |error| { + err_health.cue.report_error(error.kind()); + cue_errors.fetch_add(1, Ordering::Relaxed); + }, Some(Duration::from_secs(3))).context("open headphone output")?; + Some(stream) + } else { None }; + let separate = cue_stream.is_some(); let mut load = 0f32; - let mut health = crate::state::AudioHealth::default(); + let mut callback_health = crate::state::AudioHealth::default(); 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 cc = cue_ch; let err2 = errors.clone(); - let data_cb = move |data: &mut [f32], _: &cpal::OutputCallbackInfo| { + let data_cb = move |data: &mut [f32], callback: &cpal::OutputCallbackInfo| { let t0 = Instant::now(); let faults0 = major_faults(); - if eject.load(Ordering::Acquire) { - if let (Some(s), Some(r)) = (slot.take(), ret.as_mut()) { - let _ = r.push(s); - } + master_health.master.heartbeat(data.len() / ch); + if stopped.load(Ordering::Acquire) || master_health.master.failed.load(Ordering::Acquire) { data.fill(0.0); return; } - let Some(side) = slot.as_mut() else { + let Some(side) = loan.get() else { data.fill(0.0); return; }; @@ -298,6 +545,10 @@ fn open_stream( } side.core.prof[0] = t0.elapsed().as_micros() as u32; let frames = data.len() / ch; + let latency = output::observe(callback, frames, &master_health.master); + let presentation = latency.map(|ns| t0.duration_since(epoch).as_nanos() as u64 + ns); + let mut overflow = false; + let master_delay = master_health.master_delay.load(Ordering::Relaxed) as f64; let mut done = 0; while done < frames { let n = (frames - done).min(SCRATCH_FRAMES); @@ -307,12 +558,19 @@ fn open_stream( 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) }; + if cue_tx.push(frame).is_err() { overflow = true; } + } if split { o[0] = 0.5 * (m[f * 2] + m[f * 2 + 1]); o[1] = 0.5 * (c[f * 2] + c[f * 2 + 1]); } else { - o[mc[0] as usize] = m[f * 2]; - o[mc[1] as usize] = m[f * 2 + 1]; + 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[cc[0] as usize] = c[f * 2]; o[cc[1] as usize] = c[f * 2 + 1]; @@ -321,61 +579,91 @@ fn open_stream( } done += n; } + if overflow { + master_health.overflows.fetch_add(1, Ordering::Relaxed); + master_health.reset.store(true, Ordering::Relaxed); + } let budget = frames as f32 / sr as f32; let l = t0.elapsed().as_secs_f32() / budget.max(1e-6); load = load * 0.9 + l * 0.1; side.core.cpu_load = load; // health: overruns, late callbacks, peaks - health.buffer_frames = frames as u32; + callback_health.buffer_frames = frames as u32; if l > 1.0 { - health.overruns += 1; + callback_health.overruns += 1; } if major_faults() > faults0 + 8 { - health.faulted += 1; + callback_health.faulted += 1; if l > 1.0 { - health.faulted_overruns += 1; + callback_health.faulted_overruns += 1; } } if let Some(prev) = last_start { if t0.duration_since(prev).as_secs_f32() > 2.0 * budget + 0.002 { - health.late += 1; + callback_health.late += 1; } } last_start = Some(t0); - health.peak_load = health.peak_load.max(l); + callback_health.peak_load = callback_health.peak_load.max(l); window.0 = window.0.max(l); window.1 += budget; - health.recent_peak = health.recent_peak.max(window.0); + callback_health.recent_peak = callback_health.recent_peak.max(window.0); if window.1 >= 2.0 { - health.recent_peak = window.0; + callback_health.recent_peak = window.0; window = (0.0, 0.0); } let sections = side.core.audio.section_peak_us; for (k, v) in crate::prof::take().into_iter().enumerate() { - health.deck_peak_us[k] = health.deck_peak_us[k].max(v); + callback_health.deck_peak_us[k] = callback_health.deck_peak_us[k].max(v); } - side.core.audio = health; + side.core.audio = callback_health; side.core.audio.section_peak_us = sections; side.core.stream_errors = err2.load(Ordering::Relaxed); }; - let err_cb = move |e: cpal::Error| { - log::warn!("audio stream error: {e}"); + let opening_health = health.clone(); + let err_cb = move |error: cpal::Error| { + health.master.report_error(error.kind()); errors.fetch_add(1, Ordering::Relaxed); }; let stream = device .build_output_stream::(stream_config, data_cb, err_cb, Some(Duration::from_secs(3))) .with_context(|| format!("open {name} ({channels} ch @ {sr} Hz)"))?; - stream.play().context("start stream")?; + // The callback owns no core until BOTH streams have opened and started. + // An error before this point therefore leaves all deck state with the caller. + if let Some(cue) = &cue_stream { cue.play().context("start headphone stream")?; } + stream.play().context("start master stream")?; + if opening_health.master.failed.load(Ordering::Acquire) || opening_health.cue.failed.load(Ordering::Acquire) { + bail!("an audio stream failed while starting"); + } + opening_health.master.arm(); + 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.apply(Command::SetDeckCount(config.decks)); + if let Some(s) = side.take() { + if let Err(rtrb::PushError::Full(s)) = lend.push(s) { + *side = Some(s); + bail!("audio core handoff failed"); + } + } let info = StreamInfo { device: name, sample_rate: sr, channels, buffer_frames: config.buffer_frames, master_channels: master_ch, - cue_channels: cue_ch, + cue_channels: if separate { Some([0, 1]) } else { cue_ch }, split, + master: master_info, + headphones: cue_info, + warning: None, + cue_underruns: 0, + cue_overflows: 0, + estimated_offset_ms: None, + master_delay_ms: 0.0, + cue_delay_ms: 0.0, }; - Ok((stream, info, None)) + Ok((Streams { master: stream, cue: cue_stream, stop }, info)) } impl EngineHandle { @@ -391,11 +679,36 @@ impl EngineHandle { /// Latest state snapshot (cheap copy; poll at UI rate). pub fn state(&self) -> EngineState { - *self.state.lock().read() + let mut state = *self.state.lock().read(); + state.stream_errors = self.errors.load(Ordering::Relaxed); + state } pub fn stream_info(&self) -> StreamInfo { - self.info.lock().clone() + let rt = self.runtime.lock(); + let mut info = self.info.lock().clone(); + fn update(i: &mut EndpointInfo, h: &output::EndpointHealth) { + h.log_errors(&i.device); + i.observed_buffer_frames = match h.frames.load(Ordering::Relaxed) { 0 => None, n => Some(n) }; + i.estimated_latency_ms = match h.latency_us.load(Ordering::Relaxed) { 0 => None, n => Some(n as f64 / 1000.0) }; + i.failed = h.check_stalled(i.sample_rate); + i.errors = h.errors.load(Ordering::Relaxed); + } + update(&mut info.master, &rt.health.master); + if let Some(cue) = &mut info.headphones { update(cue, &rt.health.cue); } + info.cue_underruns = rt.health.underruns.load(Ordering::Relaxed); + info.cue_overflows = rt.health.overflows.load(Ordering::Relaxed); + let offset = rt.health.offset_us.load(Ordering::Relaxed); + info.estimated_offset_ms = (offset != i32::MIN && info.headphones.is_some() + && info.master.estimated_latency_ms.is_some() && info.headphones.as_ref().is_some_and(|h| h.estimated_latency_ms.is_some())) + .then_some(offset as f64 / 1000.0); + info.master_delay_ms = rt.health.master_delay.load(Ordering::Relaxed) as f64 * 1000.0 / info.sample_rate as f64; + info.cue_delay_ms = rt.health.cue_delay.load(Ordering::Relaxed) as f64 * 1000.0 / info.sample_rate as f64; + if rt.streams.is_none() { + info.master.failed = true; + if let Some(cue) = &mut info.headphones { cue.failed = true; } + } + info } pub fn audio_config(&self) -> AudioConfig { @@ -409,39 +722,54 @@ impl EngineHandle { /// Reopen the output with a new configuration (device, rate, buffer, routing). Decks keep /// their tracks, positions and settings. - pub fn set_audio_config(&self, config: AudioConfig) -> Result<()> { - let mut stream_guard = self.stream.lock(); - // ask the callback to hand back the engine - let eject = self.eject.lock().clone(); - eject.store(true, Ordering::Release); - let deadline = Instant::now() + Duration::from_millis(1000); - let mut side = None; - while Instant::now() < deadline { - if let Ok(s) = self.ret.lock().pop() { - side = Some(s); - break; + pub fn set_audio_config(&self, mut config: AudioConfig) -> Result<()> { + let prepared = prepare(&config)?; + let mut rt = self.runtime.lock(); + if self.recorder.lock().is_some() && prepared.sr != self.info.lock().sample_rate { + bail!("stop recording before changing the sample rate"); + } + bind_config(&mut config, &prepared); + let old_config = self.config.lock().clone(); + let old_info = self.info.lock().clone(); + let mut rollback = old_config.clone(); + rollback.device = Some(if old_info.master.id.is_empty() { old_info.master.device.clone() } else { old_info.master.id.clone() }); + rollback.sample_rate = Some(old_info.sample_rate); + if old_config.headphones == HeadphoneRouting::SeparateDevice { + rollback.headphones = if let Some(cue) = &old_info.headphones { + rollback.headphone_device = Some(cue.id.clone()); + HeadphoneRouting::SeparateDevice + } else { HeadphoneRouting::Off }; + } + rt.reclaim()?; + match rt.open(&config, prepared, self.errors.clone()) { + Ok(info) => { + *self.info.lock() = info; + *self.config.lock() = config; + Ok(()) + } + Err(error) => { + let restored = prepare(&rollback).and_then(|p| rt.open(&rollback, p, self.errors.clone())); + match restored { + Ok(mut info) => { + info.warning = old_info.warning; + *self.info.lock() = info; + Err(error.context("could not change output; previous output restored")) + } + Err(restore) => { + self.info.lock().warning = Some(format!("Audio stopped; deck state retained. Apply to retry. {restore:#}")); + Err(error.context("could not change or restore output; deck state retained")) + } + } } - std::thread::sleep(Duration::from_millis(5)); } - drop(stream_guard.take()); - let side = side.ok_or_else(|| anyhow!("audio callback did not respond; engine state lost"))?; - let (rp, rc) = rtrb::RingBuffer::>::new(2); - *self.ret.lock() = rc; - let new_eject = Arc::new(AtomicBool::new(false)); - let mut side = side; - side.core.apply(Command::SetDeckCount(config.decks)); - let (stream, info, _) = open_stream(&config, side, new_eject.clone(), rp, self.errors.clone())?; - *stream_guard = Some(stream); - *self.eject.lock() = new_eject; - *self.info.lock() = info; - *self.config.lock() = config; - Ok(()) } /// Start recording the master output to a WAV file. pub fn start_recording(&self, path: &Path, format: WavFormat) -> Result<()> { self.stop_recording()?; + let rt = self.runtime.lock(); let sr = self.info.lock().sample_rate; + if rt.streams.is_none() || rt.health.master.check_stalled(sr) { bail!("master output is unavailable"); } let (p, c) = rtrb::RingBuffer::::new(sr as usize * 2 * 10); let t = RecorderThread::spawn(path.to_path_buf(), sr, format, c)?; self.send(Command::SetRecorder(Some(p)))?; @@ -452,7 +780,30 @@ impl EngineHandle { /// Stop recording; returns the file path and number of frames written. pub fn stop_recording(&self) -> Result> { let Some(t) = self.recorder.lock().take() else { return Ok(None) }; - self.send(Command::SetRecorder(None))?; + if let Err(e) = self.send(Command::SetRecorder(None)) { + *self.recorder.lock() = Some(t); + return Err(e); + } + let deadline = Instant::now() + Duration::from_secs(3); + while !t.join.is_finished() { + let mut rt = self.runtime.lock(); + let sr = self.info.lock().sample_rate; + if rt.health.master.check_stalled(sr) || rt.streams.is_none() { + if let Err(e) = rt.reclaim() { + *self.recorder.lock() = Some(t); + return Err(e); + } + if let Some(side) = &mut rt.parked { + while let Ok(cmd) = side.cmds.pop() { side.core.apply(cmd); } + } + } + drop(rt); + if Instant::now() >= deadline { + *self.recorder.lock() = Some(t); + bail!("recorder did not finish; retry Stop recording"); + } + std::thread::sleep(Duration::from_millis(10)); + } Self::join_recorder(t) } @@ -472,8 +823,12 @@ impl EngineHandle { impl Drop for EngineHandle { fn drop(&mut self) { let rec = self.recorder.lock().take(); - // dropping the stream drops the engine (and the recorder ring), finishing the file - drop(self.stream.lock().take()); + // Return and drop the core before joining the recorder and garbage collector. + { + let rt = self.runtime.get_mut(); + let _ = rt.reclaim(); + drop(rt.parked.take()); + } if let Some(t) = rec { let _ = Self::join_recorder(t); } @@ -488,3 +843,152 @@ impl Drop for EngineHandle { fn major_faults() -> i64 { crate::sys::page_faults() } + +#[cfg(test)] +mod tests { + use super::*; + + fn range(channels: u16, min: u32, max: u32) -> cpal::SupportedStreamConfigRange { + cpal::SupportedStreamConfigRange::new(channels, min, max, + cpal::SupportedBufferSize::Range { min: 128, max: 1024 }, cpal::SampleFormat::F32) + } + + #[test] + fn legacy_audio_settings_keep_their_routing() { + for routing in [HeadphoneRouting::Auto, HeadphoneRouting::Off, HeadphoneRouting::Split, + HeadphoneRouting::Channels { master: [2, 3], cue: [0, 1] }] { + let mut value = serde_json::to_value(AudioConfig { headphones: routing, ..AudioConfig::default() }).unwrap(); + let fields = value.as_object_mut().unwrap(); + fields.remove("headphone_device"); + fields.remove("alignment_ms"); + fields.remove("alignment_key"); + let config: AudioConfig = serde_json::from_value(value).unwrap(); + assert_eq!(config.headphones, routing); + assert_eq!(config.headphone_device, None); + assert_eq!(config.alignment_ms, 0.0); + } + let config = AudioConfig { device: Some("master-id".into()), headphone_device: Some("cue-id".into()), + headphones: HeadphoneRouting::SeparateDevice, alignment_ms: -12.5, alignment_key: Some("pair".into()), ..AudioConfig::default() }; + assert_eq!(config, serde_json::from_str(&serde_json::to_string(&config).unwrap()).unwrap()); + } + + #[test] + fn device_ids_disambiguate_names_and_missing_selection_is_an_error() { + let candidates = vec![("USB Audio".into(), "id-one".into()), ("USB Audio".into(), "id-two".into()), ("Speakers".into(), "id-three".into())]; + assert_eq!(resolve_device("id-two", &candidates).unwrap(), 1); + assert_eq!(resolve_device("Speakers", &candidates).unwrap(), 2); + assert!(resolve_device("USB Audio", &candidates).is_err()); + assert!(resolve_device("unplugged", &candidates).is_err()); + } + + #[test] + fn correction_is_bound_to_the_resolved_pair_and_format() { + let mut config = AudioConfig { alignment_ms: 12.5, ..AudioConfig::default() }; + bind_alignment(&mut config, "master-a/cue-b/48000/256".into()); + bind_alignment(&mut config, "master-a/cue-b/48000/256".into()); + assert_eq!(config.alignment_ms, 12.5); + bind_alignment(&mut config, "master-a/cue-b/44100/256".into()); + assert_eq!(config.alignment_ms, 0.0); + config.alignment_ms = -20.0; + bind_alignment(&mut config, "master-a/cue-c/44100/256".into()); + assert_eq!(config.alignment_ms, 0.0); + } + + #[test] + fn negotiation_uses_exact_supported_channels_and_common_strict_format() { + let master = [range(2, 44100, 48000), range(8, 44100, 48000)]; + let cue = [range(2, 48000, 48000)]; + let mut config = AudioConfig::default(); + assert_eq!(choose_format(&master, Some(&cue), &config, 2).unwrap(), (2, 48000)); + assert_eq!(choose_format(&master, None, &config, 4).unwrap(), (8, 44100)); + config.sample_rate = Some(44100); + assert!(choose_format(&master, Some(&cue), &config, 2).is_err()); + config.sample_rate = None; + 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()); + 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()); + assert!(choose_format(&master, Some(&[range(1, 44100, 48000)]), &config, 2).is_err()); + } + + #[test] + fn single_device_rates_remain_preferences_and_buffers_are_validated_by_the_driver() { + for routing in [HeadphoneRouting::Auto, HeadphoneRouting::Off, HeadphoneRouting::Split, + HeadphoneRouting::Channels { master: [0, 1], cue: [2, 3] }] { + let config = AudioConfig { headphones: routing, sample_rate: Some(96000), buffer_frames: Some(64), ..AudioConfig::default() }; + let channels = if matches!(routing, HeadphoneRouting::Channels { .. }) { 4 } else { 2 }; + assert_eq!(choose_format(&[range(channels, 48000, 48000)], None, &config, channels).unwrap(), (channels, 48000)); + assert_eq!(choose_format(&[range(channels, 44100, 48000)], None, &config, channels).unwrap(), (channels, 44100)); + } + assert_eq!(default_format(&[range(2, 96000, 96000)], 2, 96000).unwrap(), (2, 96000)); + assert!(default_format(&[range(2, 96000, 96000)], 4, 96000).is_err()); + let strict = AudioConfig { headphones: HeadphoneRouting::SeparateDevice, sample_rate: Some(96000), ..AudioConfig::default() }; + assert!(choose_format(&[range(2, 48000, 48000)], Some(&[range(2, 48000, 48000)]), &strict, 2).is_err()); + } + + #[test] + fn shared_wasapi_period_is_not_mistaken_for_a_fixed_request_limit() { + let period = cpal::SupportedStreamConfigRange::new(2, 48000, 48000, + cpal::SupportedBufferSize::Range { min: 480, max: 480 }, cpal::SampleFormat::F32); + assert_eq!(supports_buffer(&period, Some(256)), cfg!(windows)); + assert!(supports_buffer(&period, None)); + } + + #[test] + fn stopped_callback_returns_the_same_core_even_without_another_callback() { + for callback_ran in [false, true] { + let (_, commands) = rtrb::RingBuffer::new(4); + let mut core = Box::new(EngineCore::new(48000, 2)); + core.apply(Command::SetMasterGain(-80.0)); + core.apply(Command::SetHeadphoneMix(0.25)); + let audio = Arc::new(clubcraft_audio::AudioBuffer::new(48000, vec![0.0; 48000], vec![0.0; 48000])); + core.apply(Command::LoadTrack(0, Arc::new(crate::LoadedTrack::new("retained", audio)))); + core.apply(Command::Seek(0, 0.5)); + let pointer = std::ptr::from_ref(core.as_ref()); + let side = Box::new(AudioSide { core, cmds: commands, master: vec![], cue: vec![] }); + let (mut lend, incoming) = rtrb::RingBuffer::new(1); + let (returns, mut returned) = rtrb::RingBuffer::new(2); + let mut loan = CoreLoan { side: None, incoming, returns }; + lend.push(side).unwrap(); + if callback_ran { assert!(loan.get().is_some()); } + drop(loan); + let side = returned.pop().unwrap(); + assert_eq!(pointer, std::ptr::from_ref(side.core.as_ref())); + assert_eq!(side.core.snapshot().master.headphone_mix, 0.25); + assert!((side.core.snapshot().decks[0].position - 0.5).abs() < 1e-6); + } + } + + #[test] + fn master_and_pfl_buses_keep_independent_gain_and_mix() { + let mut core = EngineCore::new(48000, 2); + core.apply(Command::SetLimiter { enabled: false, ceiling_db: -1.0 }); + for (deck, frequency) in [(0, 1000.0), (1, 500.0)] { + let samples: Vec<_> = (0..96000).map(|f| (2.0 * std::f32::consts::PI * frequency * f as f32 / 48000.0).sin() * 0.1).collect(); + let audio = Arc::new(clubcraft_audio::AudioBuffer::new(48000, samples.clone(), samples)); + core.apply(Command::LoadTrack(deck, Arc::new(crate::LoadedTrack::new("bus", audio)))); + core.apply(Command::SetKeylock(deck, false)); + core.apply(Command::Play(deck)); + } + core.apply(Command::SetFader(1, 0.0)); + core.apply(Command::SetPfl(1, true)); + core.apply(Command::SetHeadphoneMix(0.0)); + let mut master = [0.0; 960]; + let mut cue = [0.0; 960]; + for _ in 0..10 { core.process(&mut master, &mut cue); } + assert!(master.iter().zip(cue).map(|(m, c)| (m - c).abs()).sum::() > 10.0); + let reference = master; + let cue_level: f32 = cue.iter().map(|s| s.abs()).sum(); + core.apply(Command::SetHeadphoneGain(-20.0)); + core.process(&mut master, &mut cue); + assert!(master.iter().zip(reference).all(|(a, b)| (a - b).abs() < 0.001)); + assert!(cue.iter().map(|s| s.abs()).sum::() < cue_level * 0.2); + core.apply(Command::SetHeadphoneGain(0.0)); + core.apply(Command::SetHeadphoneMix(1.0)); + core.process(&mut master, &mut cue); + assert!(master.iter().zip(cue).all(|(m, c)| (m - c).abs() < 0.01)); + } +} diff --git a/crates/engine/src/lib.rs b/crates/engine/src/lib.rs index 951a9ee..b6eb686 100644 --- a/crates/engine/src/lib.rs +++ b/crates/engine/src/lib.rs @@ -36,6 +36,7 @@ pub mod core; pub mod deck; pub mod dsp; pub mod engine; +mod output; pub mod fx; pub mod midi; pub mod mixer; @@ -55,7 +56,7 @@ pub use command::{Command, DeckId, EqBand}; pub use conductor::{window_at, MixSchedule, MIX_WINDOW}; pub use core::EngineCore; pub use deck::Deck; -pub use engine::{devices, AudioConfig, CommandSender, DeviceInfo, Engine, EngineHandle, HeadphoneRouting, StreamInfo}; +pub use engine::{devices, AudioConfig, CommandSender, DeviceInfo, EndpointInfo, Engine, EngineHandle, HeadphoneRouting, StreamInfo}; pub use fx::FxKind; pub use mixer::{CrossfaderAssign, CrossfaderCurve, FaderCurve}; pub use player::{CommandSink, MixPlayer, PrefetchStatus, TrackLoader}; diff --git a/crates/engine/src/output.rs b/crates/engine/src/output.rs new file mode 100644 index 0000000..9ccc751 --- /dev/null +++ b/crates/engine/src/output.rs @@ -0,0 +1,749 @@ +//! Independent output clocks. Only the master callback advances the engine. +//! All storage and sinc phases are allocated before either stream starts. + +use std::sync::atomic::{AtomicBool, AtomicI32, AtomicU32, AtomicU64, Ordering}; +use std::sync::Arc; +use std::time::Instant; + +const TAPS: usize = 32; +const PHASES: usize = 512; +// Leave a transition band below Nyquist for the 32-tap filter at +/-0.5% drift. +const SINC_CUTOFF: f64 = 0.94; +// Queue error is measured in frames: 500 frames asks for 1000 ppm proportional +// correction. The integral removes steady clock error over tens of seconds. +const SERVO_PROPORTIONAL: f64 = 2e-6; +const SERVO_INTEGRAL: f64 = 1e-7; +// Two seconds rejects callback jitter. Reserve 4000 ppm for integral trim and +// cap total correction at 5000 ppm, comfortably above the tested +/-1000 ppm. +const SERVO_TAU_SECONDS: f64 = 2.0; +const SERVO_INTEGRAL_LIMIT: f64 = 0.004; +const SERVO_RATIO_LIMIT: f64 = 0.005; +// Count rendered cue time rather than wall time: waiting for a device or +// rebuffering must not make the first irregular callback the final calibration. +const ALIGNMENT_WARMUP_SECONDS: u64 = 2; +const ERROR_KINDS: [cpal::ErrorKind; 14] = [ + cpal::ErrorKind::DeviceBusy, + cpal::ErrorKind::DeviceChanged, + cpal::ErrorKind::DeviceNotAvailable, + cpal::ErrorKind::HostUnavailable, + cpal::ErrorKind::InvalidInput, + cpal::ErrorKind::PermissionDenied, + cpal::ErrorKind::RealtimeDenied, + cpal::ErrorKind::ResourceExhausted, + cpal::ErrorKind::StreamInvalidated, + cpal::ErrorKind::UnsupportedConfig, + cpal::ErrorKind::UnsupportedOperation, + cpal::ErrorKind::Xrun, + cpal::ErrorKind::BackendError, + cpal::ErrorKind::Other, +]; + +pub(crate) struct EndpointHealth { + pub frames: AtomicU32, + pub latency_us: AtomicU32, + pub errors: AtomicU32, + pub failed: AtomicBool, + pending_errors: AtomicU32, + created: Instant, + last_callback_us: AtomicU64, + armed: AtomicBool, +} + +impl Default for EndpointHealth { + fn default() -> Self { + Self { + frames: AtomicU32::new(0), + latency_us: AtomicU32::new(0), + errors: AtomicU32::new(0), + failed: AtomicBool::new(false), + pending_errors: AtomicU32::new(0), + created: Instant::now(), + last_callback_us: AtomicU64::new(0), + armed: AtomicBool::new(false), + } + } +} + +impl EndpointHealth { + /// Error callbacks may run on the audio thread: keep diagnostics allocation-free. + pub fn report_error(&self, kind: cpal::ErrorKind) { + self.errors.fetch_add(1, Ordering::Relaxed); + let index = ERROR_KINDS.iter().position(|k| *k == kind).unwrap_or(ERROR_KINDS.len() - 1); + self.pending_errors.fetch_or(1 << index, Ordering::Relaxed); + // BackendError has no reliable fatality classification. Let callback + // liveness diagnose it rather than permanently muting a healthy stream. + if !matches!( + kind, + cpal::ErrorKind::Xrun + | cpal::ErrorKind::DeviceChanged + | cpal::ErrorKind::RealtimeDenied + | cpal::ErrorKind::DeviceBusy + | cpal::ErrorKind::ResourceExhausted + | cpal::ErrorKind::BackendError + ) { + self.failed.store(true, Ordering::Release); + } + } + + /// Called only outside audio callbacks; coalesce repeated xruns between polls. + pub fn log_errors(&self, name: &str) { + let pending = self.pending_errors.swap(0, Ordering::Relaxed); + for (index, kind) in ERROR_KINDS.iter().enumerate() { + if pending & (1 << index) != 0 { + log::warn!("Audio output {name}: {kind}"); + } + } + } + + pub fn heartbeat(&self, frames: usize) { + self.last_callback_us.store(self.created.elapsed().as_micros() as u64, Ordering::Relaxed); + self.frames.store(frames as u32, Ordering::Relaxed); + } + + pub fn arm(&self) { + self.last_callback_us.store(self.created.elapsed().as_micros() as u64, Ordering::Relaxed); + self.armed.store(true, Ordering::Release); + } + + pub fn check_stalled(&self, sr: u32) -> bool { + let budget_us = self.frames.load(Ordering::Relaxed) as u64 * 1_000_000 / sr.max(1) as u64; + let age = (self.created.elapsed().as_micros() as u64).saturating_sub(self.last_callback_us.load(Ordering::Relaxed)); + // A stall is a live observation, not a terminal error. A resumed callback + // updates the heartbeat and immediately restores this status. + self.failed.load(Ordering::Acquire) || (self.armed.load(Ordering::Acquire) && age > (budget_us * 8).max(2_000_000)) + } +} + +#[derive(Default)] +pub(crate) struct OutputHealth { + pub master: EndpointHealth, + pub cue: EndpointHealth, + pub underruns: AtomicU32, + pub overflows: AtomicU32, + pub reset: AtomicBool, + pub master_delay: AtomicU32, + pub cue_delay: AtomicU32, + pub offset_us: AtomicI32, +} + +/// Zero means unavailable, including backends which supply zero timestamps. +pub(crate) fn observe(info: &cpal::OutputCallbackInfo, frames: usize, health: &EndpointHealth) -> Option { + health.heartbeat(frames); + let t = info.timestamp(); + let us = t + .playback + .checked_duration_since(t.callback) + .filter(|d| !d.is_zero() && d.as_secs_f64() < 2.0) + .map(|d| d.as_micros() as u32) + .unwrap_or(0); + health.latency_us.store(us, Ordering::Relaxed); + (us != 0).then_some(us as u64 * 1000) +} + +#[derive(Clone, Copy, Default)] +pub(crate) struct CueFrame { + pub samples: [f32; 2], + /// Predicted, undelayed master presentation time in the shared Instant epoch. + pub master_ns: u64, +} + +/// A bounded fractional stereo delay with fixed read positions. A tap change +/// crossfades over 128 frames; moving a read position would bend the pitch. +pub(crate) struct Delay { + frames: Vec<[f32; 2]>, + write: usize, + delay: f64, + previous: f64, + fade: f32, +} + +impl Delay { + pub fn new(sr: u32) -> Self { + Self { + frames: vec![[0.0; 2]; sr as usize * 2 + 2], + write: 0, + delay: 0.0, + previous: 0.0, + fade: 1.0, + } + } + + pub fn process(&mut self, frame: [f32; 2], target: f64) -> [f32; 2] { + let target = target.clamp(0.0, (self.frames.len() - 2) as f64); + if target != self.delay { + self.previous = self.delay; + self.delay = target; + self.fade = 0.0; + } + self.frames[self.write] = frame; + let current = self.read(self.delay); + let previous = self.read(self.previous); + self.fade = (self.fade + 1.0 / 128.0).min(1.0); + let out = std::array::from_fn(|i| previous[i] + (current[i] - previous[i]) * self.fade); + self.write = (self.write + 1) % self.frames.len(); + out + } + + fn read(&self, delay: f64) -> [f32; 2] { + let read = (self.write as f64 - delay).rem_euclid(self.frames.len() as f64); + let base = read.floor(); + // rem_euclid may round a tiny negative input up to exactly len. + let a = base as usize % self.frames.len(); + let b = (a + 1) % self.frames.len(); + let t = (read - base) as f32; + std::array::from_fn(|i| self.frames[a][i] + (self.frames[b][i] - self.frames[a][i]) * t) + } +} + +/// PI correction is intentionally slow: callback scheduling jitter is not clock drift. +#[derive(Default)] +struct ClockServo { + error: f64, + integral: f64, + ratio: f64, +} + +impl ClockServo { + fn update(&mut self, error: f64, seconds: f64) -> f64 { + let smoothing = 1.0 - (-seconds / SERVO_TAU_SECONDS).exp(); + self.error += (error - self.error) * smoothing; + self.integral = (self.integral + self.error * seconds * SERVO_INTEGRAL).clamp(-SERVO_INTEGRAL_LIMIT, SERVO_INTEGRAL_LIMIT); + let desired_ratio = (self.error * SERVO_PROPORTIONAL + self.integral).clamp(-SERVO_RATIO_LIMIT, SERVO_RATIO_LIMIT); + self.ratio += (desired_ratio - self.ratio) * smoothing; + 1.0 + self.ratio + } +} + +pub(crate) fn alignment(offset_ns: f64, correction_ms: f64, sr: u32) -> (f64, f64) { + let frames = (offset_ns * 1e-9 + correction_ms * 0.001) * sr as f64; + (frames.clamp(0.0, sr as f64 * 2.0), (-frames).clamp(0.0, sr as f64 * 2.0)) +} + +pub(crate) struct CueOutput { + input: rtrb::Consumer, + health: Arc, + epoch: Instant, + sr: u32, + correction_ms: f64, + history: [CueFrame; TAPS], + head: usize, + phase: f64, + kernel: Vec<[f32; TAPS]>, + servo: ClockServo, + started: bool, + gain: f32, + last: [f32; 2], + delay: Delay, + offset_ns: Option, + estimate_frames: u64, + estimate_has_timestamps: Option, + alignment_set: bool, +} + +impl CueOutput { + pub fn new(input: rtrb::Consumer, health: Arc, epoch: Instant, sr: u32, correction_ms: f64) -> Self { + let kernel = (0..=PHASES) + .map(|p| { + let frac = p as f64 / PHASES as f64; + let mut row = std::array::from_fn(|k| { + let x = k as f64 - (TAPS / 2 - 1) as f64 - frac; + let sinc = if x.abs() < 1e-10 { + SINC_CUTOFF + } else { + (std::f64::consts::PI * x * SINC_CUTOFF).sin() / (std::f64::consts::PI * x) + }; + // Blackman window limits sidelobes of the short sinc kernel. + let angle = std::f64::consts::PI * x / (TAPS / 2) as f64; + let window = 0.42 + 0.5 * angle.cos() + 0.08 * (2.0 * angle).cos(); + (sinc * window) as f32 + }); + let sum: f32 = row.iter().sum(); + for c in &mut row { + *c /= sum; + } + row + }) + .collect(); + Self { + input, + health, + epoch, + sr, + correction_ms, + history: [CueFrame::default(); TAPS], + head: 0, + phase: 0.0, + kernel, + servo: ClockServo::default(), + started: false, + gain: 0.0, + last: [0.0; 2], + delay: Delay::new(sr), + offset_ns: None, + estimate_frames: 0, + estimate_has_timestamps: None, + alignment_set: false, + } + } + + pub fn render(&mut self, data: &mut [f32], info: &cpal::OutputCallbackInfo) { + let frames = data.len() / 2; + 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)); + } + + fn render_at(&mut self, data: &mut [f32], playback_ns: Option) { + let frames = data.len() / 2; + 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 { + // A pathological driver buffer must not leave cue waiting forever + // for more data than the bounded transport can hold. + self.health.cue.failed.store(true, Ordering::Release); + data.fill(0.0); + return; + } + let reset = self.health.reset.swap(false, Ordering::Relaxed); + if reset || self.input.slots() > target + block * 6 + TAPS { + if !reset { + self.health.overflows.fetch_add(1, Ordering::Relaxed); + } + self.started = false; + self.reset_estimate(); + while self.input.slots() > target + frames + TAPS { + let _ = self.input.pop(); + } + } + if !self.started && self.gain == 0.0 && self.input.slots() >= target + frames + TAPS { + for h in &mut self.history { + *h = self.input.pop().unwrap_or_default(); + } + self.head = 0; + self.phase = 0.0; + self.servo = ClockServo::default(); + self.reset_estimate(); + self.started = true; + } + let ratio = self + .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() { + if self.started { + while self.phase >= 1.0 { + if let Ok(h) = self.input.pop() { + self.history[self.head] = h; + self.head = (self.head + 1) % TAPS; + self.phase -= 1.0; + } else { + self.started = false; + self.health.underruns.fetch_add(1, Ordering::Relaxed); + break; + } + } + } + if self.started { + let phase_position = self.phase * PHASES as f64; + let phase_index = phase_position as usize; + let phase_blend = (phase_position - phase_index as f64) as f32; + let mut sample = [0.0; 2]; + for k in 0..TAPS { + let frame = self.history[(self.head + k) % TAPS]; + let coefficient = self.kernel[phase_index][k] + (self.kernel[phase_index + 1][k] - self.kernel[phase_index][k]) * phase_blend; + sample[0] += frame.samples[0] * coefficient; + sample[1] += frame.samples[1] * coefficient; + } + if !measured { + let h = self.history[(self.head + TAPS / 2 - 1) % TAPS]; + if let Some(playback) = playback_ns.filter(|_| h.master_ns != 0) { + let offset = playback as f64 + (f as f64 - self.phase) * 1e9 / self.sr as f64 - h.master_ns as f64; + self.set_alignment(offset, frames, true); + } else { + // Without driver timing we still know the queued frames + // ahead of the sample at the sinc center. Include all of + // them, not just the configured target fill. + let queued = self.input.slots() as f64 + (TAPS / 2 + 1) as f64 - self.phase; + self.set_alignment(queued * 1e9 / self.sr as f64, frames, false); + } + measured = true; + } + self.last = sample; + self.phase += ratio; + } + 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); + } + } + + fn reset_estimate(&mut self) { + self.offset_ns = None; + self.estimate_frames = 0; + self.estimate_has_timestamps = None; + } + + fn set_alignment(&mut self, offset_ns: f64, frames: usize, has_timestamps: bool) { + if frames == 0 { + return; + } + if self.estimate_has_timestamps != Some(has_timestamps) { + self.reset_estimate(); + self.estimate_has_timestamps = Some(has_timestamps); + } + self.estimate_frames = self.estimate_frames.saturating_add(frames as u64); + // Average the first second by sample count, then use a one-second low + // pass. This prevents the first callback from dominating the estimate + // while giving startup irregularities two seconds to settle. + let smoothing = (frames as f64 / self.estimate_frames.min(self.sr as u64) as f64).min(1.0); + let filtered = self.offset_ns.map(|old| old + (offset_ns - old) * smoothing).unwrap_or(offset_ns); + self.offset_ns = Some(filtered); + self.health + .offset_us + .store(if has_timestamps { (filtered / 1000.0) as i32 } else { i32::MIN }, Ordering::Relaxed); + // Latch once after warmup. Queue jitter and rebuffering must never + // move the master tap. Apply (including correction changes) recalibrates; + // all continuous clock correction stays in the cue resampler. + if !self.alignment_set && self.estimate_frames >= self.sr as u64 * ALIGNMENT_WARMUP_SECONDS { + let (master, cue) = alignment(filtered, self.correction_ms, self.sr); + self.health.master_delay.store(master.round() as u32, Ordering::Relaxed); + self.health.cue_delay.store(cue.round() as u32, Ordering::Relaxed); + self.alignment_set = true; + } + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_device_that_stops_callbacks_is_reported_even_without_an_error_callback() { + let endpoint = EndpointHealth::default(); + assert!(!endpoint.check_stalled(48000)); + endpoint.arm(); + assert!(!endpoint.check_stalled(48000)); + let stale = EndpointHealth { + created: Instant::now().checked_sub(std::time::Duration::from_secs(10)).unwrap(), + armed: AtomicBool::new(true), + ..EndpointHealth::default() + }; + assert!(stale.check_stalled(48000)); + assert!(!stale.failed.load(Ordering::Acquire)); + stale.heartbeat(256); + assert!(!stale.check_stalled(48000)); + stale.report_error(cpal::ErrorKind::StreamInvalidated); + stale.heartbeat(256); + assert!(stale.check_stalled(48000)); + } + + #[test] + fn transient_errors_keep_both_outputs_running_and_terminal_errors_stay_failed() { + let health = OutputHealth::default(); + for endpoint in [&health.master, &health.cue] { + endpoint.arm(); + for kind in [ + cpal::ErrorKind::Xrun, + cpal::ErrorKind::DeviceChanged, + cpal::ErrorKind::RealtimeDenied, + cpal::ErrorKind::DeviceBusy, + cpal::ErrorKind::ResourceExhausted, + cpal::ErrorKind::BackendError, + ] { + endpoint.report_error(kind); + endpoint.heartbeat(256); + assert!(!endpoint.check_stalled(48000), "{kind:?}"); + } + assert_eq!(endpoint.errors.load(Ordering::Relaxed), 6); + assert_ne!(endpoint.pending_errors.load(Ordering::Relaxed), 0); + endpoint.log_errors("test output"); + assert_eq!(endpoint.pending_errors.load(Ordering::Relaxed), 0); + } + health.cue.report_error(cpal::ErrorKind::DeviceNotAvailable); + assert!(health.cue.check_stalled(48000)); + assert!(!health.master.check_stalled(48000)); + for kind in [ + cpal::ErrorKind::DeviceNotAvailable, + cpal::ErrorKind::StreamInvalidated, + cpal::ErrorKind::HostUnavailable, + cpal::ErrorKind::PermissionDenied, + cpal::ErrorKind::Other, + ] { + let endpoint = EndpointHealth::default(); + endpoint.report_error(kind); + endpoint.heartbeat(256); + assert!(endpoint.check_stalled(48000), "{kind:?}"); + } + } + + #[test] + fn master_alignment_does_not_follow_jitter_or_rebuffering() { + let health = Arc::new(OutputHealth::default()); + let (_, input) = rtrb::RingBuffer::new(96000); + let mut cue = CueOutput::new(input, health.clone(), Instant::now(), 48000, 5.0); + cue.set_alignment(25_000_000.0, 48000, true); + assert_eq!(health.master_delay.load(Ordering::Relaxed), 0); + cue.set_alignment(25_000_000.0, 48000, true); + let delay = health.master_delay.load(Ordering::Relaxed); + assert_eq!(delay, 1440); + for offset in [35_000_000.0, -10_000_000.0, 120_000_000.0] { + cue.set_alignment(offset, 256, true); + health.reset.store(true, Ordering::Relaxed); + cue.render_at(&mut [0.0; 512], None); + assert_eq!(health.master_delay.load(Ordering::Relaxed), delay); + } + } + + #[test] + fn alignment_averages_startup_outliers_and_waits_for_two_seconds() { + let health = Arc::new(OutputHealth::default()); + let (_, input) = rtrb::RingBuffer::new(96000); + let mut cue = CueOutput::new(input, health.clone(), Instant::now(), 48000, 0.0); + cue.set_alignment(120_000_000.0, 256, true); + for _ in 1..374 { + cue.set_alignment(20_000_000.0, 256, true); + assert!(!cue.alignment_set); + assert_eq!(health.master_delay.load(Ordering::Relaxed), 0); + } + cue.set_alignment(20_000_000.0, 256, true); + assert!(cue.alignment_set); + let frames = health.master_delay.load(Ordering::Relaxed); + assert!((frames as f64 / 48.0 - 20.0).abs() < 1.0); + cue.set_alignment(120_000_000.0, 96000, true); + assert_eq!(health.master_delay.load(Ordering::Relaxed), frames); + } + + #[test] + fn calibration_warmup_restarts_on_rebuffering_or_timing_source_change() { + let health = Arc::new(OutputHealth::default()); + let (_, input) = rtrb::RingBuffer::new(96000); + let mut cue = CueOutput::new(input, health.clone(), Instant::now(), 48000, -10.0); + cue.set_alignment(100_000_000.0, 72000, true); + health.reset.store(true, Ordering::Relaxed); + cue.render_at(&mut [0.0; 512], None); + assert_eq!(cue.estimate_frames, 0); + cue.set_alignment(100_000_000.0, 72000, true); + cue.set_alignment(30_000_000.0, 48000, false); + assert!(!cue.alignment_set); + assert_eq!(cue.estimate_frames, 48000); + assert_eq!(health.offset_us.load(Ordering::Relaxed), i32::MIN); + cue.set_alignment(30_000_000.0, 48000, false); + assert_eq!(health.master_delay.load(Ordering::Relaxed), 960); + // Losing timestamps after calibration affects diagnostics, not the master tap. + cue.set_alignment(200_000_000.0, 96000, true); + assert_eq!(health.master_delay.load(Ordering::Relaxed), 960); + } + + #[test] + fn a_master_delay_change_crossfades_fixed_taps_without_resampling() { + let mut delay = Delay::new(48000); + for frame in 0..2000 { + let sample = (frame as f32 * 0.13).sin(); + delay.process([sample; 2], 0.0); + } + for frame in 2000..2500 { + let sample = (frame as f32 * 0.13).sin(); + let out = delay.process([sample; 2], 1200.0); + let blend = ((frame - 2000 + 1) as f32 / 128.0).min(1.0); + let delayed = ((frame - 1200) as f32 * 0.13).sin(); + assert!((out[0] - (sample + (delayed - sample) * blend)).abs() < 1e-6); + assert_eq!(delay.delay, 1200.0); + } + } + + #[test] + fn one_hour_of_independent_clocks_and_callback_jitter() { + for ppm in [-1000.0, 1000.0] { + let mut servo = ClockServo::default(); + let mut fill = 960.0; + let mut consumed = 0.0; + let sr = 48000.0; + let mut peak: f64 = 0.0; + for block in 0..675000 { + let n = [128.0, 512.0, 256.0, 128.0][block % 4]; + let dt = n / (sr * (1.0 + ppm * 1e-6)); + // Bounded scheduling jitter, with no net long-term clock change. + let jitter = if block % 2 == 0 { 16.0 } else { -16.0 }; + let ratio = servo.update(fill - 960.0 + jitter, dt); + fill += dt * sr - n * ratio; + consumed += dt; + peak = peak.max((fill - 960.0).abs()); + assert!((400.0..1500.0).contains(&fill)); + } + assert!(consumed >= 3590.0); + assert!(peak < 500.0); + assert!((servo.ratio + ppm * 1e-6).abs() < 0.00002); + } + } + + #[test] + fn alignment_sign_and_fractional_delay() { + assert_eq!(alignment(20_000_000.0, 5.0, 48000), (1200.0, 0.0)); + let (m, c) = alignment(20_000_000.0, -30.0, 48000); + assert_eq!(m, 0.0); + assert!((c - 480.0).abs() < 1e-8); + for target in [0.0, 1e-12, 17.5, 240.25, 1200.0, 24000.0] { + let mut delay = Delay::new(48000); + for _ in 0..100000 { + delay.process([0.0; 2], target); + } + let mut peak = (0, 0.0f32); + for f in 0..25000 { + let out = delay.process(if f == 0 { [1.0, -1.0] } else { [0.0; 2] }, target); + assert_eq!(out[0], -out[1]); + if out[0] > peak.1 { + peak = (f, out[0]); + } + } + assert!((peak.0 as f64 - target).abs() < 1.0); + } + } + + #[test] + fn cue_timestamps_include_queue_and_filter_lookahead_in_alignment() { + for correction in [-250.0, 0.0, 20.0] { + let health = Arc::new(OutputHealth::default()); + health.master.frames.store(256, Ordering::Relaxed); + let (mut tx, rx) = rtrb::RingBuffer::new(96000); + let mut cue = CueOutput::new(rx, health.clone(), Instant::now(), 48000, correction); + // A synthetic impulse at the center tap is presented by master at + // 1 s + 15 frames. The headphone driver schedules it at 1.2 s. + for f in 0..2000 { + tx.push(CueFrame { + samples: if f == 15 { [1.0; 2] } else { [0.0; 2] }, + master_ns: 1_000_000_000 + f * 1_000_000_000 / 48000, + }) + .unwrap(); + } + cue.render_at(&mut [0.0; 512], Some(1_200_000_000)); + assert!(!cue.alignment_set); + let measured = cue.offset_ns.unwrap(); + for _ in 1..375 { + cue.set_alignment(measured, 256, true); + } + assert!(cue.alignment_set); + let m = health.master_delay.load(Ordering::Relaxed) as f64; + let c = health.cue_delay.load(Ordering::Relaxed) as f64; + let residual = (200.0 - 15.0 / 48.0 + correction) - (m - c) / 48.0; + assert!(residual.abs() < 1.0, "alignment residual {residual} ms"); + } + } + + #[test] + fn missing_timestamps_and_manual_correction_are_explicit() { + let health = Arc::new(OutputHealth::default()); + let info = cpal::OutputCallbackInfo::new(cpal::OutputStreamTimestamp { + callback: cpal::StreamInstant::new(1, 0), + playback: cpal::StreamInstant::new(1, 10_000_000), + }); + assert_eq!(observe(&info, 128, &health.master), Some(10_000_000)); + assert_eq!(health.master.frames.load(Ordering::Relaxed), 128); + let unknown = cpal::OutputCallbackInfo::new(cpal::OutputStreamTimestamp { + callback: cpal::StreamInstant::ZERO, + playback: cpal::StreamInstant::ZERO, + }); + assert_eq!(observe(&unknown, 512, &health.cue), None); + let (mut tx, rx) = rtrb::RingBuffer::new(96000); + for _ in 0..2400 { + tx.push(CueFrame::default()).unwrap(); + } + let mut cue = CueOutput::new(rx, health.clone(), Instant::now(), 48000, -10.0); + cue.render_at(&mut [0.0; 512], None); + assert_eq!(health.offset_us.load(Ordering::Relaxed), i32::MIN); + assert!(!cue.alignment_set); + let measured = cue.offset_ns.unwrap(); + for _ in 1..375 { + cue.set_alignment(measured, 256, false); + } + // At the first rendered sample there are 2368 frames still queued and + // 17 frames of sinc history ahead. The -10 ms correction removes 480. + assert_eq!(health.master_delay.load(Ordering::Relaxed), 2368 + 17 - 480); + assert_eq!(health.cue_delay.load(Ordering::Relaxed), 0); + } + + #[test] + fn cue_clock_renders_stereo_and_recovers_without_touching_master() { + let health = Arc::new(OutputHealth::default()); + health.master.frames.store(256, Ordering::Relaxed); + let (mut tx, rx) = rtrb::RingBuffer::new(96000); + let mut cue = CueOutput::new(rx, health.clone(), Instant::now(), 48000, 0.0); + let mut out = vec![0.0; 512]; + for _ in 0..2000 { + tx.push(CueFrame { + samples: [0.25, -0.5], + master_ns: 1, + }) + .unwrap(); + } + for _ in 0..8 { + cue.render_at(&mut out, Some(30_000_000)); + } + assert!(out.iter().all(|s| s.is_finite())); + assert!(health.underruns.load(Ordering::Relaxed) > 0); + for _ in 0..20 { + cue.render_at(&mut out, None); + } + assert!(out.iter().all(|s| s.abs() < 1e-6)); + for _ in 0..2000 { + tx.push(CueFrame { + samples: [0.25, -0.5], + master_ns: 1, + }) + .unwrap(); + } + cue.render_at(&mut out, None); + assert!((out[510] - 0.25).abs() < 1e-4); + assert!((out[511] + 0.5).abs() < 1e-4); + assert_eq!(health.offset_us.load(Ordering::Relaxed), i32::MIN); + health.reset.store(true, Ordering::Relaxed); + cue.render_at(&mut out, None); + assert!(out.iter().all(|s| s.is_finite())); + } + + #[test] + fn independently_scheduled_callbacks_with_different_sizes_and_jitter() { + for ppm in [-1000.0, 1000.0] { + let health = Arc::new(OutputHealth::default()); + let (mut tx, rx) = rtrb::RingBuffer::new(96000); + let mut cue = CueOutput::new(rx, health.clone(), Instant::now(), 48000, 0.0); + let mut master_time = 0.0; + let mut cue_time = 0.001; + let mut master_frames = 0u64; + let mut master_blocks = 0; + let mut cue_blocks = 0; + let mut data = [0.0; 1024]; + while master_time < 30.0 || cue_time < 30.0 { + if master_time <= cue_time { + let n = [128, 512, 256, 512][master_blocks % 4]; + health.master.frames.store(n, Ordering::Relaxed); + for f in 0..n { + let s = (2.0 * std::f64::consts::PI * 1000.0 * (master_frames + f as u64) as f64 / 48000.0).sin() as f32 * 0.1; + tx.push(CueFrame { + samples: [s, -s], + master_ns: ((1.0 + master_time + 0.01) * 1e9) as u64 + f as u64 * 1_000_000_000 / 48000, + }) + .unwrap(); + } + master_frames += n as u64; + master_time += n as f64 / 48000.0 + if master_blocks % 2 == 0 { 0.0002 } else { -0.0002 }; + master_blocks += 1; + } else { + let n = [256, 128, 512, 128][cue_blocks % 4]; + let out = &mut data[..n * 2]; + cue.render_at(out, Some(((1.0 + cue_time + 0.02) * 1e9) as u64)); + for frame in out.as_chunks::<2>().0 { + assert!(frame[0].is_finite() && frame[0].abs() < 0.11); + assert_eq!(frame[0], -frame[1]); + } + cue_time += n as f64 / (48000.0 * (1.0 + ppm * 1e-6)) + if cue_blocks % 2 == 0 { -0.00015 } else { 0.00015 }; + cue_blocks += 1; + } + } + assert_eq!(health.underruns.load(Ordering::Relaxed), 0); + assert_eq!(health.overflows.load(Ordering::Relaxed), 0); + assert!(cue.input.slots() < 4096); + assert!(health.master_delay.load(Ordering::Relaxed) > 0); + } + } +} diff --git a/crates/engine/src/sys.rs b/crates/engine/src/sys.rs index 90f0a51..0ec52d0 100644 --- a/crates/engine/src/sys.rs +++ b/crates/engine/src/sys.rs @@ -35,16 +35,17 @@ pub fn lock(v: &[T]) -> bool { /// Undo [`lock`]. pub fn unlock(v: &[T]) { - if v.is_empty() { - return; - } #[cfg(unix)] { - // SAFETY: as in `lock`. - unsafe { - libc::munlock(v.as_ptr().cast(), std::mem::size_of_val(v)); + if !v.is_empty() { + // SAFETY: as in `lock`. + unsafe { + libc::munlock(v.as_ptr().cast(), std::mem::size_of_val(v)); + } } } + #[cfg(not(unix))] + let _ = v; } /// Give the calling thread a lower CPU priority, for background work (stem separation, diff --git a/crates/engine/tests/engine.rs b/crates/engine/tests/engine.rs index 9e0beaa..fbf9058 100644 --- a/crates/engine/tests/engine.rs +++ b/crates/engine/tests/engine.rs @@ -369,7 +369,9 @@ fn cpu_budget_4_decks_keylock_stems_fx() { let mut m = vec![0f32; block * 2]; let mut c = vec![0f32; block * 2]; let blocks = (secs * 48000.0) as usize / block; - // thread CPU time (excludes time the OS spent running other processes) + // Unix supplies thread CPU time. Elsewhere use monotonic elapsed time for + // diagnostics, without enforcing a CPU threshold affected by other processes. + #[cfg(unix)] fn cpu_now() -> f64 { let mut ts = libc::timespec { tv_sec: 0, tv_nsec: 0 }; // SAFETY: clock_gettime only writes the timespec we pass. @@ -379,6 +381,11 @@ fn cpu_budget_4_decks_keylock_stems_fx() { }; ts.tv_sec as f64 + ts.tv_nsec as f64 * 1e-9 } + #[cfg(not(unix))] + fn cpu_now() -> f64 { + static START: std::sync::OnceLock = std::sync::OnceLock::new(); + START.get_or_init(std::time::Instant::now).elapsed().as_secs_f64() + } let mut times = Vec::with_capacity(blocks); let wall = std::time::Instant::now(); let t0 = cpu_now(); @@ -388,7 +395,8 @@ fn cpu_budget_4_decks_keylock_stems_fx() { times.push(cpu_now() - tb); } let el = cpu_now() - t0; - eprintln!("wall clock {:.3} s (machine load affects this), thread CPU {:.3} s", wall.elapsed().as_secs_f64(), el); + let timing = if cfg!(unix) { "thread CPU" } else { "elapsed wall time" }; + eprintln!("wall clock {:.3} s (machine load affects this), {timing} {:.3} s", wall.elapsed().as_secs_f64(), el); let first = times[0]; let mut sorted: Vec = times[4..].to_vec(); sorted.sort_by(|a, b| a.partial_cmp(b).unwrap()); @@ -401,7 +409,7 @@ fn cpu_budget_4_decks_keylock_stems_fx() { let rt = el / secs; let block_budget = block as f64 / 48000.0; eprintln!( - "CPU: 10 s of 4 decks (keylock + stems + 2 FX each) in {:.3} s CPU → {:.2} % of one core total, {:.2} % per deck; worst block {:.3} ms of {:.3} ms budget ({:.1} %)", + "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} %)", el, rt * 100.0, rt * 25.0, @@ -409,7 +417,7 @@ fn cpu_budget_4_decks_keylock_stems_fx() { block_budget * 1000.0, worst_block / block_budget * 100.0 ); - if !cfg!(debug_assertions) { + if !cfg!(debug_assertions) && cfg!(unix) { assert!(rt < 0.25, "realtime factor {rt}"); } } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 587b683..0f06d36 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -25,6 +25,9 @@ automix with the planned mix points. Dependency direction: `core` ← `audio` ← (`stems`, `analysis`, `engine`) ← `app`. +Live output can use one multichannel device or separate master/cue devices. See +[audio outputs](audio-output.md) for format negotiation, clock drift, alignment and recovery. + ## Conventions * Internal audio: **44 100 Hz, stereo, f32**. Positions in **seconds** of the original track diff --git a/docs/audio-output.md b/docs/audio-output.md new file mode 100644 index 0000000..5976119 --- /dev/null +++ b/docs/audio-output.md @@ -0,0 +1,118 @@ +# Audio outputs + +In Settings → Audio output, choose a master device and a headphone routing mode. +Changes are staged until **Apply**; **Discard changes** restores the last applied settings. + +The existing single-device modes remain available: Auto uses master 1/2 and cue 3/4 +when the device exposes four outputs; Off uses master only; Split sends mono master +left and mono cue right. Explicit channel pairs must not overlap. +For these single-device modes the saved sample rate remains a preference: the +engine tries it, then 44.1/48 kHz, then the device default. Fixed buffer requests +are validated by the driver. If a saved setup cannot start, the app retries the +system default setup and shows a warning. This temporary fallback never replaces +the saved device or format, including on exit or a restart from Settings. A later +launch retries the original choice. Successful explicit Apply still saves the +selected configuration. + +## Two devices + +Choose **Separate device (stereo cue)** and select a headphone device. Master and +cue use channels 1/2 of their respective devices. Any two devices in the list can +be selected; there are still only two active output destinations. + +Both devices must support stereo F32 at the same nominal sample rate and requested +buffer size. Auto chooses common 44.1 kHz, then common 48 kHz. An explicit rate is +required, not a preference which may silently fall back. Drivers can deliver +different callback lengths despite a common buffer request; the settings show the +observed lengths for both streams. Selecting Device default leaves buffer sizing +to each driver. + +Devices are saved by ID. Existing settings using names are migrated when resolved; +duplicate names require selecting an ID again. An explicitly selected missing +master in Separate device mode is never replaced by the system default. If headphones cannot open at +startup, the selected master can run alone with a visible warning. + +## Alignment + +Only the master callback advances decks and records the master bus. A bounded, +preallocated SPSC queue carries stereo cue frames to the headphone callback. A +32-tap windowed-sinc resampler slowly adjusts its ratio according to queue fill, +compensating independent device clock drift without changing the master signal. +The cue queue targets at least 20 ms or two callbacks, whichever is larger. + +Each cue frame carries the undelayed master presentation estimate in a shared +monotonic epoch. The cue callback compares this with its own driver presentation +estimate, accounting for the queue and resampler lookahead. These estimates are +smoothed before calibration. The engine collects two seconds of rendered cue +audio before fixing output delays for the lifetime of the opened streams. The +first second uses a sample-weighted average, followed by a one-second low pass, +so one irregular startup callback does not dominate the result. Rebuffering or +a timing-source change before calibration restarts the warmup. Queue jitter and +rebuffering after calibration never move the master delay; continuous drift +correction happens only in the cue resampler. +Apply restarts this calibration, including after a correction change. A tap change +crossfades fixed read positions over 128 frames instead of bending the pitch. +Added delay is bounded to two seconds per output. Fixed calibration can leave +residual alignment error as device latency or queue fill changes; use Apply to +recalibrate and the manual correction for remaining acoustic offsets. + +**Alignment correction** ranges from −500 to +500 ms. Positive means the headphones +lag further than estimated, so master receives more delay; negative moves the +balance towards delaying headphones. The correction is bound to the resolved +device pair, rate and buffer. Changing these resets the correction. + +When driver timestamps are unavailable, the UI says so. The known queued cue +frames and sinc lookahead are still compensated along with the manual correction. +This does not estimate the unknown device latency. Driver estimates do not measure the entire analog or +acoustic path. Verify alignment by listening; precise analog calibration requires +an external measurement. In particular, aligning a slow headphone output increases +the latency from a control action to master playback. +Bluetooth codec buffering is usually absent from driver estimates. Bluetooth +headphones are unsuitable for low-latency cueing; manual correction can align +them only by adding the corresponding latency to master. + +## Failure and recording + +Cue underflow fades to silence and waits to refill; overflow discards stale cue +data and fades back in. Separate underrun/overflow counters are shown. A failed +headphone stream does not stop master and is never routed to the speakers. +A failed master stream stops advancing decks. Use Apply to retry or change devices. +Xruns, automatic route changes and other recoverable stream events are counted +without permanently muting either output. Error kinds are logged outside the +audio callbacks when diagnostics are polled. Callback stalls are reported while +callbacks are missing and clear automatically when they resume. Terminal errors +such as device loss or stream invalidation require reopening with Apply. + +Configuration is validated before stopping an existing stream. The core is lent +to a callback only after all new streams have opened and started; destroying the +callback returns that same core even if the device no longer calls it. Failed +changes attempt to restore the old output. If restoration fails, the core stays +parked with deck state retained for another Apply. + +Recording taps the original master before output alignment delays. Sample-rate +changes are rejected while recording; stop recording before changing the rate. + +## Verification + +Automated tests cover settings compatibility, ID selection, format negotiation, +core ownership on callback destruction, independent clock control at ±1000 ppm, +fractional delay and correction sign, stereo cue resampling and rebuffering. +The clock-control simulation runs a virtual hour without playing audio. + +For a silent hardware probe, first list IDs, then pass a master ID or a master/cue pair: + +```sh +cargo run -p clubcraft-engine --example output_probe -j 4 +cargo run -p clubcraft-engine --example output_probe -j 4 -- "master-id" +cargo run -p clubcraft-engine --example output_probe -j 4 -- "master-id" "cue-id" +``` + +The probe sets both output gains to their minimum before starting streams, +loads no tracks, checks that +both callbacks run, rejects a missing device and reopens the pair while checking +that core settings survive. + +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.