flexaudio_core/lib.rs
1//! flexaudio-core — OS-independent core.
2//!
3//! The OS-independent part of the desktop audio capture abstraction library `flexaudio`.
4//! Provides ring buffers, sample-rate conversion, channel mixing, 20 ms chunking, clock normalization,
5//! events, and type definitions. OS-specific capture is implemented by separate `flexaudio-os-*`
6//! crates that implement [`backend::CaptureBackend`], which the facade layer wires to the core.
7//!
8//! # Fixed contract
9//! All internal processing uses interleaved `f32` / 48000 Hz / stereo 2ch / 20 ms = 960
10//! frames/chunk. [`OutputFormat`] can change the external rate/channels (the Normalizer's second
11//! stage resamples; e.g. 16k/1ch gives 320 frames/chunk). Output chunks remain 20 ms regardless of rate.
12//!
13//! The public API has no callbacks. RT threads only push; consumers poll.
14//! The RT path never blocks (DROP_OLDEST / overflow drop when full). PTS comes from the device
15//! and gaps are detected.
16//!
17//! # Two-stage ring-buffer layout
18//! ```text
19//! [RT cb] --push--> RawRing (rtrb, RT-safe) --pop--> [ingest/process thread]
20//! |
21//! Normalizer (mix + rubato SRC + 960-frame slicing)
22//! |
23//! v
24//! ChunkRing (ringbuf, DROP_OLDEST) --try_pop--> [poll]
25//! ```
26
27#![warn(missing_docs)]
28
29pub mod backend;
30pub mod chunk_ring;
31pub mod clock;
32pub mod normalizer;
33pub mod process_list;
34pub mod quant;
35pub mod raw_ring;
36pub mod secondary_ring;
37pub mod types;
38
39// Re-export the main types at the crate root.
40pub use backend::{CaptureBackend, RawSink};
41pub use chunk_ring::{chunk_ring, ChunkConsumer, ChunkProducer};
42pub use clock::{monotonic_now_ns, ClockNormalizer};
43pub use normalizer::{InnerProcessor, Normalizer, CHUNK_FRAMES};
44pub use quant::quantize_i16;
45pub use raw_ring::{raw_ring, RawConsumer, RawProducer};
46pub use secondary_ring::{secondary_chunk_ring, SecondaryChunkConsumer, SecondaryChunkProducer};
47pub use types::{
48 AudioChunk, ChunkFlags, DeviceEvent, DeviceInfo, Error, Event, OutputFormat, ProcessInfo,
49 Result, SecondaryChunk, SourceKind, StreamConfig, CHANNELS, SAMPLE_RATE,
50};