From c03ab47072a34fad394f57493ceb5b9fdfa6b54c Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Tue, 3 Nov 2026 17:47:13 +0300 Subject: [PATCH 1/3] Audio: support separate master and headphone output devices --- crates/app/src/app.rs | 10 + crates/app/src/live/adapter.rs | 17 +- crates/app/src/settings.rs | 114 ++++- crates/engine/examples/output_probe.rs | 53 ++ crates/engine/src/engine.rs | 682 +++++++++++++++++++++---- crates/engine/src/lib.rs | 3 +- crates/engine/src/output.rs | 498 ++++++++++++++++++ crates/engine/src/sys.rs | 13 +- crates/engine/tests/engine.rs | 16 +- docs/ARCHITECTURE.md | 3 + docs/audio-output.md | 90 ++++ 11 files changed, 1358 insertions(+), 141 deletions(-) create mode 100644 crates/engine/examples/output_probe.rs create mode 100644 crates/engine/src/output.rs create mode 100644 docs/audio-output.md diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index 8926996..81c6f1f 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(h) = &app.eng.handle { app.settings.sync_audio(h.audio_config()); } 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 let Some(h) = &self.eng.handle { + self.settings.sync_audio(h.audio_config()); + 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..3a5af6f 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -390,8 +390,11 @@ pub struct LiveEngine { 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), + let (handle, error) = match Engine::start(config) { + Ok(h) => { + let warning = h.stream_info().warning; + (Some(h), warning) + } Err(e) => (None, Some(format!("Audio output unavailable: {e:#}"))), }; if let Some(h) = &handle { @@ -897,7 +900,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..8392191 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(|| "automatic estimate unavailable; manual correction only".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, "Driver timing is an estimate. Aligning slower headphones adds master latency; 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..96e0f29 --- /dev/null +++ b/crates/engine/examples/output_probe.rs @@ -0,0 +1,53 @@ +//! Silent hardware probe. Run with no arguments to enumerate output IDs; pass +//! master and cue IDs to exercise both devices 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 engine = Engine::start(AudioConfig { + device: Some(args[0].clone()), + headphone_device: Some(args[1].clone()), + headphones: HeadphoneRouting::SeparateDevice, + ..AudioConfig::default() + })?; + engine.send(Command::SetMasterGain(-60.0))?; + engine.send(Command::SetHeadphoneGain(-60.0))?; + std::thread::sleep(Duration::from_secs(3)); + let info = engine.stream_info(); + println!("{info:#?}"); + if 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_none_or(|h| h.observed_buffer_frames.is_none()) + { + bail!("both 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(); + invalid.headphone_device = Some("clubcraft-nonexistent-output-probe".into()); + if engine.set_audio_config(invalid).is_ok() { + bail!("missing headphone 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() + || reopened.headphones.as_ref().is_none_or(|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!("Both silent output streams opened and reopened successfully."); + Ok(()) +} diff --git a/crates/engine/src/engine.rs b/crates/engine/src/engine.rs index 8d1e813..e7c0efd 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,36 @@ 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. + /// Required sample rate. `None` = common 44.1 kHz if supported, else common 48 kHz. 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 +86,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 +122,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 +130,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 +143,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 +174,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 +183,120 @@ 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 { + pub fn start(mut config: AudioConfig) -> 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); + 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 +309,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 +327,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 +385,128 @@ 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 (channels, sr) = choose_format(&ranges, cue_ranges.as_deref(), config, want_ch)?; + 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 master_ok = |c: &cpal::SupportedStreamConfigRange, sr| c.sample_format() == cpal::SampleFormat::F32 + && c.channels() >= want_ch && (cue_ranges.is_none() || c.channels() == 2) && c.contains_rate(sr) && supports_buffer(c, config.buffer_frames); let preferred: Vec = match config.sample_rate { - Some(r) => vec![r, 44100, 48000], + Some(r) => vec![r], 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 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| { + 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 |_| { + err_health.cue.errors.fetch_add(1, Ordering::Relaxed); + err_health.cue.failed.store(true, Ordering::Release); + 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); - } + 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 +518,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 +531,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 +552,92 @@ 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 |_: cpal::Error| { + health.master.errors.fetch_add(1, Ordering::Relaxed); + health.master.failed.store(true, Ordering::Release); 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 +653,35 @@ 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) { + 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 +695,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 +753,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 +796,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 +816,137 @@ 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 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..803a665 --- /dev/null +++ b/crates/engine/src/output.rs @@ -0,0 +1,498 @@ +//! 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; + +pub(crate) struct EndpointHealth { + pub frames: AtomicU32, + pub latency_us: AtomicU32, + pub errors: AtomicU32, + pub failed: AtomicBool, + 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), + created: Instant::now(), + last_callback_us: AtomicU64::new(0), + armed: AtomicBool::new(false), + } + } +} + +impl EndpointHealth { + 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)); + if self.armed.load(Ordering::Acquire) && age > (budget_us * 8).max(2_000_000) { + self.failed.store(true, Ordering::Release); + } + self.failed.load(Ordering::Acquire) + } +} + +#[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.last_callback_us.store(health.created.elapsed().as_micros() as u64, Ordering::Relaxed); + health.frames.store(frames as u32, Ordering::Relaxed); + 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. Changing the tap slews rather than clicks. +pub(crate) struct Delay { + frames: Vec<[f32; 2]>, + write: usize, + delay: f64, +} + +impl Delay { + pub fn new(sr: u32) -> Self { + Self { + frames: vec![[0.0; 2]; sr as usize * 2 + 2], + write: 0, + delay: 0.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); + self.delay += (target - self.delay).clamp(-0.25, 0.25); + self.frames[self.write] = frame; + let read = (self.write as f64 - self.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; + let out = std::array::from_fn(|i| self.frames[a][i] + (self.frames[b][i] - self.frames[a][i]) * t); + self.write = (self.write + 1) % self.frames.len(); + out + } +} + +/// 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 a = 1.0 - (-seconds / 2.0).exp(); + self.error += (error - self.error) * a; + self.integral = (self.integral + self.error * seconds * 0.0000001).clamp(-0.004, 0.004); + let want = (self.error * 0.000002 + self.integral).clamp(-0.005, 0.005); + self.ratio += (want - self.ratio) * a; + 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, +} + +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 { + 0.94 + } else { + (std::f64::consts::PI * x * 0.94).sin() / (std::f64::consts::PI * x) + }; + let w = 0.42 + 0.5 * (std::f64::consts::PI * x / 16.0).cos() + 0.08 * (2.0 * std::f64::consts::PI * x / 16.0).cos(); + (sinc * w) 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, + } + } + + 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.offset_ns = None; + 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.offset_ns = None; + 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 pf = self.phase * PHASES as f64; + let p = pf as usize; + let t = (pf - p as f64) as f32; + let mut sample = [0.0; 2]; + for k in 0..TAPS { + let h = self.history[(self.head + k) % TAPS]; + let c = self.kernel[p][k] + (self.kernel[p + 1][k] - self.kernel[p][k]) * t; + sample[0] += h.samples[0] * c; + sample[1] += h.samples[1] * c; + } + 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; + let a = 1.0 - (-(frames as f64 / self.sr as f64) / 1.0).exp(); + let filtered = self.offset_ns.map(|old| old + (offset - old) * a).unwrap_or(offset); + self.offset_ns = Some(filtered); + self.health.offset_us.store((filtered / 1000.0) as i32, Ordering::Relaxed); + let (m, c) = alignment(filtered, self.correction_ms, self.sr); + self.health.master_delay.store(m.round() as u32, Ordering::Relaxed); + self.health.cue_delay.store(c.round() as u32, Ordering::Relaxed); + } else { + self.offset_ns = None; + self.health.offset_us.store(i32::MIN, Ordering::Relaxed); + let (m, c) = alignment(0.0, self.correction_ms, self.sr); + self.health.master_delay.store(m.round() as u32, Ordering::Relaxed); + self.health.cue_delay.store(c.round() as u32, Ordering::Relaxed); + } + 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); + } + } +} + +#[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)); + } + + #[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)); + 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_eq!(health.master_delay.load(Ordering::Relaxed), 0); + assert_eq!(health.cue_delay.load(Ordering::Relaxed), 480); + } + + #[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..d20f954 --- /dev/null +++ b/docs/audio-output.md @@ -0,0 +1,90 @@ +# 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. + +## 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 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; the earlier output receives a fractional delay, with a slewing delay tap +to avoid discontinuities. Added delay is bounded to two seconds per output. + +**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 and only the manual +correction is applied. 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. + +## 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. + +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/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" "cue-id" +``` + +The probe loads no tracks, sets both output gains to their minimum, 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. From 29503711eb2598678c3a78c43dc10809ca969ee9 Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Wed, 4 Nov 2026 13:24:17 +0300 Subject: [PATCH 2/3] Audio: recover transient output errors and restore single-device fallbacks --- crates/app/src/live/adapter.rs | 64 ++++++- crates/app/src/settings.rs | 2 +- crates/engine/examples/output_probe.rs | 36 ++-- crates/engine/src/engine.rs | 64 +++++-- crates/engine/src/output.rs | 246 +++++++++++++++++++++---- docs/audio-output.md | 35 +++- 6 files changed, 373 insertions(+), 74 deletions(-) diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index 3a5af6f..4524788 100644 --- a/crates/app/src/live/adapter.rs +++ b/crates/app/src/live/adapter.rs @@ -387,12 +387,70 @@ 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. +fn start_audio(config: AudioConfig, mut open: impl FnMut(AudioConfig) -> anyhow::Result) -> anyhow::Result<(T, Option)> { + let separate = config.headphones == clubcraft_engine::HeadphoneRouting::SeparateDevice; + open(config).map(|handle| (handle, None)).or_else(|error| { + if separate { return Err(error); } + log::warn!("Saved audio setup unavailable; trying system default: {error:#}"); + open(AudioConfig::default()).map(|handle| (handle, Some(format!("Saved audio setup unavailable; using system default: {error:#}")))) + .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 ((), warning) = 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!(warning.unwrap().contains("using system default")); + } + } + + #[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 ((), warning) = start_audio(config.clone(), |_| { attempts += 1; Ok(()) }).unwrap(); + assert_eq!(attempts, 1); + assert!(warning.is_none()); + let failure = start_audio::<()>(config, |_| anyhow::bail!("device missing")).unwrap_err(); + 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) { - Ok(h) => { - let warning = h.stream_info().warning; + let started = start_audio(config, Engine::start); + let (handle, error) = match started { + Ok((h, fallback_warning)) => { + let warning = fallback_warning.or_else(|| h.stream_info().warning); (Some(h), warning) } Err(e) => (None, Some(format!("Audio output unavailable: {e:#}"))), diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index 8392191..f96c1f7 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -329,7 +329,7 @@ impl Settings { } if i.headphones.is_some() { let estimate = i.estimated_offset_ms.map(|v| format!("estimated cue lag {v:.1} ms")) - .unwrap_or_else(|| "automatic estimate unavailable; manual correction only".into()); + .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, "Driver timing is an estimate. Aligning slower headphones adds master latency; verify by listening and adjust the correction."); diff --git a/crates/engine/examples/output_probe.rs b/crates/engine/examples/output_probe.rs index 96e0f29..83963b5 100644 --- a/crates/engine/examples/output_probe.rs +++ b/crates/engine/examples/output_probe.rs @@ -1,5 +1,5 @@ //! Silent hardware probe. Run with no arguments to enumerate output IDs; pass -//! master and cue IDs to exercise both devices without loading or playing tracks. +//! 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; @@ -12,42 +12,46 @@ fn main() -> Result<()> { } return Ok(()); } - if args.len() != 2 { - bail!("usage: output_probe [master-device-id cue-device-id]"); + if args.len() > 2 { + bail!("usage: output_probe [master-device-id [cue-device-id]]"); } - let engine = Engine::start(AudioConfig { + let separate = args.len() == 2; + let engine = Engine::start_with_commands(AudioConfig { device: Some(args[0].clone()), - headphone_device: Some(args[1].clone()), - headphones: HeadphoneRouting::SeparateDevice, + headphone_device: args.get(1).cloned(), + headphones: if separate { HeadphoneRouting::SeparateDevice } else { HeadphoneRouting::Off }, ..AudioConfig::default() - })?; - engine.send(Command::SetMasterGain(-60.0))?; - engine.send(Command::SetHeadphoneGain(-60.0))?; + }, [Command::SetMasterGain(-60.0), Command::SetHeadphoneGain(-60.0)])?; std::thread::sleep(Duration::from_secs(3)); let info = engine.stream_info(); println!("{info:#?}"); - if info.headphones.is_none() + 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_none_or(|h| h.observed_buffer_frames.is_none()) + || info.headphones.as_ref().is_some_and(|h| h.observed_buffer_frames.is_none()) { - bail!("both output streams must be running (see diagnostics above)"); + 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(); - invalid.headphone_device = Some("clubcraft-nonexistent-output-probe".into()); + 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 headphone device was unexpectedly accepted"); + 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() - || reopened.headphones.as_ref().is_none_or(|h| h.failed || h.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!("Both silent output streams opened and reopened successfully."); + 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 e7c0efd..a03caea 100644 --- a/crates/engine/src/engine.rs +++ b/crates/engine/src/engine.rs @@ -43,7 +43,8 @@ pub enum HeadphoneRouting { pub struct AudioConfig { /// Output device ID (legacy names are accepted); `None` = system default. pub device: Option, - /// Required sample rate. `None` = common 44.1 kHz if supported, else common 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, @@ -260,7 +261,13 @@ pub struct Engine; impl Engine { /// Open the output device and start the engine. - pub fn start(mut config: AudioConfig) -> Result { + 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), @@ -281,6 +288,7 @@ impl Engine { 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()); @@ -406,15 +414,26 @@ fn prepare(config: &AudioConfig) -> Result { Some(cue) } else { None }; let cue_ranges = cue_device.as_ref().map(|d| d.supported_output_configs().map(|r| r.collect::>())).transpose()?; - let (channels, sr) = choose_format(&ranges, cue_ranges.as_deref(), config, want_ch)?; + 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 && (cue_ranges.is_none() || c.channels() == 2) && c.contains_rate(sr) && supports_buffer(c, config.buffer_frames); + && 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) => vec![r], + Some(r) if strict => vec![r], + Some(r) => vec![r, 44100, 48000], None => vec![44100, 48000], }; let chosen = preferred @@ -429,6 +448,13 @@ fn choose_format(ranges: &[cpal::SupportedStreamConfigRange], cue_ranges: Option 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 @@ -480,13 +506,13 @@ fn open_stream( 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 |_| { - err_health.cue.errors.fetch_add(1, Ordering::Relaxed); - err_health.cue.failed.store(true, Ordering::Release); + 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) @@ -502,6 +528,7 @@ fn open_stream( let data_cb = move |data: &mut [f32], callback: &cpal::OutputCallbackInfo| { let t0 = Instant::now(); let faults0 = major_faults(); + master_health.master.heartbeat(data.len() / ch); if stopped.load(Ordering::Acquire) || master_health.master.failed.load(Ordering::Acquire) { data.fill(0.0); return; @@ -594,9 +621,8 @@ fn open_stream( side.core.stream_errors = err2.load(Ordering::Relaxed); }; let opening_health = health.clone(); - let err_cb = move |_: cpal::Error| { - health.master.errors.fetch_add(1, Ordering::Relaxed); - health.master.failed.store(true, Ordering::Release); + let err_cb = move |error: cpal::Error| { + health.master.report_error(error.kind()); errors.fetch_add(1, Ordering::Relaxed); }; let stream = device @@ -662,6 +688,7 @@ impl EngineHandle { 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); @@ -887,6 +914,21 @@ mod tests { 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, diff --git a/crates/engine/src/output.rs b/crates/engine/src/output.rs index 803a665..d1cb39f 100644 --- a/crates/engine/src/output.rs +++ b/crates/engine/src/output.rs @@ -7,12 +7,40 @@ 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; +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, @@ -25,6 +53,7 @@ impl Default for EndpointHealth { 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), @@ -33,6 +62,41 @@ impl Default for EndpointHealth { } 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); @@ -41,10 +105,9 @@ impl EndpointHealth { 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)); - if self.armed.load(Ordering::Acquire) && age > (budget_us * 8).max(2_000_000) { - self.failed.store(true, Ordering::Release); - } - self.failed.load(Ordering::Acquire) + // 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)) } } @@ -62,8 +125,7 @@ pub(crate) struct OutputHealth { /// Zero means unavailable, including backends which supply zero timestamps. pub(crate) fn observe(info: &cpal::OutputCallbackInfo, frames: usize, health: &EndpointHealth) -> Option { - health.last_callback_us.store(health.created.elapsed().as_micros() as u64, Ordering::Relaxed); - health.frames.store(frames as u32, Ordering::Relaxed); + health.heartbeat(frames); let t = info.timestamp(); let us = t .playback @@ -82,11 +144,14 @@ pub(crate) struct CueFrame { pub master_ns: u64, } -/// A bounded fractional stereo delay. Changing the tap slews rather than clicks. +/// 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 { @@ -95,22 +160,35 @@ impl Delay { 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); - self.delay += (target - self.delay).clamp(-0.25, 0.25); + if target != self.delay { + self.previous = self.delay; + self.delay = target; + self.fade = 0.0; + } self.frames[self.write] = frame; - let read = (self.write as f64 - self.delay).rem_euclid(self.frames.len() as f64); + 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; - let out = std::array::from_fn(|i| self.frames[a][i] + (self.frames[b][i] - self.frames[a][i]) * t); - self.write = (self.write + 1) % self.frames.len(); - out + std::array::from_fn(|i| self.frames[a][i] + (self.frames[b][i] - self.frames[a][i]) * t) } } @@ -124,11 +202,11 @@ struct ClockServo { impl ClockServo { fn update(&mut self, error: f64, seconds: f64) -> f64 { - let a = 1.0 - (-seconds / 2.0).exp(); - self.error += (error - self.error) * a; - self.integral = (self.integral + self.error * seconds * 0.0000001).clamp(-0.004, 0.004); - let want = (self.error * 0.000002 + self.integral).clamp(-0.005, 0.005); - self.ratio += (want - self.ratio) * a; + 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 } } @@ -154,6 +232,7 @@ pub(crate) struct CueOutput { last: [f32; 2], delay: Delay, offset_ns: Option, + alignment_set: bool, } impl CueOutput { @@ -164,12 +243,14 @@ impl CueOutput { 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 { - 0.94 + SINC_CUTOFF } else { - (std::f64::consts::PI * x * 0.94).sin() / (std::f64::consts::PI * x) + (std::f64::consts::PI * x * SINC_CUTOFF).sin() / (std::f64::consts::PI * x) }; - let w = 0.42 + 0.5 * (std::f64::consts::PI * x / 16.0).cos() + 0.08 * (2.0 * std::f64::consts::PI * x / 16.0).cos(); - (sinc * w) as f32 + // 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 { @@ -194,6 +275,7 @@ impl CueOutput { last: [0.0; 2], delay: Delay::new(sr), offset_ns: None, + alignment_set: false, } } @@ -255,15 +337,15 @@ impl CueOutput { } } if self.started { - let pf = self.phase * PHASES as f64; - let p = pf as usize; - let t = (pf - p as f64) as f32; + 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 h = self.history[(self.head + k) % TAPS]; - let c = self.kernel[p][k] + (self.kernel[p + 1][k] - self.kernel[p][k]) * t; - sample[0] += h.samples[0] * c; - sample[1] += h.samples[1] * c; + 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]; @@ -273,15 +355,15 @@ impl CueOutput { let filtered = self.offset_ns.map(|old| old + (offset - old) * a).unwrap_or(offset); self.offset_ns = Some(filtered); self.health.offset_us.store((filtered / 1000.0) as i32, Ordering::Relaxed); - let (m, c) = alignment(filtered, self.correction_ms, self.sr); - self.health.master_delay.store(m.round() as u32, Ordering::Relaxed); - self.health.cue_delay.store(c.round() as u32, Ordering::Relaxed); + self.set_alignment(filtered); } else { self.offset_ns = None; self.health.offset_us.store(i32::MIN, Ordering::Relaxed); - let (m, c) = alignment(0.0, self.correction_ms, self.sr); - self.health.master_delay.store(m.round() as u32, Ordering::Relaxed); - self.health.cue_delay.store(c.round() as u32, Ordering::Relaxed); + // 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); } measured = true; } @@ -294,6 +376,18 @@ impl CueOutput { *out = delayed.map(|s| s * self.gain); } } + + fn set_alignment(&mut self, offset_ns: f64) { + // Latch once per opened stream. 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 { + let (master, cue) = alignment(offset_ns, 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)] @@ -312,6 +406,84 @@ mod tests { ..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); + 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); + 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 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] @@ -407,8 +579,10 @@ mod tests { 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_eq!(health.master_delay.load(Ordering::Relaxed), 0); - assert_eq!(health.cue_delay.load(Ordering::Relaxed), 480); + // 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] diff --git a/docs/audio-output.md b/docs/audio-output.md index d20f954..6248b97 100644 --- a/docs/audio-output.md +++ b/docs/audio-output.md @@ -6,6 +6,10 @@ Changes are staged until **Apply**; **Discard changes** restores the last applie 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. ## Two devices @@ -22,7 +26,7 @@ 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 is never replaced by the system default. If headphones cannot open at +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 @@ -36,19 +40,29 @@ 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; the earlier output receives a fractional delay, with a slewing delay tap -to avoid discontinuities. Added delay is bounded to two seconds per output. +smoothed for diagnostics. The first usable estimate sets fixed output delays for +the lifetime of the opened streams. Queue jitter and rebuffering never move the +master delay; continuous drift correction happens only in the cue resampler. +Apply recalibrates the delay, 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 and only the manual -correction is applied. Driver estimates do not measure the entire analog or +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 @@ -56,6 +70,11 @@ 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 @@ -73,14 +92,16 @@ 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/cue pair: +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 loads no tracks, sets both output gains to their minimum, checks that +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. From e696117399c7d02bfc049b2950da93e414eed926 Mon Sep 17 00:00:00 2001 From: tuzhibaevta Date: Wed, 4 Nov 2026 17:42:08 +0300 Subject: [PATCH 3/3] Audio: preserve saved setup on fallback and settle alignment before locking --- crates/app/src/app.rs | 6 +- crates/app/src/live/adapter.rs | 75 +++++++++++++++++++---- crates/app/src/settings.rs | 2 +- crates/engine/src/output.rs | 109 ++++++++++++++++++++++++++++----- docs/audio-output.md | 17 +++-- 5 files changed, 171 insertions(+), 38 deletions(-) diff --git a/crates/app/src/app.rs b/crates/app/src/app.rs index 81c6f1f..83a970b 100644 --- a/crates/app/src/app.rs +++ b/crates/app/src/app.rs @@ -189,7 +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(h) = &app.eng.handle { app.settings.sync_audio(h.audio_config()); } + 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(); @@ -1439,8 +1439,8 @@ impl eframe::App for App { 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 let Some(h) = &self.eng.handle { - self.settings.sync_audio(h.audio_config()); + 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; } diff --git a/crates/app/src/live/adapter.rs b/crates/app/src/live/adapter.rs index 4524788..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, @@ -389,12 +392,26 @@ pub struct LiveEngine { // Keep the legacy startup recovery for one-device setups. SeparateDevice must // never substitute the selected master or reroute cue onto the system speakers. -fn start_audio(config: AudioConfig, mut open: impl FnMut(AudioConfig) -> anyhow::Result) -> anyhow::Result<(T, Option)> { +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| (handle, None)).or_else(|error| { + 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| (handle, Some(format!("Saved audio setup unavailable; using 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:#}"))) }) } @@ -410,14 +427,43 @@ mod audio_start_tests { 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 ((), warning) = start_audio(config.clone(), |candidate| { + 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!(warning.unwrap().contains("using system 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] @@ -436,10 +482,11 @@ mod audio_start_tests { fn working_setup_is_not_reopened_and_double_failure_is_reported() { let config = AudioConfig::default(); let mut attempts = 0; - let ((), warning) = start_audio(config.clone(), |_| { attempts += 1; Ok(()) }).unwrap(); + let started = start_audio(config.clone(), |_| { attempts += 1; Ok(()) }).unwrap(); assert_eq!(attempts, 1); - assert!(warning.is_none()); - let failure = start_audio::<()>(config, |_| anyhow::bail!("device missing")).unwrap_err(); + 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")); } } @@ -448,12 +495,13 @@ impl LiveEngine { pub fn start(config: AudioConfig) -> LiveEngine { let (tx, rx) = unbounded(); let started = start_audio(config, Engine::start); - let (handle, error) = match started { - Ok((h, fallback_warning)) => { - let warning = fallback_warning.or_else(|| h.stream_info().warning); - (Some(h), warning) + 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:#}"))), + Err(e) => (None, Some(format!("Audio output unavailable: {e:#}")), None), }; if let Some(h) = &handle { let _ = h.send(Command::SetAutoGain(true)); @@ -466,6 +514,7 @@ impl LiveEngine { LiveEngine { handle, error, + startup_audio_config, cache, sep: Arc::new(LiveSeparator::new()), tx, diff --git a/crates/app/src/settings.rs b/crates/app/src/settings.rs index f96c1f7..4eefc25 100644 --- a/crates/app/src/settings.rs +++ b/crates/app/src/settings.rs @@ -332,7 +332,7 @@ impl Settings { .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, "Driver timing is an estimate. Aligning slower headphones adds master latency; verify by listening and adjust the correction."); + 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); } } diff --git a/crates/engine/src/output.rs b/crates/engine/src/output.rs index d1cb39f..9ccc751 100644 --- a/crates/engine/src/output.rs +++ b/crates/engine/src/output.rs @@ -18,6 +18,9 @@ const SERVO_INTEGRAL: f64 = 1e-7; 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, @@ -232,6 +235,8 @@ pub(crate) struct CueOutput { last: [f32; 2], delay: Delay, offset_ns: Option, + estimate_frames: u64, + estimate_has_timestamps: Option, alignment_set: bool, } @@ -275,6 +280,8 @@ impl CueOutput { last: [0.0; 2], delay: Delay::new(sr), offset_ns: None, + estimate_frames: 0, + estimate_has_timestamps: None, alignment_set: false, } } @@ -303,7 +310,7 @@ impl CueOutput { self.health.overflows.fetch_add(1, Ordering::Relaxed); } self.started = false; - self.offset_ns = None; + self.reset_estimate(); while self.input.slots() > target + frames + TAPS { let _ = self.input.pop(); } @@ -315,7 +322,7 @@ impl CueOutput { self.head = 0; self.phase = 0.0; self.servo = ClockServo::default(); - self.offset_ns = None; + self.reset_estimate(); self.started = true; } let ratio = self @@ -351,19 +358,13 @@ impl CueOutput { 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; - let a = 1.0 - (-(frames as f64 / self.sr as f64) / 1.0).exp(); - let filtered = self.offset_ns.map(|old| old + (offset - old) * a).unwrap_or(offset); - self.offset_ns = Some(filtered); - self.health.offset_us.store((filtered / 1000.0) as i32, Ordering::Relaxed); - self.set_alignment(filtered); + self.set_alignment(offset, frames, true); } else { - self.offset_ns = None; - self.health.offset_us.store(i32::MIN, Ordering::Relaxed); // 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); + self.set_alignment(queued * 1e9 / self.sr as f64, frames, false); } measured = true; } @@ -377,12 +378,35 @@ impl CueOutput { } } - fn set_alignment(&mut self, offset_ns: f64) { - // Latch once per opened stream. Queue jitter and rebuffering must never + 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 { - let (master, cue) = alignment(offset_ns, self.correction_ms, self.sr); + 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; @@ -458,17 +482,59 @@ mod tests { 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); + 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); + 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); @@ -551,6 +617,12 @@ mod tests { .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; @@ -579,6 +651,11 @@ mod tests { 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); diff --git a/docs/audio-output.md b/docs/audio-output.md index 6248b97..5976119 100644 --- a/docs/audio-output.md +++ b/docs/audio-output.md @@ -9,7 +9,10 @@ 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. +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 @@ -40,10 +43,14 @@ 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 for diagnostics. The first usable estimate sets fixed output delays for -the lifetime of the opened streams. Queue jitter and rebuffering never move the -master delay; continuous drift correction happens only in the cue resampler. -Apply recalibrates the delay, including after a correction change. A tap change +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