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
+8
View File
@@ -9,3 +9,11 @@ path = "src/lib.rs"
[dependencies]
recorder-core = { path = "../core" }
log = "0.4"
[target.'cfg(target_os = "linux")'.dependencies]
libpulse-binding = "2.30"
libpulse-simple-binding = "2.29"
[target.'cfg(windows)'.dependencies]
wasapi = "0.26"
+84
View File
@@ -0,0 +1,84 @@
//! The dedicated thread every platform capture source runs on.
//!
//! Platform stream handles (COM interfaces, PulseAudio connections) are not
//! `Send`, so they are created, used and dropped on this one thread. The
//! thread reports whether the stream opened through a channel, which lets
//! `CaptureSource::start` return that result synchronously.
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::mpsc::{self, Receiver, RecvTimeoutError, SyncSender};
use std::sync::Arc;
use std::thread::{self, JoinHandle};
use std::time::Duration;
use recorder_core::capture::{CaptureError, StreamFormat};
/// How long `stop` waits for the thread before detaching it. Only reached if
/// a platform call blocks indefinitely; stopping must never hang the app.
const STOP_TIMEOUT: Duration = Duration::from_secs(2);
/// Sends the outcome of opening the stream back to `start`.
pub(crate) type Ready = SyncSender<Result<StreamFormat, CaptureError>>;
pub(crate) struct CaptureThread {
stop: Arc<AtomicBool>,
/// Disconnects when the thread ends (its sender is dropped with it).
done: Receiver<()>,
handle: JoinHandle<()>,
}
impl CaptureThread {
/// Spawns `body` on a new thread and waits until it has reported the
/// stream format (or an error) through `ready`. `body` must return soon
/// after the stop flag it is given is set.
pub(crate) fn spawn<F>(name: &str, body: F) -> Result<(Self, StreamFormat), CaptureError>
where
F: FnOnce(&AtomicBool, Ready) + Send + 'static,
{
let stop = Arc::new(AtomicBool::new(false));
let (ready_tx, ready_rx) = mpsc::sync_channel(1);
let (done_tx, done_rx) = mpsc::channel::<()>();
let thread_stop = stop.clone();
let handle = thread::Builder::new()
.name(name.to_string())
.spawn(move || {
let _done = done_tx;
body(&thread_stop, ready_tx);
})
.map_err(|err| CaptureError::Backend(format!("cannot spawn capture thread: {err}")))?;
match ready_rx.recv() {
Ok(Ok(format)) => Ok((
Self {
stop,
done: done_rx,
handle,
},
format,
)),
Ok(Err(err)) => {
let _ = handle.join();
Err(err)
}
Err(_) => {
let _ = handle.join();
Err(CaptureError::Backend(
"capture thread ended before the stream opened".into(),
))
}
}
}
/// Signals the thread to stop and waits for it to end.
pub(crate) fn stop(self) {
self.stop.store(true, Ordering::SeqCst);
match self.done.recv_timeout(STOP_TIMEOUT) {
Err(RecvTimeoutError::Timeout) => {
log::warn!("capture thread did not stop in time; detaching it");
}
_ => {
let _ = self.handle.join();
}
}
}
}
+21 -3
View File
@@ -1,4 +1,22 @@
//! Audio capture and encoding for the Gesprächsrekorder call recorder.
//! Platform audio capture for the Gesprächsrekorder call recorder.
//!
//! Intentionally near-empty for now; audio device enumeration, capture and
//! WAV/FLAC encoding land in a later task.
//! Implements [`recorder_core::capture::CaptureSource`] for the microphone and
//! for the call app's audio output: WASAPI on Windows, PulseAudio on Linux.
//! The platform-neutral trait, types and the two-track recorder live in
//! `recorder-core`.
mod capture_thread;
#[cfg(target_os = "linux")]
mod linux {
pub mod capture;
}
#[cfg(target_os = "linux")]
pub use linux::capture::{list_devices, mic_source, output_source};
#[cfg(windows)]
mod windows {
pub mod capture;
}
#[cfg(windows)]
pub use windows::capture::{list_devices, mic_source, output_source};
+154
View File
@@ -0,0 +1,154 @@
//! PulseAudio (and PipeWire via pipewire-pulse) capture with libpulse-simple.
//!
//! Streams are opened directly as 16 kHz mono `f32`, so the server does the
//! resampling and downmix and the recorder's conditioner passes them through.
//! The call output is recorded from the default sink's monitor source;
//! per-process capture does not exist here, so `OutputTarget::Process` falls
//! back to that monitor as well.
use std::sync::atomic::{AtomicBool, Ordering};
use libpulse_binding::def::BufferAttr;
use libpulse_binding::error::{Code, PAErr};
use libpulse_binding::sample::{Format, Spec};
use libpulse_binding::stream::Direction;
use libpulse_simple_binding::Simple;
use recorder_core::capture::{
CaptureError, CaptureSource, DataCallback, Devices, OutputTarget, StreamFormat,
};
use crate::capture_thread::{CaptureThread, Ready};
const APP_NAME: &str = "Gesprächsrekorder";
const DEFAULT_MONITOR: &str = "@DEFAULT_MONITOR@";
const FORMAT: StreamFormat = StreamFormat {
rate: 16_000,
channels: 1,
};
/// Samples per blocking read (20 ms). Also bounds how long `stop` waits.
const CHUNK_SAMPLES: usize = 320;
const CHUNK_BYTES: usize = CHUNK_SAMPLES * std::mem::size_of::<f32>();
/// A PulseAudio record stream on one source (microphone or monitor).
pub struct PulseSource {
/// Source name; `None` for the server's default source.
device: Option<String>,
stream_name: &'static str,
thread: Option<CaptureThread>,
}
pub fn mic_source(device: Option<&str>) -> Box<dyn CaptureSource> {
Box::new(PulseSource {
device: device.map(str::to_owned),
stream_name: "Mikrofon",
thread: None,
})
}
pub fn output_source(target: OutputTarget) -> Box<dyn CaptureSource> {
let device = match target {
OutputTarget::Process { .. } | OutputTarget::DefaultRender => DEFAULT_MONITOR.to_owned(),
OutputTarget::Device(name) => name,
};
Box::new(PulseSource {
device: Some(device),
stream_name: "Gesprächsaudio",
thread: None,
})
}
/// Device enumeration is not offered on Linux; recordings use the defaults.
pub fn list_devices() -> Devices {
Devices::default()
}
impl CaptureSource for PulseSource {
fn start(&mut self, on_data: DataCallback) -> Result<StreamFormat, CaptureError> {
self.stop();
let device = self.device.clone();
let stream_name = self.stream_name;
let (thread, format) =
CaptureThread::spawn(&format!("pulse {stream_name}"), move |stop, ready| {
run(device.as_deref(), stream_name, stop, ready, on_data)
})?;
self.thread = Some(thread);
Ok(format)
}
fn stop(&mut self) {
if let Some(thread) = self.thread.take() {
thread.stop();
}
}
}
impl Drop for PulseSource {
fn drop(&mut self) {
self.stop();
}
}
fn open(device: Option<&str>, stream_name: &str) -> Result<Simple, CaptureError> {
let spec = Spec {
format: Format::FLOAT32NE,
rate: FORMAT.rate,
channels: FORMAT.channels as u8,
};
let attr = BufferAttr {
maxlength: u32::MAX,
tlength: u32::MAX,
prebuf: u32::MAX,
minreq: u32::MAX,
fragsize: CHUNK_BYTES as u32,
};
Simple::new(
None,
APP_NAME,
Direction::Record,
device,
stream_name,
&spec,
None,
Some(&attr),
)
.map_err(|err| to_capture_error(err, device))
}
fn to_capture_error(err: PAErr, device: Option<&str>) -> CaptureError {
match (Code::try_from(err), device) {
(Ok(Code::NoEntity), Some(device)) => CaptureError::DeviceNotFound(device.to_owned()),
_ => CaptureError::Backend(format!("PulseAudio: {err}")),
}
}
fn run(
device: Option<&str>,
stream_name: &str,
stop: &AtomicBool,
ready: Ready,
mut on_data: DataCallback,
) {
let simple = match open(device, stream_name) {
Ok(simple) => simple,
Err(err) => {
let _ = ready.send(Err(err));
return;
}
};
let _ = ready.send(Ok(FORMAT));
let mut bytes = vec![0u8; CHUNK_BYTES];
let mut samples = vec![0f32; CHUNK_SAMPLES];
while !stop.load(Ordering::SeqCst) {
if let Err(err) = simple.read(&mut bytes) {
// Source gone (unplugged, server restart): stop delivering; the
// recorder keeps the track aligned with silence.
log::warn!("PulseAudio capture '{stream_name}' ended: {err}");
return;
}
for (sample, raw) in samples.iter_mut().zip(bytes.as_chunks::<4>().0) {
*sample = f32::from_ne_bytes(*raw);
}
on_data(&samples);
}
}
+327
View File
@@ -0,0 +1,327 @@
//! WASAPI capture (shared mode, event driven) via the `wasapi` crate.
//!
//! - Microphone: the default *communications* capture endpoint, or the
//! endpoint with the given device id.
//! - Output, `Process`: application loopback of the call app's process tree
//! (Windows 10 2004+), so only the call's audio is recorded.
//! - Output, `DefaultRender` / `Device`: loopback of the default
//! communications render endpoint / of the given render endpoint.
//!
//! All streams are delivered as interleaved `f32`. When the endpoint goes
//! away mid-recording (`AUDCLNT_E_DEVICE_INVALIDATED`, e.g. a headset was
//! unplugged), the source reopens the default endpoint once, in the original
//! format so the recorder's conditioner stays valid. If that fails, it stops
//! delivering data and the recorder pads the track with silence.
use std::sync::atomic::{AtomicBool, Ordering};
use std::thread;
use recorder_core::capture::{
CaptureError, CaptureSource, DataCallback, DeviceInfo, Devices, OutputTarget, StreamFormat,
};
use wasapi::{
deinitialize, initialize_mta, AudioCaptureClient, AudioClient, Device, DeviceEnumerator,
Direction, Handle, Role, SampleType, StreamMode, WasapiError, WaveFormat,
};
use crate::capture_thread::{CaptureThread, Ready};
/// `AUDCLNT_E_DEVICE_INVALIDATED`: the endpoint was removed or disabled.
const AUDCLNT_E_DEVICE_INVALIDATED: i32 = 0x8889_0004_u32 as i32;
/// Format requested for application loopback, which has no mix format.
const PROCESS_LOOPBACK_FORMAT: StreamFormat = StreamFormat {
rate: 48_000,
channels: 2,
};
/// Shared-mode buffer size (100 ns units): 200 ms of headroom so a slow
/// disk write in the recorder does not overflow the capture buffer.
const BUFFER_DURATION_HNS: i64 = 2_000_000;
/// Event wait timeout (ms). Loopback endpoints signal no events while
/// nothing plays, so the loop wakes up regularly to check the stop flag and
/// to notice an invalidated device.
const WAIT_MS: u32 = 100;
#[derive(Debug, Clone)]
enum Endpoint {
/// Capture endpoint id; `None` for the default communications endpoint.
Mic(Option<String>),
Output(OutputTarget),
}
impl Endpoint {
/// What to reopen after the endpoint was invalidated.
fn fallback(&self) -> Endpoint {
match self {
Endpoint::Mic(_) => Endpoint::Mic(None),
Endpoint::Output(OutputTarget::Process { .. }) => self.clone(),
Endpoint::Output(_) => Endpoint::Output(OutputTarget::DefaultRender),
}
}
fn label(&self) -> &'static str {
match self {
Endpoint::Mic(_) => "mic",
Endpoint::Output(_) => "out",
}
}
}
pub struct WasapiSource {
endpoint: Endpoint,
thread: Option<CaptureThread>,
}
pub fn mic_source(device: Option<&str>) -> Box<dyn CaptureSource> {
Box::new(WasapiSource {
endpoint: Endpoint::Mic(device.map(str::to_owned)),
thread: None,
})
}
pub fn output_source(target: OutputTarget) -> Box<dyn CaptureSource> {
Box::new(WasapiSource {
endpoint: Endpoint::Output(target),
thread: None,
})
}
/// Active capture (inputs) and render (outputs) endpoints. Enumerated on a
/// fresh thread so COM is initialised the way this code expects,
/// independent of the caller's apartment. Errors yield empty lists.
pub fn list_devices() -> Devices {
thread::spawn(|| {
if initialize_mta().is_err() {
return Devices::default();
}
let devices = Devices {
inputs: endpoints(&Direction::Capture),
outputs: endpoints(&Direction::Render),
};
deinitialize();
devices
})
.join()
.unwrap_or_default()
}
fn endpoints(direction: &Direction) -> Vec<DeviceInfo> {
let collection = match DeviceEnumerator::new()
.and_then(|enumerator| enumerator.get_device_collection(direction))
{
Ok(collection) => collection,
Err(err) => {
log::warn!("cannot enumerate {direction} devices: {err}");
return Vec::new();
}
};
(&collection)
.into_iter()
.filter_map(|device| {
let device = device.ok()?;
Some(DeviceInfo {
id: device.get_id().ok()?,
name: device.get_friendlyname().ok()?,
})
})
.collect()
}
impl CaptureSource for WasapiSource {
fn start(&mut self, on_data: DataCallback) -> Result<StreamFormat, CaptureError> {
self.stop();
let endpoint = self.endpoint.clone();
let (thread, format) = CaptureThread::spawn(
&format!("wasapi {}", endpoint.label()),
move |stop, ready| run(endpoint, stop, ready, on_data),
)?;
self.thread = Some(thread);
Ok(format)
}
fn stop(&mut self) {
if let Some(thread) = self.thread.take() {
thread.stop();
}
}
}
impl Drop for WasapiSource {
fn drop(&mut self) {
self.stop();
}
}
/// An opened, started WASAPI capture stream. Lives on the capture thread.
struct Stream {
client: AudioClient,
capture: AudioCaptureClient,
event: Handle,
format: StreamFormat,
}
impl Drop for Stream {
fn drop(&mut self) {
let _ = self.client.stop_stream();
}
}
fn backend(err: WasapiError) -> CaptureError {
CaptureError::Backend(format!("WASAPI: {err}"))
}
fn is_device_invalidated(err: &WasapiError) -> bool {
matches!(err, WasapiError::Windows(e) if e.code().0 == AUDCLNT_E_DEVICE_INVALIDATED)
}
fn device_by_id(enumerator: &DeviceEnumerator, id: &str) -> Result<Device, CaptureError> {
enumerator
.get_device(id)
.map_err(|_| CaptureError::DeviceNotFound(id.to_owned()))
}
/// Opens `endpoint` and starts streaming. `format` forces a stream format
/// (used when reopening); otherwise the endpoint's mix format is used, with
/// the samples converted to `f32` by the audio engine.
fn open(endpoint: &Endpoint, format: Option<StreamFormat>) -> Result<Stream, CaptureError> {
let mut client = match endpoint {
Endpoint::Output(OutputTarget::Process { root_pid }) => {
AudioClient::new_application_loopback_client(*root_pid, true).map_err(backend)?
}
_ => {
let enumerator = DeviceEnumerator::new().map_err(backend)?;
let device = match endpoint {
Endpoint::Mic(Some(id)) | Endpoint::Output(OutputTarget::Device(id)) => {
device_by_id(&enumerator, id)?
}
Endpoint::Mic(None) => enumerator
.get_default_device_for_role(&Direction::Capture, &Role::Communications)
.map_err(backend)?,
Endpoint::Output(_) => enumerator
.get_default_device_for_role(&Direction::Render, &Role::Communications)
.map_err(backend)?,
};
device.get_iaudioclient().map_err(backend)?
}
};
let format = match (format, endpoint) {
(Some(format), _) => format,
(None, Endpoint::Output(OutputTarget::Process { .. })) => PROCESS_LOOPBACK_FORMAT,
(None, _) => {
let mix = client.get_mixformat().map_err(backend)?;
StreamFormat {
rate: mix.get_samplespersec(),
channels: mix.get_nchannels(),
}
}
};
let wave_format = WaveFormat::new(
32,
32,
&SampleType::Float,
format.rate as usize,
format.channels as usize,
None,
);
let mode = StreamMode::EventsShared {
autoconvert: true,
buffer_duration_hns: BUFFER_DURATION_HNS,
};
// Capture on a capture endpoint records it; on a render endpoint (and on
// the application loopback client) it sets up loopback capture.
client
.initialize_client(&wave_format, &Direction::Capture, &mode)
.map_err(backend)?;
let event = client.set_get_eventhandle().map_err(backend)?;
let capture = client.get_audiocaptureclient().map_err(backend)?;
client.start_stream().map_err(backend)?;
Ok(Stream {
client,
capture,
event,
format,
})
}
fn run(endpoint: Endpoint, stop: &AtomicBool, ready: Ready, on_data: DataCallback) {
if let Err(err) = initialize_mta().ok() {
let _ = ready.send(Err(CaptureError::Backend(format!(
"COM initialisation failed: {err}"
))));
return;
}
capture(&endpoint, stop, ready, on_data);
// Every COM object is dropped by now.
deinitialize();
}
fn capture(endpoint: &Endpoint, stop: &AtomicBool, ready: Ready, mut on_data: DataCallback) {
let mut stream = match open(endpoint, None) {
Ok(stream) => stream,
Err(err) => {
let _ = ready.send(Err(err));
return;
}
};
let format = stream.format;
let _ = ready.send(Ok(format));
let label = endpoint.label();
let mut reopened = false;
let mut bytes = Vec::new();
let mut samples = Vec::new();
while !stop.load(Ordering::SeqCst) {
// A timeout is normal (silent loopback); drain regardless, which
// also surfaces an invalidated device.
let _ = stream.event.wait_for_event(WAIT_MS);
let Err(err) = drain(&stream, &mut bytes, &mut samples, &mut on_data) else {
continue;
};
if !is_device_invalidated(&err) || reopened {
log::warn!("WASAPI capture '{label}' ended: {err}");
return;
}
reopened = true;
log::warn!("WASAPI capture '{label}': device invalidated, reopening the default device");
drop(stream);
stream = match open(&endpoint.fallback(), Some(format)) {
Ok(stream) => stream,
Err(err) => {
log::warn!("WASAPI capture '{label}': reopening failed: {err}");
return;
}
};
}
}
/// Delivers every packet currently queued in the capture buffer.
fn drain(
stream: &Stream,
bytes: &mut Vec<u8>,
samples: &mut Vec<f32>,
on_data: &mut DataCallback,
) -> Result<(), WasapiError> {
let block_align = stream.format.channels as usize * std::mem::size_of::<f32>();
loop {
let frames = stream.capture.get_next_packet_size()?.unwrap_or(0) as usize;
if frames == 0 {
return Ok(());
}
bytes.resize(frames * block_align, 0);
let (read, info) = stream.capture.read_from_device(bytes)?;
let len = read as usize * stream.format.channels as usize;
samples.clear();
if info.flags.silent {
samples.resize(len, 0.0);
} else {
samples.extend(
bytes.as_chunks::<4>().0[..len]
.iter()
.map(|raw| f32::from_le_bytes(*raw)),
);
}
if !samples.is_empty() {
on_data(samples);
}
}
}