feat #14740: two-track capture and recorder

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
hauke
2026-11-05 14:31:11 +01:00
co-authored by Claude Opus 5.5
parent 7beae18a85
commit 8e8a3c3c58
9 changed files with 1354 additions and 3 deletions
+72
View File
@@ -0,0 +1,72 @@
//! Platform-neutral capture interface.
//!
//! The platform crate (`recorder-audio`) implements [`CaptureSource`] for the
//! microphone and for the call app's audio output (WASAPI on Windows,
//! PulseAudio on Linux). The [`Recorder`](crate::recorder::Recorder) only sees
//! this trait, which keeps it testable with fake sources.
use thiserror::Error;
/// Format of the interleaved `f32` samples a [`CaptureSource`] delivers.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct StreamFormat {
pub rate: u32,
pub channels: u16,
}
/// What the output ("out") track records.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum OutputTarget {
/// Only the audio rendered by this process and its children (Windows
/// application loopback). Falls back to [`OutputTarget::DefaultRender`]
/// where per-process capture is not available.
Process { root_pid: u32 },
/// Everything played on the default (communications) output device.
DefaultRender,
/// Everything played on the output device with this id.
Device(String),
}
/// One audio endpoint as shown in the device picker.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DeviceInfo {
pub id: String,
pub name: String,
}
/// Available capture inputs (microphones) and outputs (render endpoints).
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct Devices {
pub inputs: Vec<DeviceInfo>,
pub outputs: Vec<DeviceInfo>,
}
#[derive(Debug, Error)]
pub enum CaptureError {
#[error("audio device not found: {0}")]
DeviceNotFound(String),
#[error("unsupported: {0}")]
Unsupported(String),
#[error("audio backend error: {0}")]
Backend(String),
}
/// Receives interleaved `f32` samples from a running [`CaptureSource`].
pub type DataCallback = Box<dyn FnMut(&[f32]) + Send>;
/// A live audio stream (microphone or output loopback).
///
/// Implementations run the platform stream on their own thread, so the
/// non-`Send` platform handles never leave it. [`CaptureSource::start`]
/// returns only once the stream is actually open (or failed to open);
/// afterwards `on_data` is called from the capture thread with interleaved
/// `f32` samples in the returned [`StreamFormat`]. [`CaptureSource::stop`]
/// blocks until the capture thread has ended and `on_data` will not be called
/// again (a thread stuck in a platform call may be detached after a timeout
/// instead, so callers must tolerate a stray late call); calling it more than
/// once is harmless.
pub trait CaptureSource: Send {
fn start(&mut self, on_data: DataCallback) -> Result<StreamFormat, CaptureError>;
fn stop(&mut self);
}
+2
View File
@@ -5,7 +5,9 @@
//! application shell so it can be unit-tested without a GUI or network.
pub mod audio;
pub mod capture;
pub mod model;
pub mod recorder;
pub mod retention;
pub mod store;
+610
View File
@@ -0,0 +1,610 @@
//! Two-track call recorder: microphone ("mic") and call output ("out").
//!
//! Each track runs its own pipeline inline in the capture callback:
//! [`Conditioner`] (downmix + resample to 16 kHz mono) -> [`GapFiller`]
//! (silence for missing packets) -> [`TrackWriter`] (crash-safe WAV). Both
//! tracks measure time against one shared start [`Instant`], and a timer
//! thread pads a track that stopped delivering data, so the two WAVs stay
//! aligned sample-for-sample with wall-clock time.
use std::fs;
use std::io;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicU32, Ordering};
use std::sync::mpsc::{self, RecvTimeoutError, Sender};
use std::sync::{Arc, Mutex, MutexGuard};
use std::thread::{self, JoinHandle};
use std::time::{Duration, Instant};
use thiserror::Error;
use crate::audio::{rms_level, Conditioner, GapFiller, TrackWriter};
use crate::capture::{CaptureError, CaptureSource, StreamFormat};
/// Track sample rate (matches the on-disk WAV format).
const RATE: u32 = 16_000;
/// How often silent tracks are padded up to wall-clock time.
const PAD_INTERVAL: Duration = Duration::from_millis(500);
#[derive(Debug, Error)]
pub enum RecorderError {
#[error(transparent)]
Io(#[from] io::Error),
#[error("both audio sources failed to start (mic: {mic}; out: {out})")]
BothSourcesFailed {
mic: CaptureError,
out: CaptureError,
},
}
/// Pipeline state of one track, touched by the capture callback, the pad
/// timer and `stop`.
struct TrackState {
/// `None` until the source has reported its stream format.
conditioner: Option<Conditioner>,
/// Raw samples that arrived before the format was known.
early: Vec<f32>,
gap: GapFiller,
/// `None` once finalized or discarded.
writer: Option<TrackWriter>,
/// First write error; later writes are skipped.
error: Option<io::Error>,
}
impl TrackState {
fn write(&mut self, samples: &[f32]) {
if samples.is_empty() || self.error.is_some() {
return;
}
if let Some(writer) = self.writer.as_mut() {
if let Err(err) = writer.write(samples) {
self.error = Some(err);
}
}
}
}
/// The part of a track shared with its capture callback and the pad timer.
struct TrackShared {
state: Mutex<TrackState>,
/// `f32` bits of the latest chunk's rms level, readable without locking.
level: AtomicU32,
write_failed: AtomicBool,
}
impl TrackShared {
fn new(writer: TrackWriter) -> Self {
Self {
state: Mutex::new(TrackState {
conditioner: None,
early: Vec::new(),
gap: GapFiller::new(RATE),
writer: Some(writer),
error: None,
}),
level: AtomicU32::new(0f32.to_bits()),
write_failed: AtomicBool::new(false),
}
}
/// Never fails on a poisoned lock: a panic elsewhere must not take the
/// recording down with it.
fn lock(&self) -> MutexGuard<'_, TrackState> {
self.state
.lock()
.unwrap_or_else(|poisoned| poisoned.into_inner())
}
fn level(&self) -> f32 {
f32::from_bits(self.level.load(Ordering::Relaxed))
}
fn set_level(&self, level: f32) {
self.level.store(level.to_bits(), Ordering::Relaxed);
}
/// Conditions and writes one capture chunk that arrived at `elapsed`.
fn on_data(&self, elapsed: Duration, raw: &[f32]) {
let mut state = self.lock();
let Some(conditioner) = state.conditioner.as_mut() else {
state.early.extend_from_slice(raw);
return;
};
let conditioned = conditioner.process(raw);
self.push(&mut state, elapsed, &conditioned);
}
/// Installs the conditioner once the stream format is known and pushes
/// whatever arrived before.
fn set_format(&self, format: StreamFormat, elapsed: Duration) {
let mut state = self.lock();
let mut conditioner = Conditioner::new(format.rate, format.channels);
let early = std::mem::take(&mut state.early);
let conditioned = conditioner.process(&early);
state.conditioner = Some(conditioner);
self.push(&mut state, elapsed, &conditioned);
}
fn push(&self, state: &mut TrackState, elapsed: Duration, conditioned: &[f32]) {
if conditioned.is_empty() {
return;
}
let samples = state.gap.fill(elapsed, conditioned);
state.write(&samples);
self.set_level(rms_level(conditioned));
self.note_error(state);
}
/// Pads the track with silence up to `elapsed` if it is lagging.
fn pad(&self, elapsed: Duration) {
let mut state = self.lock();
let zeros = state.gap.pad_to(elapsed);
if !zeros.is_empty() {
state.write(&zeros);
self.set_level(0.0);
self.note_error(&state);
}
}
fn note_error(&self, state: &TrackState) {
if state.error.is_some() {
self.write_failed.store(true, Ordering::Relaxed);
}
}
}
struct Track {
name: &'static str,
path: PathBuf,
source: Box<dyn CaptureSource>,
shared: Arc<TrackShared>,
start_failed: bool,
}
impl Track {
fn create(name: &'static str, source: Box<dyn CaptureSource>, path: &Path) -> io::Result<Self> {
let writer = TrackWriter::create(path)?;
Ok(Self {
name,
path: path.to_path_buf(),
source,
shared: Arc::new(TrackShared::new(writer)),
start_failed: false,
})
}
fn start(&mut self, started: Instant) -> Result<(), CaptureError> {
let shared = self.shared.clone();
let on_data = Box::new(move |raw: &[f32]| shared.on_data(started.elapsed(), raw));
let result = self.source.start(on_data).and_then(|format| {
if format.rate == 0 || format.channels == 0 {
self.source.stop();
Err(CaptureError::Unsupported(format!(
"stream format {} Hz, {} channels",
format.rate, format.channels
)))
} else {
Ok(format)
}
});
match result {
Ok(format) => {
self.shared.set_format(format, started.elapsed());
Ok(())
}
Err(err) => {
self.start_failed = true;
Err(err)
}
}
}
/// Flushes the conditioner and pads up to `elapsed`; returns the number
/// of samples the track now holds.
fn drain(&self, elapsed: Duration) -> u64 {
let mut state = self.shared.lock();
if let Some(conditioner) = state.conditioner.as_mut() {
let tail = conditioner.flush();
if !tail.is_empty() {
let samples = state.gap.fill(elapsed, &tail);
state.write(&samples);
}
}
let zeros = state.gap.pad_to(elapsed);
state.write(&zeros);
state.gap.written()
}
/// Appends `extra` zeros and finalizes the WAV.
fn finish(&self, extra: u64) -> Result<Duration, RecorderError> {
let mut state = self.shared.lock();
state.write(&vec![0.0; extra as usize]);
let writer = state.writer.take();
if let Some(err) = state.error.take() {
return Err(err.into());
}
match writer {
Some(writer) => Ok(writer.finalize()?),
None => Ok(Duration::ZERO),
}
}
fn remove_file(&self) {
// Close the file before deleting it (required on Windows).
drop(self.shared.lock().writer.take());
let _ = fs::remove_file(&self.path);
}
}
/// Pads both tracks every [`PAD_INTERVAL`] until told to stop.
struct PadTimer {
stop: Sender<()>,
thread: JoinHandle<()>,
}
impl PadTimer {
fn spawn(tracks: [Arc<TrackShared>; 2], started: Instant) -> Self {
let (stop, stop_rx) = mpsc::channel::<()>();
let thread = thread::spawn(move || {
while let Err(RecvTimeoutError::Timeout) = stop_rx.recv_timeout(PAD_INTERVAL) {
let elapsed = started.elapsed();
for track in &tracks {
track.pad(elapsed);
}
}
});
Self { stop, thread }
}
fn stop(self) {
let _ = self.stop.send(());
let _ = self.thread.join();
}
}
/// A running two-track recording. Track 0 is "mic", track 1 is "out".
pub struct Recorder {
started: Instant,
tracks: [Track; 2],
timer: Option<PadTimer>,
}
impl Recorder {
/// Creates both WAV files and starts both sources. If one source fails to
/// start, the other keeps recording and the failed track is filled with
/// silence (see [`Recorder::failed_tracks`]); only if both fail is this an
/// error, in which case no files are left behind.
pub fn start(
mic: Box<dyn CaptureSource>,
out: Box<dyn CaptureSource>,
mic_path: &Path,
out_path: &Path,
) -> Result<Recorder, RecorderError> {
let mic = Track::create("mic", mic, mic_path)?;
let out = match Track::create("out", out, out_path) {
Ok(out) => out,
Err(err) => {
mic.remove_file();
return Err(err.into());
}
};
let started = Instant::now();
let mut recorder = Recorder {
started,
tracks: [mic, out],
timer: None,
};
let mic_result = recorder.tracks[0].start(started);
let out_result = recorder.tracks[1].start(started);
if let (Err(mic), Err(out)) = (mic_result, out_result) {
recorder.discard();
return Err(RecorderError::BothSourcesFailed { mic, out });
}
recorder.timer = Some(PadTimer::spawn(
[
recorder.tracks[0].shared.clone(),
recorder.tracks[1].shared.clone(),
],
started,
));
Ok(recorder)
}
/// Current (mic, out) rms levels in `0.0..=1.0`.
pub fn levels(&self) -> (f32, f32) {
(self.tracks[0].shared.level(), self.tracks[1].shared.level())
}
/// Names ("mic" / "out") of tracks whose source failed to start or whose
/// file could not be written.
pub fn failed_tracks(&self) -> Vec<&'static str> {
self.tracks
.iter()
.filter(|t| t.start_failed || t.shared.write_failed.load(Ordering::Relaxed))
.map(|t| t.name)
.collect()
}
/// Stops both sources and finalizes both WAVs to the same length.
/// Returns the recorded duration.
pub fn stop(mut self) -> Result<Duration, RecorderError> {
self.halt();
let elapsed = self.started.elapsed();
let written = [self.tracks[0].drain(elapsed), self.tracks[1].drain(elapsed)];
let longest = written[0].max(written[1]);
let mic = self.tracks[0].finish(longest - written[0]);
let out = self.tracks[1].finish(longest - written[1]);
Ok(mic?.max(out?))
}
/// Stops both sources and deletes both files.
pub fn discard(mut self) {
self.halt();
for track in &self.tracks {
track.remove_file();
}
}
/// Stops the pad timer and both sources. Idempotent.
fn halt(&mut self) {
if let Some(timer) = self.timer.take() {
timer.stop();
}
for track in &mut self.tracks {
track.source.stop();
}
}
}
impl Drop for Recorder {
fn drop(&mut self) {
self.halt();
}
}
#[cfg(test)]
mod tests {
use super::*;
use crate::capture::DataCallback;
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::Arc;
use std::thread::{self, JoinHandle};
use std::time::Instant;
const CHUNK: Duration = Duration::from_millis(20);
/// Test source: a thread that pushes a constant-amplitude 20 ms chunk
/// every 20 ms, except inside the `silent` window (relative to start),
/// where it sends nothing at all.
struct FakeSource {
format: StreamFormat,
amplitude: f32,
silent: Option<(Duration, Duration)>,
fail: bool,
stop: Arc<AtomicBool>,
thread: Option<JoinHandle<()>>,
}
impl FakeSource {
fn new(rate: u32, channels: u16, amplitude: f32) -> Self {
Self {
format: StreamFormat { rate, channels },
amplitude,
silent: None,
fail: false,
stop: Arc::new(AtomicBool::new(false)),
thread: None,
}
}
fn silent_between(mut self, from: Duration, to: Duration) -> Self {
self.silent = Some((from, to));
self
}
fn failing() -> Self {
let mut source = Self::new(16_000, 1, 0.0);
source.fail = true;
source
}
}
impl CaptureSource for FakeSource {
fn start(&mut self, mut on_data: DataCallback) -> Result<StreamFormat, CaptureError> {
if self.fail {
return Err(CaptureError::DeviceNotFound("fake".into()));
}
let format = self.format;
let frames = (format.rate as u128 * CHUNK.as_millis() / 1000) as usize;
let chunk = vec![self.amplitude; frames * format.channels as usize];
let silent = self.silent;
let stop = self.stop.clone();
self.thread = Some(thread::spawn(move || {
let started = Instant::now();
let mut sent = 0u32;
while !stop.load(Ordering::SeqCst) {
let due = CHUNK * (sent + 1);
if let Some(wait) = due.checked_sub(started.elapsed()) {
thread::sleep(wait);
}
sent += 1;
let muted = silent.is_some_and(|(from, to)| due > from && due <= to);
if !muted {
on_data(&chunk);
}
}
}));
Ok(format)
}
fn stop(&mut self) {
self.stop.store(true, Ordering::SeqCst);
if let Some(thread) = self.thread.take() {
thread.join().unwrap();
}
}
}
fn read_wav(path: &Path) -> Vec<i16> {
hound::WavReader::open(path)
.unwrap()
.into_samples::<i16>()
.map(Result::unwrap)
.collect()
}
fn secs(samples: usize) -> f64 {
samples as f64 / 16_000.0
}
#[test]
fn recorder_tracks_equal_length_when_output_silent_gap() {
let dir = tempfile::tempdir().unwrap();
let mic_path = dir.path().join("mic.wav");
let out_path = dir.path().join("out.wav");
let mic = FakeSource::new(48_000, 2, 0.25);
let out = FakeSource::new(16_000, 1, 0.25)
.silent_between(Duration::from_millis(200), Duration::from_millis(1_200));
let started = Instant::now();
let recorder = Recorder::start(Box::new(mic), Box::new(out), &mic_path, &out_path).unwrap();
thread::sleep(Duration::from_millis(1_500));
let duration = recorder.stop().unwrap();
let wall = started.elapsed().as_secs_f64();
let mic_samples = read_wav(&mic_path);
let out_samples = read_wav(&out_path);
assert!(
(secs(mic_samples.len()) - secs(out_samples.len())).abs() <= 0.05,
"mic {} s vs out {} s",
secs(mic_samples.len()),
secs(out_samples.len())
);
assert!(
(duration.as_secs_f64() - wall).abs() < 0.15,
"duration {duration:?} vs wall clock {wall} s"
);
// The gap sits where it happened: silence well inside the window,
// signal again after it.
let window = &out_samples[(0.4 * 16_000.0) as usize..(1.0 * 16_000.0) as usize];
assert!(window.iter().all(|&s| s == 0), "gap must be silence");
let after = &out_samples[(1.35 * 16_000.0) as usize..(1.45 * 16_000.0) as usize];
assert!(
after.iter().any(|&s| s != 0),
"signal must resume after the gap"
);
}
#[test]
fn recorder_discard_deletes_files() {
let dir = tempfile::tempdir().unwrap();
let mic_path = dir.path().join("mic.wav");
let out_path = dir.path().join("out.wav");
let recorder = Recorder::start(
Box::new(FakeSource::new(16_000, 1, 0.1)),
Box::new(FakeSource::new(16_000, 1, 0.1)),
&mic_path,
&out_path,
)
.unwrap();
thread::sleep(Duration::from_millis(200));
assert!(mic_path.exists() && out_path.exists());
recorder.discard();
assert!(!mic_path.exists());
assert!(!out_path.exists());
}
#[test]
fn recorder_levels_reflect_input() {
let dir = tempfile::tempdir().unwrap();
let recorder = Recorder::start(
Box::new(FakeSource::new(16_000, 1, 0.5)),
Box::new(FakeSource::new(48_000, 2, 0.0)),
&dir.path().join("mic.wav"),
&dir.path().join("out.wav"),
)
.unwrap();
thread::sleep(Duration::from_millis(300));
let (mic, out) = recorder.levels();
recorder.stop().unwrap();
assert!((mic - 0.5).abs() < 0.05, "mic level {mic}");
assert!(out < 0.01, "out level {out}");
}
#[test]
fn recorder_pads_a_silent_track_while_running() {
let dir = tempfile::tempdir().unwrap();
let out = FakeSource::new(16_000, 1, 0.25)
.silent_between(Duration::from_millis(100), Duration::from_secs(60));
let recorder = Recorder::start(
Box::new(FakeSource::new(16_000, 1, 0.25)),
Box::new(out),
&dir.path().join("mic.wav"),
&dir.path().join("out.wav"),
)
.unwrap();
thread::sleep(Duration::from_millis(50));
let (_, out_before) = recorder.levels();
thread::sleep(Duration::from_millis(700));
let (_, out_after) = recorder.levels();
recorder.stop().unwrap();
assert!(out_before > 0.2, "out level before the gap {out_before}");
assert_eq!(out_after, 0.0, "timer padding resets the level");
}
#[test]
fn recorder_out_start_failure_keeps_mic_and_marks_failed() {
let dir = tempfile::tempdir().unwrap();
let mic_path = dir.path().join("mic.wav");
let out_path = dir.path().join("out.wav");
let recorder = Recorder::start(
Box::new(FakeSource::new(16_000, 1, 0.25)),
Box::new(FakeSource::failing()),
&mic_path,
&out_path,
)
.unwrap();
thread::sleep(Duration::from_millis(400));
assert_eq!(recorder.failed_tracks(), vec!["out"]);
let duration = recorder.stop().unwrap();
let mic_samples = read_wav(&mic_path);
let out_samples = read_wav(&out_path);
assert_eq!(mic_samples.len(), out_samples.len());
assert!(duration >= Duration::from_millis(350), "{duration:?}");
assert!(mic_samples.iter().any(|&s| s != 0), "mic keeps recording");
assert!(
out_samples.iter().all(|&s| s == 0),
"failed track is silence"
);
}
#[test]
fn recorder_fails_when_both_sources_fail() {
let dir = tempfile::tempdir().unwrap();
let mic_path = dir.path().join("mic.wav");
let out_path = dir.path().join("out.wav");
let result = Recorder::start(
Box::new(FakeSource::failing()),
Box::new(FakeSource::failing()),
&mic_path,
&out_path,
);
assert!(matches!(
result,
Err(RecorderError::BothSourcesFailed { .. })
));
assert!(!mic_path.exists() && !out_path.exists());
}
}