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 diagnostics;
33pub mod error_context;
34mod errors;
35mod loss;
36pub mod normalizer;
37pub mod process_list;
38pub mod quant;
39pub mod raw_ring;
40pub mod secondary_ring;
41pub mod types;
42mod whisper_error;
43
44// Re-export the main types at the crate root.
45pub use backend::{CaptureBackend, RawSink};
46pub use chunk_ring::{chunk_ring, ChunkConsumer, ChunkProducer};
47pub use clock::{monotonic_now_ns, ClockNormalizer};
48pub use normalizer::{InnerProcessor, NormalizedChunk, Normalizer, CHUNK_FRAMES};
49pub use quant::quantize_i16;
50pub use raw_ring::{raw_ring, RawConsumer, RawProducer};
51pub use secondary_ring::{secondary_chunk_ring, SecondaryChunkConsumer, SecondaryChunkProducer};
52pub use types::{
53 AudioChunk, AudioLoss, AudioPath, ChunkFlags, DefaultDeviceKind, DeviceEvent, DeviceInfo,
54 Error, ErrorContext, ErrorGroup, ErrorKind, Event, LossReason, MixLane, NativeStatus,
55 Operation, OutputFormat, OutputTap, Permission, ProcessInfo, Result, SecondaryChunk,
56 ShutdownReport, SourceKind, StreamConfig, CHANNELS, SAMPLE_RATE,
57};
58
59pub use diagnostics::CaptureDiagnostics;
60pub use whisper_error::WhisperCode;