Skip to content

armgit / Handy

Public Imported from GitHub
0

A free, open source, and extensible speech-to-text application that works completely offline.

make microphone callback real-time safe (#1954)

CJ Paisd54c88eb35ab
diff --git a/src-tauri/Cargo.lock b/src-tauri/Cargo.lock
index 49848534..8839379d 100644
--- a/src-tauri/Cargo.lock
+++ b/src-tauri/Cargo.lock
@@ -2531,6 +2531,7 @@ dependencies = [
"regex",
"reqwest 0.12.28",
"rodio",
+ "rtrb",
"rubato",
"rusqlite",
"rusqlite_migration",
@@ -5243,6 +5244,12 @@ dependencies = [
"symphonia",
]
+[[package]]
+name = "rtrb"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9278fb35b3e730abe136e9b395b5b81b96d06b9f5478a50f0c8430a2237b22de"
+
[[package]]
name = "rubato"
version = "0.16.2"
diff --git a/src-tauri/Cargo.toml b/src-tauri/Cargo.toml
index 2afba25c..81589ee2 100644
--- a/src-tauri/Cargo.toml
+++ b/src-tauri/Cargo.toml
@@ -49,6 +49,7 @@ serde = { version = "1", features = ["derive"] }
serde_json = "1"
rdev = { git = "https://github.com/rustdesk-org/rdev" }
cpal = "0.16.0"
+rtrb = "0.4.0"
anyhow = "1.0.95"
rubato = "0.16.2"
hound = "3.5.1"
diff --git a/src-tauri/src/audio_toolkit/audio/recorder.rs b/src-tauri/src/audio_toolkit/audio/recorder.rs
index 57bcc915..e7c848bc 100644
--- a/src-tauri/src/audio_toolkit/audio/recorder.rs
+++ b/src-tauri/src/audio_toolkit/audio/recorder.rs
@@ -1,7 +1,7 @@
use std::{
io::Error,
sync::{
- atomic::{AtomicBool, Ordering},
+ atomic::{AtomicBool, AtomicU64, Ordering},
mpsc, Arc, Mutex,
},
time::{Duration, Instant},
@@ -11,6 +11,7 @@ use cpal::{
traits::{DeviceTrait, HostTrait, StreamTrait},
Device, Sample, SizedSample,
};
+use rtrb::{Consumer, Producer, RingBuffer};
use crate::audio_toolkit::{
audio::{AudioVisualiser, FrameResampler},
@@ -21,16 +22,28 @@ use crate::audio_toolkit::{
enum Cmd {
/// Begin capturing. Carries the send timestamp so the consumer can log how
- /// long the command sat in the channel, plus a one-shot acknowledgement
- /// sent only after the first microphone sample chunk is processed.
+ /// long the command sat in the channel, plus a one-shot first-sample acknowledgement.
Start(VadPolicy, Instant, mpsc::Sender<()>),
Stop(mpsc::Sender<Vec<f32>>),
Shutdown,
}
-enum AudioChunk {
- Samples(Vec<f32>),
- EndOfStream,
+// Two seconds of ring capacity absorbs consumer stalls without adding latency
+// during normal 10 ms drains.
+const AUDIO_RING_SECONDS: usize = 2;
+const CONSUMER_POLL_INTERVAL: Duration = Duration::from_millis(10);
+const MAX_DRAIN_CHUNK: Duration = Duration::from_millis(50);
+const PAUSE_ACK_TIMEOUT: Duration = Duration::from_secs(2);
+
+/// Atomics shared by the callback and consumer; audio uses a wait-free SPSC ring.
+/// The callback must remain allocation-, lock-, logging-, and blocking-free.
+#[derive(Default)]
+struct CaptureTransportState {
+ pause_requested: AtomicBool,
+ /// Set after forwarding a pause's boundary block; subsequent callbacks
+ /// remain silent until the consumer clears the request.
+ pause_acknowledged: AtomicBool,
+ overrun_samples: AtomicU64,
}
/// How 16 kHz mono frames should be filtered for one recording session.
@@ -70,13 +83,14 @@ impl VadConfig {
/// Callback invoked with each 16 kHz mono frame that passes the active capture
/// policy while recording. Used to feed a live streaming transcription as audio arrives.
pub type AudioFrameCallback = Arc<dyn Fn(&[f32]) + Send + Sync + 'static>;
+pub type LevelCallback = Arc<dyn Fn(Vec<f32>) + Send + Sync + 'static>;
pub struct AudioRecorder {
device: Option<Device>,
cmd_tx: Option<mpsc::Sender<Cmd>>,
worker_handle: Option<std::thread::JoinHandle<()>>,
vad: Option<VadConfig>,
- level_cb: Option<Arc<dyn Fn(Vec<f32>) + Send + Sync + 'static>>,
+ level_cb: Option<LevelCallback>,
audio_cb: Option<AudioFrameCallback>,
/// Which input channel to use. None = average all (original behavior).
selected_channel: Option<usize>,
@@ -161,12 +175,11 @@ impl AudioRecorder {
return Ok(()); // already open
}
log::warn!("Capture stream failed; rebuilding microphone stream");
- let _ = self.close();
+ self.close()?;
}
self.stream_error.store(false, Ordering::Relaxed);
- let (sample_tx, sample_rx) = mpsc::channel::<AudioChunk>();
let (cmd_tx, cmd_rx) = mpsc::channel::<Cmd>();
let (init_tx, init_rx) = mpsc::sync_channel::<Result<(), String>>(1);
@@ -189,9 +202,8 @@ impl AudioRecorder {
let stream_error = Arc::clone(&self.stream_error);
let worker = std::thread::spawn(move || {
- let stop_flag = Arc::new(AtomicBool::new(false));
- let stop_flag_for_stream = stop_flag.clone();
- let init_result = (|| -> Result<(cpal::Stream, u32), String> {
+ let transport = Arc::new(CaptureTransportState::default());
+ let init_result = (|| -> Result<(cpal::Stream, u32, Consumer<f32>), String> {
let config_started = Instant::now();
let device_name = thread_device.name().unwrap_or_default();
let cached_config = config_cache
@@ -234,61 +246,52 @@ impl AudioRecorder {
}
let build_started = Instant::now();
- let stream = match config.sample_format() {
+ let (stream, sample_consumer) = match config.sample_format() {
cpal::SampleFormat::U8 => AudioRecorder::build_stream::<u8>(
&thread_device,
&config,
- sample_tx,
channels,
selected_channel,
- stop_flag_for_stream,
+ Arc::clone(&transport),
Arc::clone(&stream_error),
- )
- .map_err(|e| format!("Failed to build input stream: {e}"))?,
+ ),
cpal::SampleFormat::I8 => AudioRecorder::build_stream::<i8>(
&thread_device,
&config,
- sample_tx,
channels,
selected_channel,
- stop_flag_for_stream,
+ Arc::clone(&transport),
Arc::clone(&stream_error),
- )
- .map_err(|e| format!("Failed to build input stream: {e}"))?,
+ ),
cpal::SampleFormat::I16 => AudioRecorder::build_stream::<i16>(
&thread_device,
&config,
- sample_tx,
channels,
selected_channel,
- stop_flag_for_stream,
+ Arc::clone(&transport),
Arc::clone(&stream_error),
- )
- .map_err(|e| format!("Failed to build input stream: {e}"))?,
+ ),
cpal::SampleFormat::I32 => AudioRecorder::build_stream::<i32>(
&thread_device,
&config,
- sample_tx,
channels,
selected_channel,
- stop_flag_for_stream,
+ Arc::clone(&transport),
Arc::clone(&stream_error),
- )
- .map_err(|e| format!("Failed to build input stream: {e}"))?,
+ ),
cpal::SampleFormat::F32 => AudioRecorder::build_stream::<f32>(
&thread_device,
&config,
- sample_tx,
channels,
selected_channel,
- stop_flag_for_stream,
+ Arc::clone(&transport),
Arc::clone(&stream_error),
- )
- .map_err(|e| format!("Failed to build input stream: {e}"))?,
+ ),
sample_format => {
return Err(format!("Unsupported sample format: {sample_format:?}"));
}
- };
+ }
+ .map_err(|e| format!("Failed to build input stream: {e}"))?;
let build_elapsed = build_started.elapsed();
let play_started = Instant::now();
@@ -309,26 +312,29 @@ impl AudioRecorder {
*config_cache.lock().unwrap() = Some((device_name, config));
}
- Ok((stream, sample_rate))
+ Ok((stream, sample_rate, sample_consumer))
})();
match init_result {
- Ok((stream, sample_rate)) => {
+ Ok((stream, sample_rate, sample_consumer)) => {
let _ = init_tx.send(Ok(()));
// Timestamp for the play()-returned -> first-samples gap the
// init handshake can't see (hardware dependent).
let stream_running_at = Instant::now();
- // Keep the stream alive while we process samples.
- run_consumer(
+ let processor = CaptureProcessor::new(
sample_rate,
vad,
- sample_rx,
- cmd_rx,
level_cb,
audio_cb,
- stop_flag,
stream_running_at,
);
+ run_consumer(
+ processor,
+ sample_consumer,
+ cmd_rx,
+ transport,
+ Arc::clone(&stream_error),
+ );
drop(stream);
}
Err(error_message) => {
@@ -385,11 +391,13 @@ impl AudioRecorder {
}
pub fn stop(&self) -> Result<Vec<f32>, Box<dyn std::error::Error>> {
+ let tx = self
+ .cmd_tx
+ .as_ref()
+ .ok_or_else(|| Error::other("Recorder is not open"))?;
let (resp_tx, resp_rx) = mpsc::channel();
- if let Some(tx) = &self.cmd_tx {
- tx.send(Cmd::Stop(resp_tx))?;
- }
- Ok(resp_rx.recv()?) // wait for the samples
+ tx.send(Cmd::Stop(resp_tx))?;
+ Ok(resp_rx.recv()?)
}
/// True when the active capture stream must be rebuilt.
@@ -408,8 +416,8 @@ impl AudioRecorder {
if let Some(tx) = self.cmd_tx.take() {
let _ = tx.send(Cmd::Shutdown);
}
- if let Some(h) = self.worker_handle.take() {
- let _ = h.join();
+ if let Some(handle) = self.worker_handle.take() {
+ let _ = handle.join();
}
self.device = None;
Ok(())
@@ -418,47 +426,124 @@ impl AudioRecorder {
fn build_stream<T>(
device: &cpal::Device,
config: &cpal::SupportedStreamConfig,
- sample_tx: mpsc::Sender<AudioChunk>,
channels: usize,
selected_channel: Option<usize>,
- stop_flag: Arc<AtomicBool>,
+ transport: Arc<CaptureTransportState>,
stream_error: Arc<AtomicBool>,
- ) -> Result<cpal::Stream, cpal::BuildStreamError>
+ ) -> Result<(cpal::Stream, Consumer<f32>), cpal::BuildStreamError>
where
- T: Sample + SizedSample + Send + 'static,
+ T: Sample + SizedSample + Copy + Send + 'static,
f32: cpal::FromSample<T>,
{
- let mut output_buffer = Vec::new();
- let mut eos_sent = false;
+ let ring_capacity = config.sample_rate().0 as usize * AUDIO_RING_SECONDS;
+ let (mut sample_producer, mut sample_consumer) = RingBuffer::new(ring_capacity);
+
+ // Touch rtrb's uninitialized pages before the stream starts to reduce
+ // callback page faults. This does not pin them.
+ {
+ let chunk = sample_producer
+ .write_chunk(ring_capacity)
+ .expect("new audio ring has its full capacity available");
+ chunk.commit_all();
+ }
+ {
+ let chunk = sample_consumer
+ .read_chunk(ring_capacity)
+ .expect("pre-filled audio ring is readable");
+ chunk.commit_all();
+ }
+
// Resolve the effective channel to use. If the selected channel is
// out of range for this device, fall back to averaging all channels.
- let use_channel: Option<usize> = match selected_channel {
- Some(ch) if ch < channels => Some(ch),
- Some(_) => None, // out of range, fall back to average
- None => None, // user chose "average all"
- };
-
+ let use_channel = selected_channel.filter(|&channel| channel < channels);
+ let callback_transport = Arc::clone(&transport);
let stream_cb = move |data: &[T], _: &cpal::InputCallbackInfo| {
- handle_input_block(
+ Self::write_input_to_ring(
data,
channels,
use_channel,
- &stop_flag,
- &mut eos_sent,
- &mut output_buffer,
- &sample_tx,
+ &mut sample_producer,
+ &callback_transport,
);
};
- device.build_input_stream(
+ let stream = device.build_input_stream(
&config.clone().into(),
stream_cb,
- move |err| {
- log::error!("Stream error: {}", err);
- stream_error.store(true, Ordering::Relaxed);
+ move |_err| {
+ // Error callbacks may share the platform audio thread. Defer
+ // logging and recovery to the consumer/manager path.
+ stream_error.store(true, Ordering::Release);
},
None,
- )
+ )?;
+ Ok((stream, sample_consumer))
+ }
+
+ /// Real-time callback body. Keep this allocation-free, wait-free, and free
+ /// of locks, logging, clocks, and system calls.
+ fn write_input_to_ring<T>(
+ data: &[T],
+ channels: usize,
+ use_channel: Option<usize>,
+ producer: &mut Producer<f32>,
+ transport: &CaptureTransportState,
+ ) where
+ T: Sample + SizedSample + Copy,
+ f32: cpal::FromSample<T>,
+ {
+ // Forward the first block that observes a pause; once acknowledged,
+ // remain silent until the consumer resumes capture.
+ if transport.pause_requested.load(Ordering::Acquire)
+ && transport.pause_acknowledged.load(Ordering::Acquire)
+ {
+ return;
+ }
+
+ let frame_count = data.len() / channels;
+ let writable_frames = producer.slots().min(frame_count);
+ let written = if writable_frames == 0 {
+ 0
+ } else {
+ let chunk = producer
+ .write_chunk_uninit(writable_frames)
+ .expect("the producer just reported this many writable slots");
+ if channels == 1 {
+ chunk.fill_from_iter(
+ data.iter()
+ .take(writable_frames)
+ .map(|&sample| sample.to_sample::<f32>()),
+ )
+ } else if let Some(channel) = use_channel {
+ chunk.fill_from_iter(
+ data.chunks_exact(channels)
+ .take(writable_frames)
+ .map(|frame| frame[channel].to_sample::<f32>()),
+ )
+ } else {
+ chunk.fill_from_iter(data.chunks_exact(channels).take(writable_frames).map(
+ |frame| {
+ frame
+ .iter()
+ .map(|&sample| sample.to_sample::<f32>())
+ .sum::<f32>()
+ / channels as f32
+ },
+ ))
+ }
+ };
+ debug_assert_eq!(written, writable_frames);
+
+ let dropped = frame_count - written;
+ if dropped > 0 {
+ transport
+ .overrun_samples
+ .fetch_add(dropped as u64, Ordering::Relaxed);
+ }
+
+ // Publish the boundary write before acknowledging, including when the
+ // pause request arrives during the write.
+ acknowledge_pause_after_write(transport);
}
pub fn preferred_input_channel_count(
@@ -523,70 +608,9 @@ impl AudioRecorder {
}
}
-/// Body of the cpal input callback, extracted for testing without a device.
-/// Converts the block to mono and forwards it. The block that first observes
-/// the stop flag was captured before the stop, so it is still forwarded —
-/// dropping it loses up to a callback period of tail audio (worst on
-/// Bluetooth) — followed by the end-of-stream sentinel; later blocks are
-/// dropped until the flag clears.
-fn handle_input_block<T>(
- data: &[T],
- channels: usize,
- use_channel: Option<usize>,
- stop_flag: &AtomicBool,
- eos_sent: &mut bool,
- output_buffer: &mut Vec<f32>,
- sample_tx: &mpsc::Sender<AudioChunk>,
-) where
- T: Sample,
- f32: cpal::FromSample<T>,
-{
- let stopping = stop_flag.load(Ordering::Relaxed);
- if stopping && *eos_sent {
- return;
- }
-
- output_buffer.clear();
-
- if channels == 1 {
- output_buffer.extend(data.iter().map(|&sample| sample.to_sample::<f32>()));
- } else {
- let frame_count = data.len() / channels;
- output_buffer.reserve(frame_count);
-
- if let Some(ch) = use_channel {
- for frame in data.chunks_exact(channels) {
- let mono_sample = frame[ch].to_sample::<f32>();
- output_buffer.push(mono_sample);
- }
- } else {
- for frame in data.chunks_exact(channels) {
- let mono_sample = frame
- .iter()
- .map(|&sample| sample.to_sample::<f32>())
- .sum::<f32>()
- / channels as f32;
- output_buffer.push(mono_sample);
- }
- }
- }
-
- // A failed send means the consumer thread is gone. During shutdown that is
- // expected (the consumer exits before the stream is dropped), so only
- // report it when capture was supposed to be live.
- if sample_tx
- .send(AudioChunk::Samples(output_buffer.clone()))
- .is_err()
- && !stopping
- {
- log::error!("Failed to send samples");
- }
-
- if stopping {
- let _ = sample_tx.send(AudioChunk::EndOfStream);
- *eos_sent = true;
- } else {
- *eos_sent = false;
+fn acknowledge_pause_after_write(transport: &CaptureTransportState) {
+ if transport.pause_requested.load(Ordering::Acquire) {
+ transport.pause_acknowledged.store(true, Ordering::Release);
}
}
@@ -604,424 +628,419 @@ pub fn is_no_input_device_error(error_message: &str) -> bool {
&& normalized.contains("coreaudio"))
}
-#[cfg(test)]
-mod tests {
- use super::{
- handle_input_block, is_microphone_access_denied, is_no_input_device_error, run_consumer,
- AudioChunk, AudioRecorder, Cmd,
- };
- use std::{
- sync::{
- atomic::{AtomicBool, Ordering},
- mpsc, Arc,
- },
- thread,
- time::{Duration, Instant},
+/// Route one 16 kHz frame through VAD to recording and live outputs.
+/// Kept free-standing to permit disjoint borrows around resampler callbacks.
+fn handle_frame(
+ samples: &[f32],
+ vad_policy: VadPolicy,
+ vad: &Option<VadConfig>,
+ audio_cb: &Option<AudioFrameCallback>,
+ out_buf: &mut Vec<f32>,
+) {
+ let mut emit = |buf: &[f32]| {
+ out_buf.extend_from_slice(buf);
+ if let Some(cb) = audio_cb {
+ cb(buf);
+ }
};
- #[test]
- fn unopened_recorder_does_not_need_reopen() {
- // No worker has been spawned yet, so there is nothing to reap. Guards
- // against inverting the "no worker" case, which would make every first
- // open() take the rebuild path.
- let recorder = AudioRecorder::new().expect("recorder");
- assert!(!recorder.needs_reopen());
+ if vad_policy == VadPolicy::Disabled {
+ emit(samples);
+ return;
}
- #[test]
- fn stream_error_requires_reopen() {
- let recorder = AudioRecorder::new().expect("recorder");
- recorder.stream_error.store(true, Ordering::Relaxed);
- assert!(recorder.needs_reopen());
+ if let Some(cfg) = vad {
+ let mut detector = cfg.detector.lock().unwrap();
+ match detector
+ .push_frame(samples)
+ .unwrap_or(VadFrame::Speech(samples))
+ {
+ VadFrame::Speech(buf) => emit(buf),
+ VadFrame::Noise => {}
+ }
+ } else {
+ emit(samples);
}
+}
- #[test]
- fn shutdown_is_processed_without_audio_samples() {
- let (sample_tx, sample_rx) = mpsc::channel();
- let (cmd_tx, cmd_rx) = mpsc::channel();
- let (done_tx, done_rx) = mpsc::channel();
- let worker = thread::spawn(move || {
- run_consumer(
- 48_000,
- None,
- sample_rx,
- cmd_rx,
- None,
- None,
- Arc::new(AtomicBool::new(false)),
- Instant::now(),
- );
- let _ = done_tx.send(());
- });
-
- cmd_tx.send(Cmd::Shutdown).expect("send shutdown");
- let stopped = done_rx.recv_timeout(Duration::from_secs(1));
-
- // Unblock the old implementation so a failing test still exits cleanly.
- drop(sample_tx);
- worker.join().expect("join consumer");
- assert!(stopped.is_ok(), "shutdown waited for an audio sample");
+fn drain_available_samples(
+ consumer: &mut Consumer<f32>,
+ max_samples: usize,
+ mut process: impl FnMut(&[f32]),
+) -> usize {
+ let available = consumer.slots().min(max_samples);
+ if available == 0 {
+ return 0;
}
- #[test]
- fn boundary_block_forwarded_before_eos() {
- let (tx, rx) = mpsc::channel();
- let stop_flag = AtomicBool::new(false);
- let mut eos_sent = false;
- let mut scratch = Vec::new();
- let mut push = |flag: &AtomicBool, eos: &mut bool, block: &[f32]| {
- handle_input_block::<f32>(block, 1, None, flag, eos, &mut scratch, &tx)
- };
-
- // Running: blocks forwarded, no sentinel.
- push(&stop_flag, &mut eos_sent, &[0.1]);
- assert!(matches!(rx.try_recv(), Ok(AudioChunk::Samples(_))));
- assert!(rx.try_recv().is_err());
-
- // The block observing the stop flag is still forwarded, then EOS.
- stop_flag.store(true, Ordering::Relaxed);
- push(&stop_flag, &mut eos_sent, &[0.5, 0.5]);
- match rx.try_recv() {
- Ok(AudioChunk::Samples(samples)) => assert_eq!(samples, vec![0.5, 0.5]),
- _ => panic!("boundary block must be forwarded, not dropped"),
- }
- assert!(matches!(rx.try_recv(), Ok(AudioChunk::EndOfStream)));
-
- // Later blocks are dropped until the flag clears, then capture resumes.
- push(&stop_flag, &mut eos_sent, &[0.9]);
- assert!(rx.try_recv().is_err(), "blocks after EOS must be dropped");
- stop_flag.store(false, Ordering::Relaxed);
- push(&stop_flag, &mut eos_sent, &[0.2]);
- assert!(matches!(rx.try_recv(), Ok(AudioChunk::Samples(_))));
- assert!(rx.try_recv().is_err(), "no sentinel while running");
+ let chunk = consumer
+ .read_chunk(available)
+ .expect("reported audio ring slots must be readable");
+ let (first, second) = chunk.as_slices();
+ if !first.is_empty() {
+ process(first);
}
-
- #[test]
- fn detects_access_is_denied() {
- assert!(is_microphone_access_denied("Access is denied"));
+ if !second.is_empty() {
+ process(second);
}
+ chunk.commit_all();
+ available
+}
- #[test]
- fn detects_permission_denied() {
- assert!(is_microphone_access_denied("permission denied"));
- }
+/// What to do with a chunk drained from the ring.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+enum ChunkDisposition {
+ /// Process as active recording audio, including during the final stop drain.
+ Capture,
+ /// Consume idle audio without processing it.
+ Discard,
+}
- #[test]
- fn detects_windows_error_code() {
- assert!(is_microphone_access_denied("WASAPI error: 0x80070005"));
- }
+/// Converts raw ring samples into 16 kHz frames across recording sessions.
+/// Ring transport stays outside to avoid conflicting borrows during drains.
+struct CaptureProcessor {
+ // ---- stream-scoped: fixed for the life of the input stream ---------- //
+ in_sample_rate: u32,
+ vad: Option<VadConfig>,
+ level_cb: Option<LevelCallback>,
+ audio_cb: Option<AudioFrameCallback>,
+ stream_running_at: Instant,
+ visualizer: AudioVisualiser,
+ frame_resampler: FrameResampler,
+ max_drain_samples: usize,
+ first_chunk_logged: bool,
+
+ // ---- recording-scoped: reset by `begin_recording` ------------------- //
+ vad_policy: VadPolicy,
+ processed_samples: Vec<f32>,
+ awaiting_first_captured_chunk: Option<Instant>,
+ capture_ready_tx: Option<mpsc::Sender<()>>,
+ total_dropped_samples: u64,
+ overrun_warning_logged: bool,
+}
+
+impl CaptureProcessor {
+ fn new(
+ in_sample_rate: u32,
+ vad: Option<VadConfig>,
+ level_cb: Option<LevelCallback>,
+ audio_cb: Option<AudioFrameCallback>,
+ stream_running_at: Instant,
+ ) -> Self {
+ // Resample into frames sized for the active VAD backend (30 ms when
+ // no detector is attached) so the detector never sees a partial frame.
+ let frame_samples = vad.as_ref().map_or(
+ (constants::WHISPER_SAMPLE_RATE * 30 / 1000) as usize,
+ |config| config.frame_samples,
+ );
+ let frame_duration =
+ Duration::from_secs_f64(frame_samples as f64 / constants::WHISPER_SAMPLE_RATE as f64);
+ let frame_resampler = FrameResampler::new(
+ in_sample_rate as usize,
+ constants::WHISPER_SAMPLE_RATE as usize,
+ frame_duration,
+ );
- #[test]
- fn does_not_match_unrelated_errors() {
- assert!(!is_microphone_access_denied("device not found"));
+ const BUCKETS: usize = 16;
+ let target_window = (f64::from(in_sample_rate) / 30.0).round() as usize;
+ let window_size = [256usize, 512, 1024, 2048]
+ .into_iter()
+ .min_by_key(|w| w.abs_diff(target_window))
+ .unwrap();
+ let visualizer = AudioVisualiser::new(in_sample_rate, window_size, BUCKETS, 400.0, 4000.0);
+
+ let max_drain_samples =
+ ((in_sample_rate as u128 * MAX_DRAIN_CHUNK.as_millis()) / 1_000).max(1) as usize;
+
+ Self {
+ in_sample_rate,
+ vad,
+ level_cb,
+ audio_cb,
+ stream_running_at,
+ visualizer,
+ frame_resampler,
+ max_drain_samples,
+ first_chunk_logged: false,
+ vad_policy: VadPolicy::Offline,
+ processed_samples: Vec::new(),
+ awaiting_first_captured_chunk: None,
+ capture_ready_tx: None,
+ total_dropped_samples: 0,
+ overrun_warning_logged: false,
+ }
}
- #[test]
- fn detects_no_input_device() {
- assert!(is_no_input_device_error("No input device found"));
+ /// Reset per-recording state and arm the first-sample acknowledgement.
+ fn begin_recording(&mut self, policy: VadPolicy, ready_tx: mpsc::Sender<()>) {
+ self.awaiting_first_captured_chunk = Some(Instant::now());
+ self.capture_ready_tx = Some(ready_tx);
+ self.total_dropped_samples = 0;
+ self.overrun_warning_logged = false;
+ self.vad_policy = policy;
+ self.processed_samples.clear();
+ self.visualizer.reset();
+ self.frame_resampler.reset();
+ if policy != VadPolicy::Disabled {
+ if let Some(cfg) = &self.vad {
+ let mut detector = cfg.detector.lock().unwrap();
+ detector.set_hangover_frames(cfg.hangover_for(policy));
+ detector.reset();
+ }
+ }
}
- #[test]
- fn detects_coreaudio_config_error() {
- assert!(is_no_input_device_error(
- "Failed to fetch preferred config: A backend-specific error has occurred: An unknown error unknown to the coreaudio-rs API occurred"
- ));
+ /// Drop a pending first-sample acknowledgement. If Stop was queued before
+ /// the first chunk, this prevents a stale ready UI event or start chime.
+ fn cancel_ready_signal(&mut self) {
+ self.capture_ready_tx = None;
+ self.awaiting_first_captured_chunk = None;
}
- #[test]
- fn does_not_match_other_errors_for_no_device() {
- assert!(!is_no_input_device_error("permission denied"));
- assert!(!is_no_input_device_error("device not found"));
+ /// Drain up to one bounded chunk from the ring. Returns the number of
+ /// samples consumed so callers can tell an empty ring from a busy one.
+ fn drain(&mut self, consumer: &mut Consumer<f32>, disposition: ChunkDisposition) -> usize {
+ let max_samples = self.max_drain_samples;
+ drain_available_samples(consumer, max_samples, |raw| {
+ self.process_raw_chunk(raw, disposition)
+ })
}
-}
-#[allow(clippy::too_many_arguments)]
-fn run_consumer(
- in_sample_rate: u32,
- vad: Option<VadConfig>,
- sample_rx: mpsc::Receiver<AudioChunk>,
- cmd_rx: mpsc::Receiver<Cmd>,
- level_cb: Option<Arc<dyn Fn(Vec<f32>) + Send + Sync + 'static>>,
- audio_cb: Option<AudioFrameCallback>,
- stop_flag: Arc<AtomicBool>,
- stream_running_at: Instant,
-) {
- let frame_samples = vad.as_ref().map_or(
- (constants::WHISPER_SAMPLE_RATE * 30 / 1000) as usize,
- |config| config.frame_samples,
- );
- let frame_duration =
- Duration::from_secs_f64(frame_samples as f64 / constants::WHISPER_SAMPLE_RATE as f64);
- let mut frame_resampler = FrameResampler::new(
- in_sample_rate as usize,
- constants::WHISPER_SAMPLE_RATE as usize,
- frame_duration,
- );
-
- let mut processed_samples = Vec::<f32>::new();
- let mut recording = false;
- let mut vad_policy = VadPolicy::Offline;
-
- // ---------- latency instrumentation ---------------------------------- //
- // First-chunk arrival exposes the play()->samples-flowing gap; the
- // first-captured log confirms capture begins with the chunk in flight
- // when Cmd::Start lands.
- let mut first_chunk_logged = false;
- let mut awaiting_first_captured_chunk: Option<Instant> = None;
- let mut capture_ready_tx: Option<mpsc::Sender<()>> = None;
-
- // ---------- spectrum visualisation setup ---------------------------- //
- const BUCKETS: usize = 16;
- // Scale the FFT window to the device sample rate so the analysis window
- // (~33 ms) and frequency resolution (~30 Hz/bin) stay roughly constant
- // across devices. A fixed 512-sample window collapses the low vocal
- // buckets onto a single bin at 48 kHz (e.g. built-in laptop mics), and
- // would stutter at ~4-8 updates/sec on an 8-16 kHz Bluetooth headset.
- // Targets: 48 kHz -> 2048, 16 kHz -> 512, 8 kHz -> 256.
- let target_window = (f64::from(in_sample_rate) / 30.0).round() as usize;
- let window_size = [256usize, 512, 1024, 2048]
- .into_iter()
- .min_by_key(|w| w.abs_diff(target_window))
- .unwrap();
- let mut visualizer = AudioVisualiser::new(
- in_sample_rate,
- window_size,
- BUCKETS,
- 400.0, // vocal_min_hz
- 4000.0, // vocal_max_hz
- );
-
- fn handle_frame(
- samples: &[f32],
- recording: bool,
- vad_policy: VadPolicy,
- vad: &Option<VadConfig>,
- audio_cb: &Option<AudioFrameCallback>,
- out_buf: &mut Vec<f32>,
- ) {
- if !recording {
+ fn process_raw_chunk(&mut self, raw: &[f32], disposition: ChunkDisposition) {
+ let chunk_ms = raw.len() as f64 * 1000.0 / self.in_sample_rate as f64;
+ if !self.first_chunk_logged {
+ self.first_chunk_logged = true;
+ log::debug!(
+ "first audio samples arrived {:?} after stream start ({:.1}ms drained)",
+ self.stream_running_at.elapsed(),
+ chunk_ms
+ );
+ }
+
+ if disposition == ChunkDisposition::Discard {
return;
}
- let mut emit = |buf: &[f32]| {
- out_buf.extend_from_slice(buf);
- if let Some(cb) = audio_cb {
- cb(buf);
+ if let Some(buckets) = self.visualizer.feed(raw) {
+ if let Some(callback) = &self.level_cb {
+ callback(buckets);
}
- };
+ }
+
+ let vad_policy = self.vad_policy;
+ self.frame_resampler.push(raw, |frame: &[f32]| {
+ handle_frame(
+ frame,
+ vad_policy,
+ &self.vad,
+ &self.audio_cb,
+ &mut self.processed_samples,
+ )
+ });
- if vad_policy == VadPolicy::Disabled {
- emit(samples);
+ if let Some(started) = self.awaiting_first_captured_chunk.take() {
+ log::debug!(
+ "first captured samples ({:.1}ms) processed {:?} after Cmd::Start",
+ chunk_ms,
+ started.elapsed()
+ );
+ }
+ if let Some(ready_tx) = self.capture_ready_tx.take() {
+ // Silence still counts: readiness means the host is delivering samples,
+ // not that VAD has detected speech.
+ let _ = ready_tx.send(());
+ }
+ }
+
+ /// Account for samples the callback could not fit into the ring during
+ /// the active recording. Warns once per recording.
+ fn observe_overrun(&mut self, samples: u64) {
+ if samples == 0 {
return;
}
- if let Some(cfg) = vad {
- let mut det = cfg.detector.lock().unwrap();
- match det.push_frame(samples).unwrap_or(VadFrame::Speech(samples)) {
- VadFrame::Speech(buf) => emit(buf),
- VadFrame::Noise => {}
- }
- } else {
- emit(samples);
+ self.total_dropped_samples = self.total_dropped_samples.saturating_add(samples);
+ if !self.overrun_warning_logged {
+ self.overrun_warning_logged = true;
+ log::warn!(
+ "Microphone capture ring dropped {samples} samples; continuing the active recording"
+ );
}
}
- // Poll commands even when a disconnected device stops producing samples
- // without closing its CoreAudio stream.
- loop {
- let mut pending = match sample_rx.recv_timeout(Duration::from_millis(50)) {
- Ok(chunk) => Some(chunk),
- Err(mpsc::RecvTimeoutError::Timeout) => None,
- Err(mpsc::RecvTimeoutError::Disconnected) => break,
- };
+ /// Flush the resampler tail and hand back the finished recording.
+ fn finish_recording(&mut self) -> Vec<f32> {
+ let vad_policy = self.vad_policy;
+ self.frame_resampler.finish(|frame: &[f32]| {
+ handle_frame(
+ frame,
+ vad_policy,
+ &self.vad,
+ &self.audio_cb,
+ &mut self.processed_samples,
+ )
+ });
- // Handle pending commands BEFORE the in-flight chunk so a Start
- // captures it. Commands used to be polled after processing, which
- // silently dropped one buffer period of audio (~10ms built-in, up to
- // ~100ms on Bluetooth) at every recording start.
- while let Ok(cmd) = cmd_rx.try_recv() {
- match cmd {
- Cmd::Start(policy, sent_at, ready_tx) => {
+ // Diagnostic for VAD audio still withheld when capture stopped; it is
+ // not conclusive in either direction.
+ if vad_policy != VadPolicy::Disabled {
+ if let Some(cfg) = &self.vad {
+ let report = cfg.detector.lock().unwrap().tail_report();
+ if let Some(report) = report {
log::debug!(
- "Cmd::Start processed {:?} after send; capture begins with {} chunk",
- sent_at.elapsed(),
- if pending.is_some() {
- "the in-flight"
- } else {
- "the next available"
- }
+ "VAD at stop: withheld tail {} frames (~{}ms, {} voiced), in_speech={}, onset_counter={}, hangover_counter={}",
+ report.withheld_frames,
+ report.withheld_frames * cfg.frame_samples * 1000
+ / constants::WHISPER_SAMPLE_RATE as usize,
+ report.withheld_voiced_frames,
+ report.in_speech,
+ report.onset_counter,
+ report.hangover_counter
);
- awaiting_first_captured_chunk = Some(Instant::now());
- capture_ready_tx = Some(ready_tx);
- stop_flag.store(false, Ordering::Relaxed);
- vad_policy = policy;
- processed_samples.clear();
- recording = true;
- visualizer.reset();
- frame_resampler.reset();
- // Reconfigure the single VAD engine for this session's policy
- // and clear its smoothing + recurrent state before it sees
- // any frames.
- if vad_policy != VadPolicy::Disabled {
- if let Some(cfg) = &vad {
- let mut det = cfg.detector.lock().unwrap();
- det.set_hangover_frames(cfg.hangover_for(vad_policy));
- det.reset();
- }
- }
}
- Cmd::Stop(reply_tx) => {
- recording = false;
- // If Stop was queued before the first chunk, dropping this
- // sender prevents a stale ready UI event or start chime.
- capture_ready_tx = None;
- awaiting_first_captured_chunk = None;
- stop_flag.store(true, Ordering::Relaxed);
-
- // The chunk in hand arrived before the stop; it belongs to
- // the recording, so feed it ahead of the drain below.
- if let Some(AudioChunk::Samples(raw)) = pending.take() {
- frame_resampler.push(&raw, &mut |frame: &[f32]| {
- handle_frame(
- frame,
- true,
- vad_policy,
- &vad,
- &audio_cb,
- &mut processed_samples,
- )
- });
- }
+ }
+ }
+
+ if self.total_dropped_samples > 0 {
+ log::warn!(
+ "Active recording completed after dropping {} microphone samples",
+ self.total_dropped_samples
+ );
+ }
+ std::mem::take(&mut self.processed_samples)
+ }
+}
- // Drain all remaining audio until the producer confirms end-of-stream.
- // The cpal callback sees the stop flag, sends EndOfStream, and goes
- // silent — guaranteeing every captured sample is in the channel
- // ahead of the sentinel.
- loop {
- match sample_rx.recv_timeout(Duration::from_secs(2)) {
- Ok(AudioChunk::Samples(remaining)) => {
- frame_resampler.push(&remaining, &mut |frame: &[f32]| {
- handle_frame(
- frame,
- true,
- vad_policy,
- &vad,
- &audio_cb,
- &mut processed_samples,
- )
- });
+fn run_consumer(
+ mut processor: CaptureProcessor,
+ mut sample_consumer: Consumer<f32>,
+ cmd_rx: mpsc::Receiver<Cmd>,
+ transport: Arc<CaptureTransportState>,
+ stream_error: Arc<AtomicBool>,
+) {
+ let mut recording = false;
+ let mut stream_error_logged = false;
+
+ loop {
+ // Avoid sleeping with queued audio; check commands before each bounded
+ // drain so Stop cannot sit behind a multi-second backlog.
+ let mut command = if sample_consumer.slots() > 0 {
+ match cmd_rx.try_recv() {
+ Ok(command) => Some(command),
+ Err(mpsc::TryRecvError::Empty) => None,
+ Err(mpsc::TryRecvError::Disconnected) => return,
+ }
+ } else {
+ match cmd_rx.recv_timeout(CONSUMER_POLL_INTERVAL) {
+ Ok(command) => Some(command),
+ Err(mpsc::RecvTimeoutError::Timeout) => None,
+ Err(mpsc::RecvTimeoutError::Disconnected) => return,
+ }
+ };
+
+ loop {
+ if let Some(cmd) = command.take() {
+ match cmd {
+ Cmd::Start(policy, sent_at, ready_tx) => {
+ log::debug!(
+ "Cmd::Start processed {:?} after send; capture begins with {} samples",
+ sent_at.elapsed(),
+ if sample_consumer.slots() > 0 {
+ "the in-flight"
+ } else {
+ "the next available"
}
- Ok(AudioChunk::EndOfStream) => break,
- Err(_) => {
- log::warn!("Timed out waiting for EndOfStream from audio callback");
- break;
+ );
+ // Ignore overruns accumulated while the always-on stream
+ // was idle; only active-capture loss is relevant.
+ transport.overrun_samples.store(0, Ordering::Release);
+ processor.begin_recording(policy, ready_tx);
+ recording = true;
+ }
+ Cmd::Stop(reply_tx) => {
+ processor
+ .observe_overrun(transport.overrun_samples.swap(0, Ordering::AcqRel));
+ recording = false;
+ processor.cancel_ready_signal();
+
+ // Request a pause that forwards one boundary block, then drain
+ // all audio committed before the acknowledgement.
+ transport.pause_acknowledged.store(false, Ordering::Relaxed);
+ transport.pause_requested.store(true, Ordering::Release);
+ let pause_started = Instant::now();
+ while !transport.pause_acknowledged.load(Ordering::Acquire)
+ && pause_started.elapsed() < PAUSE_ACK_TIMEOUT
+ {
+ let drained =
+ processor.drain(&mut sample_consumer, ChunkDisposition::Capture);
+ if drained == 0 {
+ std::thread::sleep(Duration::from_millis(1));
}
}
- }
- frame_resampler.finish(&mut |frame: &[f32]| {
- handle_frame(
- frame,
- true,
- vad_policy,
- &vad,
- &audio_cb,
- &mut processed_samples,
- )
- });
-
- // Diagnostic only: evidence for whether the VAD was
- // still withholding tail audio when capture stopped.
- // Suggestive, not conclusive, in either direction.
- if vad_policy != VadPolicy::Disabled {
- if let Some(cfg) = &vad {
- let report = cfg.detector.lock().unwrap().tail_report();
- if let Some(report) = report {
- log::debug!(
- "VAD at stop: withheld tail {} frames (~{}ms, {} voiced), in_speech={}, onset_counter={}, hangover_counter={}",
- report.withheld_frames,
- report.withheld_frames * cfg.frame_samples * 1000
- / constants::WHISPER_SAMPLE_RATE as usize,
- report.withheld_voiced_frames,
- report.in_speech,
- report.onset_counter,
- report.hangover_counter
- );
- }
+ let pause_timed_out = !transport.pause_acknowledged.load(Ordering::Acquire);
+ if pause_timed_out {
+ log::warn!("Timed out waiting for the microphone callback to pause");
+ // Preserve the existing recovery model: finish this
+ // stop, then rebuild the stream on the next start.
+ stream_error.store(true, Ordering::Release);
}
- }
- let _ = reply_tx.send(std::mem::take(&mut processed_samples));
+ // Everything still in the ring, including the boundary
+ // block, belongs to this recording.
+ while processor.drain(&mut sample_consumer, ChunkDisposition::Capture) > 0 {
+ }
- // Resume the audio callback so the consumer loop can continue
- // receiving chunks (important for always-on microphone mode).
- stop_flag.store(false, Ordering::Relaxed);
- }
- Cmd::Shutdown => {
- stop_flag.store(true, Ordering::Relaxed);
- return;
+ // Include drops that raced with the pause request.
+ processor
+ .observe_overrun(transport.overrun_samples.swap(0, Ordering::AcqRel));
+ let samples = processor.finish_recording();
+ if !pause_timed_out {
+ // Resume before stop() returns so an immediate recording
+ // cannot lose its first callback to this pause request.
+ transport.pause_acknowledged.store(false, Ordering::Relaxed);
+ transport.pause_requested.store(false, Ordering::Release);
+ }
+ let _ = reply_tx.send(samples);
+
+ if pause_timed_out {
+ return;
+ }
+ }
+ Cmd::Shutdown => {
+ transport.pause_requested.store(true, Ordering::Release);
+ return;
+ }
}
}
+
+ command = match cmd_rx.try_recv() {
+ Ok(command) => Some(command),
+ Err(mpsc::TryRecvError::Empty) => break,
+ Err(mpsc::TryRecvError::Disconnected) => return,
+ };
}
- let raw = match pending.take() {
- Some(AudioChunk::Samples(s)) => s,
- // EndOfStream, or the chunk was consumed by a Stop above.
- _ => continue,
+ let disposition = if recording {
+ ChunkDisposition::Capture
+ } else {
+ ChunkDisposition::Discard
};
+ processor.drain(&mut sample_consumer, disposition);
- let chunk_ms = raw.len() as f64 * 1000.0 / in_sample_rate as f64;
- if !first_chunk_logged {
- first_chunk_logged = true;
- log::debug!(
- "first audio chunk arrived {:?} after stream start ({:.1}ms of audio)",
- stream_running_at.elapsed(),
- chunk_ms
- );
- }
-
- // ---------- recording-time processing ---------------------------- //
- // In always-on mode the capture stream stays open continuously for
- // zero-latency start, so while idle (not recording) there is nothing to
- // do with a chunk: handle_frame returns early when not recording, which
- // means the resampled output would be discarded, and the level meter has
- // no idle consumer. Skip both the level-meter FFT and the resampler while
- // idle to avoid doing unnecessary work whose output is thrown away. Both
- // are reset on Cmd::Start (visualizer.reset() / frame_resampler.reset()),
- // so they resume cleanly the moment recording begins.
+ let overrun_samples = transport.overrun_samples.swap(0, Ordering::AcqRel);
if recording {
- if let Some(buckets) = visualizer.feed(&raw) {
- if let Some(cb) = &level_cb {
- cb(buckets);
- }
- }
-
- frame_resampler.push(&raw, &mut |frame: &[f32]| {
- handle_frame(
- frame,
- recording,
- vad_policy,
- &vad,
- &audio_cb,
- &mut processed_samples,
- )
- });
+ processor.observe_overrun(overrun_samples);
}
- if recording {
- if let Some(started) = awaiting_first_captured_chunk.take() {
- log::debug!(
- "first captured chunk ({:.1}ms of audio) processed {:?} after Cmd::Start",
- chunk_ms,
- started.elapsed()
- );
- }
- if let Some(ready_tx) = capture_ready_tx.take() {
- // Signal only after this chunk has passed through the visualizer
- // and resampler. Silence still counts: readiness means the host
- // is delivering samples, not that VAD has detected speech.
- let _ = ready_tx.send(());
- }
+ // The CPAL error callback only sets an atomic; log here and rebuild the
+ // stream on the next start.
+ if stream_error.load(Ordering::Acquire) && !stream_error_logged {
+ log::error!("Microphone backend reported a stream error; it will be rebuilt");
+ stream_error_logged = true;
}
}
}
+
+#[cfg(test)]
+mod tests;
diff --git a/src-tauri/src/audio_toolkit/audio/recorder/tests.rs b/src-tauri/src/audio_toolkit/audio/recorder/tests.rs
new file mode 100644
index 00000000..271acde2
--- /dev/null
+++ b/src-tauri/src/audio_toolkit/audio/recorder/tests.rs
@@ -0,0 +1,418 @@
+use super::{
+ is_microphone_access_denied, is_no_input_device_error, run_consumer, AudioRecorder,
+ CaptureProcessor, CaptureTransportState, ChunkDisposition, Cmd, VadConfig, VadPolicy,
+};
+use crate::audio_toolkit::vad::{VadFrame, VoiceActivityDetector};
+use rtrb::RingBuffer;
+use std::{
+ sync::{
+ atomic::{AtomicBool, Ordering},
+ mpsc, Arc, Mutex,
+ },
+ thread,
+ time::{Duration, Instant},
+};
+
+#[test]
+fn unopened_recorder_does_not_need_reopen() {
+ let recorder = AudioRecorder::new().expect("recorder");
+ assert!(!recorder.needs_reopen());
+}
+
+#[test]
+fn stream_error_requires_reopen() {
+ let recorder = AudioRecorder::new().expect("recorder");
+ recorder.stream_error.store(true, Ordering::Relaxed);
+ assert!(recorder.needs_reopen());
+}
+
+/// Pass-through detector with a configurable frame size, standing in for a
+/// backend such as Earshot whose frames are not 30 ms.
+struct FixedFrameVad(usize);
+
+impl VoiceActivityDetector for FixedFrameVad {
+ fn push_frame<'a>(&'a mut self, frame: &'a [f32]) -> anyhow::Result<VadFrame<'a>> {
+ Ok(VadFrame::Speech(frame))
+ }
+
+ fn frame_samples(&self) -> usize {
+ self.0
+ }
+}
+
+#[test]
+fn resampler_frame_size_follows_the_vad_backend() {
+ let frame_samples = 256;
+ let vad = VadConfig {
+ detector: Arc::new(Mutex::new(Box::new(FixedFrameVad(frame_samples)))),
+ frame_samples,
+ offline_hangover_frames: 0,
+ streaming_hangover_frames: 0,
+ };
+ let frame_lengths = Arc::new(Mutex::new(Vec::new()));
+ let observed = Arc::clone(&frame_lengths);
+ let mut processor = CaptureProcessor::new(
+ 16_000,
+ Some(vad),
+ None,
+ Some(Arc::new(move |frame: &[f32]| {
+ observed.lock().unwrap().push(frame.len())
+ })),
+ Instant::now(),
+ );
+
+ let (ready_tx, _ready_rx) = mpsc::channel();
+ processor.begin_recording(VadPolicy::Offline, ready_tx);
+ processor.process_raw_chunk(&[0.0; 1024], ChunkDisposition::Capture);
+ let samples = processor.finish_recording();
+
+ assert_eq!(samples.len(), 1024);
+ assert_eq!(*frame_lengths.lock().unwrap(), vec![frame_samples; 4]);
+}
+
+#[test]
+fn idle_chunks_are_discarded_without_reaching_the_recording() {
+ let mut processor = CaptureProcessor::new(16_000, None, None, None, Instant::now());
+ processor.process_raw_chunk(&[1.0; 480], ChunkDisposition::Discard);
+ assert!(processor.finish_recording().is_empty());
+}
+
+#[test]
+fn shutdown_is_processed_without_audio_samples() {
+ let (_producer, consumer) = RingBuffer::<f32>::new(48_000);
+ let (cmd_tx, cmd_rx) = mpsc::channel();
+ let (done_tx, done_rx) = mpsc::channel();
+ let worker = thread::spawn(move || {
+ run_consumer(
+ CaptureProcessor::new(48_000, None, None, None, Instant::now()),
+ consumer,
+ cmd_rx,
+ Arc::new(CaptureTransportState::default()),
+ Arc::new(AtomicBool::new(false)),
+ );
+ let _ = done_tx.send(());
+ });
+
+ cmd_tx.send(Cmd::Shutdown).expect("send shutdown");
+ assert!(done_rx.recv_timeout(Duration::from_secs(1)).is_ok());
+ worker.join().expect("join consumer");
+}
+
+#[test]
+fn callback_writes_mono_samples() {
+ let (mut producer, mut consumer) = RingBuffer::<f32>::new(8);
+ let transport = CaptureTransportState::default();
+
+ AudioRecorder::write_input_to_ring(&[0.25f32, -0.5, 1.0], 1, None, &mut producer, &transport);
+
+ let mut output = [0.0; 3];
+ consumer.pop_entire_slice(&mut output).expect("samples");
+ assert_eq!(output, [0.25, -0.5, 1.0]);
+}
+
+#[test]
+fn callback_downmixes_or_selects_multichannel_input() {
+ let transport = CaptureTransportState::default();
+ let (mut average_tx, mut average_rx) = RingBuffer::<f32>::new(4);
+ AudioRecorder::write_input_to_ring(
+ &[1.0f32, 3.0, -1.0, 1.0],
+ 2,
+ None,
+ &mut average_tx,
+ &transport,
+ );
+ let mut averaged = [0.0; 2];
+ average_rx
+ .pop_entire_slice(&mut averaged)
+ .expect("averaged samples");
+ assert_eq!(averaged, [2.0, 0.0]);
+
+ let (mut selected_tx, mut selected_rx) = RingBuffer::<f32>::new(4);
+ AudioRecorder::write_input_to_ring(
+ &[1.0f32, 3.0, -1.0, 1.0],
+ 2,
+ Some(1),
+ &mut selected_tx,
+ &transport,
+ );
+ let mut selected = [0.0; 2];
+ selected_rx
+ .pop_entire_slice(&mut selected)
+ .expect("selected samples");
+ assert_eq!(selected, [3.0, 1.0]);
+}
+
+#[test]
+fn callback_forwards_boundary_block_then_stays_silent_until_resumed() {
+ let (mut producer, mut consumer) = RingBuffer::<f32>::new(8);
+ let transport = CaptureTransportState::default();
+
+ // The block in hand when a pause is first observed was captured before
+ // the stop, so it is forwarded and only then acknowledged.
+ transport.pause_requested.store(true, Ordering::Release);
+ AudioRecorder::write_input_to_ring(&[1.0f32, 2.0], 1, None, &mut producer, &transport);
+ assert!(transport.pause_acknowledged.load(Ordering::Acquire));
+ assert_eq!(consumer.slots(), 2);
+
+ // Later blocks while paused are dropped and are not counted as overruns.
+ AudioRecorder::write_input_to_ring(&[3.0f32], 1, None, &mut producer, &transport);
+ assert_eq!(consumer.slots(), 2);
+ assert_eq!(transport.overrun_samples.load(Ordering::Relaxed), 0);
+
+ // Clearing the pause, as the consumer does before stop() returns, resumes capture.
+ transport.pause_acknowledged.store(false, Ordering::Relaxed);
+ transport.pause_requested.store(false, Ordering::Release);
+ AudioRecorder::write_input_to_ring(&[4.0f32], 1, None, &mut producer, &transport);
+ let mut output = [0.0; 3];
+ consumer.pop_entire_slice(&mut output).expect("samples");
+ assert_eq!(output, [1.0, 2.0, 4.0]);
+ assert!(!transport.pause_acknowledged.load(Ordering::Acquire));
+}
+
+#[test]
+fn callback_partially_fills_ring_and_counts_dropped_audio() {
+ let (mut producer, mut consumer) = RingBuffer::<f32>::new(2);
+ let transport = CaptureTransportState::default();
+
+ AudioRecorder::write_input_to_ring(&[1.0f32, 2.0, 3.0], 1, None, &mut producer, &transport);
+
+ let mut captured = [0.0; 2];
+ consumer
+ .pop_entire_slice(&mut captured)
+ .expect("partial callback audio");
+ assert_eq!(captured, [1.0, 2.0]);
+ assert_eq!(transport.overrun_samples.load(Ordering::Relaxed), 1);
+}
+
+#[test]
+fn bounded_drain_leaves_remaining_samples_for_the_next_command_cycle() {
+ let (mut producer, mut consumer) = RingBuffer::<f32>::new(8);
+ producer
+ .push_entire_slice(&[1.0, 2.0, 3.0, 4.0, 5.0])
+ .expect("samples");
+ let mut drained = Vec::new();
+
+ let count =
+ super::drain_available_samples(&mut consumer, 3, |part| drained.extend_from_slice(part));
+
+ assert_eq!(count, 3);
+ assert_eq!(drained, [1.0, 2.0, 3.0]);
+ assert_eq!(consumer.slots(), 2);
+}
+
+#[test]
+fn ring_wraparound_preserves_both_read_slices_in_order() {
+ let (mut producer, mut consumer) = RingBuffer::<f32>::new(5);
+ let transport = CaptureTransportState::default();
+ producer
+ .push_entire_slice(&[1.0, 2.0, 3.0, 4.0])
+ .expect("initial samples");
+ let mut discarded = [0.0; 3];
+ consumer
+ .pop_entire_slice(&mut discarded)
+ .expect("advance ring head");
+
+ AudioRecorder::write_input_to_ring(
+ &[5.0f32, 6.0, 7.0, 8.0],
+ 1,
+ None,
+ &mut producer,
+ &transport,
+ );
+
+ let chunk = consumer.read_chunk(5).expect("wrapped samples");
+ let (first, second) = chunk.as_slices();
+ assert!(!first.is_empty());
+ assert!(!second.is_empty());
+ let ordered = first
+ .iter()
+ .chain(second.iter())
+ .copied()
+ .collect::<Vec<_>>();
+ assert_eq!(ordered, [4.0, 5.0, 6.0, 7.0, 8.0]);
+}
+
+#[test]
+fn repeated_start_stop_cycles_resume_capture_without_leaking_samples() {
+ let (mut producer, consumer) = RingBuffer::<f32>::new(16_000);
+ let transport = Arc::new(CaptureTransportState::default());
+ let (cmd_tx, cmd_rx) = mpsc::channel();
+ let streamed = Arc::new(Mutex::new(Vec::new()));
+ let streamed_cb = Arc::clone(&streamed);
+ let consumer_transport = Arc::clone(&transport);
+ let worker = thread::spawn(move || {
+ let processor = CaptureProcessor::new(
+ 16_000,
+ None,
+ None,
+ Some(Arc::new(move |frame: &[f32]| {
+ streamed_cb.lock().unwrap().extend_from_slice(frame)
+ })),
+ Instant::now(),
+ );
+ run_consumer(
+ processor,
+ consumer,
+ cmd_rx,
+ consumer_transport,
+ Arc::new(AtomicBool::new(false)),
+ );
+ });
+
+ let wait_for_pause_request = || {
+ let deadline = Instant::now() + Duration::from_secs(1);
+ while !transport.pause_requested.load(Ordering::Acquire) {
+ assert!(Instant::now() < deadline, "pause was not requested");
+ thread::sleep(Duration::from_millis(1));
+ }
+ };
+
+ let first_input = [0.25f32, -0.5, 1.0];
+ let (ready_tx, ready_rx) = mpsc::channel();
+ cmd_tx
+ .send(Cmd::Start(VadPolicy::Disabled, Instant::now(), ready_tx))
+ .expect("first start");
+ AudioRecorder::write_input_to_ring(&first_input, 1, None, &mut producer, &transport);
+ ready_rx
+ .recv_timeout(Duration::from_secs(1))
+ .expect("first capture ready");
+
+ let (reply_tx, reply_rx) = mpsc::channel();
+ cmd_tx.send(Cmd::Stop(reply_tx)).expect("first stop");
+ wait_for_pause_request();
+ // The first callback after Stop carries audio captured before the stop,
+ // so it belongs to the recording.
+ AudioRecorder::write_input_to_ring(&[99.0f32], 1, None, &mut producer, &transport);
+
+ let first_samples = reply_rx
+ .recv_timeout(Duration::from_secs(1))
+ .expect("first stop reply");
+ let first_expected = [0.25f32, -0.5, 1.0, 99.0];
+ assert_eq!(&first_samples[..first_expected.len()], &first_expected);
+ assert!(first_samples[first_expected.len()..]
+ .iter()
+ .all(|&sample| sample == 0.0));
+ assert!(!transport.pause_requested.load(Ordering::Acquire));
+
+ let first_streamed_len = {
+ let streamed = streamed.lock().unwrap();
+ assert_eq!(&streamed[..first_expected.len()], &first_expected);
+ streamed.len()
+ };
+
+ // Start again immediately after stop() would have returned. The producer
+ // must already be re-enabled, and no first-cycle samples may leak through.
+ let second_input = [0.75f32, -0.25, 0.5];
+ let (ready_tx, ready_rx) = mpsc::channel();
+ cmd_tx
+ .send(Cmd::Start(VadPolicy::Disabled, Instant::now(), ready_tx))
+ .expect("second start");
+ AudioRecorder::write_input_to_ring(&second_input, 1, None, &mut producer, &transport);
+ ready_rx
+ .recv_timeout(Duration::from_secs(1))
+ .expect("second capture ready");
+
+ let (reply_tx, reply_rx) = mpsc::channel();
+ cmd_tx.send(Cmd::Stop(reply_tx)).expect("second stop");
+ wait_for_pause_request();
+ AudioRecorder::write_input_to_ring(&[199.0f32], 1, None, &mut producer, &transport);
+
+ let second_samples = reply_rx
+ .recv_timeout(Duration::from_secs(1))
+ .expect("second stop reply");
+ let second_expected = [0.75f32, -0.25, 0.5, 199.0];
+ assert_eq!(&second_samples[..second_expected.len()], &second_expected);
+ assert!(second_samples[second_expected.len()..]
+ .iter()
+ .all(|&sample| sample == 0.0));
+ assert!(!first_samples
+ .iter()
+ .any(|sample| second_expected.contains(sample)));
+ assert!(!second_samples
+ .iter()
+ .any(|sample| first_expected.contains(sample)));
+ assert!(!transport.pause_requested.load(Ordering::Acquire));
+
+ {
+ let streamed = streamed.lock().unwrap();
+ assert_eq!(streamed.len(), first_streamed_len + second_samples.len());
+ assert_eq!(
+ &streamed[first_streamed_len..first_streamed_len + second_expected.len()],
+ &second_expected
+ );
+ }
+
+ cmd_tx.send(Cmd::Shutdown).expect("shutdown");
+ worker.join().expect("consumer worker");
+}
+
+#[test]
+fn missing_callback_at_stop_marks_stream_for_rebuild_and_returns_samples() {
+ let (_producer, consumer) = RingBuffer::<f32>::new(16_000);
+ let transport = Arc::new(CaptureTransportState::default());
+ let stream_error = Arc::new(AtomicBool::new(false));
+ let observed_error = Arc::clone(&stream_error);
+ let (cmd_tx, cmd_rx) = mpsc::channel();
+ let worker_transport = Arc::clone(&transport);
+ let worker = thread::spawn(move || {
+ run_consumer(
+ CaptureProcessor::new(16_000, None, None, None, Instant::now()),
+ consumer,
+ cmd_rx,
+ worker_transport,
+ stream_error,
+ );
+ });
+
+ let (ready_tx, _ready_rx) = mpsc::channel();
+ cmd_tx
+ .send(Cmd::Start(VadPolicy::Disabled, Instant::now(), ready_tx))
+ .expect("start");
+ let (reply_tx, reply_rx) = mpsc::channel();
+ cmd_tx.send(Cmd::Stop(reply_tx)).expect("stop");
+
+ let samples = reply_rx
+ .recv_timeout(Duration::from_secs(3))
+ .expect("pause timeout still returns captured samples");
+ assert!(samples.is_empty());
+ worker.join().expect("consumer exits after pause timeout");
+ assert!(observed_error.load(Ordering::Acquire));
+}
+
+#[test]
+fn detects_access_is_denied() {
+ assert!(is_microphone_access_denied("Access is denied"));
+}
+
+#[test]
+fn detects_permission_denied() {
+ assert!(is_microphone_access_denied("permission denied"));
+}
+
+#[test]
+fn detects_windows_error_code() {
+ assert!(is_microphone_access_denied("WASAPI error: 0x80070005"));
+}
+
+#[test]
+fn does_not_match_unrelated_errors() {
+ assert!(!is_microphone_access_denied("device not found"));
+}
+
+#[test]
+fn detects_no_input_device() {
+ assert!(is_no_input_device_error("No input device found"));
+}
+
+#[test]
+fn detects_coreaudio_config_error() {
+ assert!(is_no_input_device_error(
+ "Failed to fetch preferred config: A backend-specific error has occurred: An unknown error unknown to the coreaudio-rs API occurred"
+ ));
+}
+
+#[test]
+fn does_not_match_other_errors_for_no_device() {
+ assert!(!is_no_input_device_error("permission denied"));
+ assert!(!is_no_input_device_error("device not found"));
+}