audio_samples 2.0.0

A typed audio processing library for Rust that treats audio as a first-class, invariant-preserving object rather than an unstructured numeric buffer.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67

//! Opus codec: SILK (speech), CELT (music), and Hybrid modes.
//!
//! ## Overview
//!
//! This module implements the Opus codec (RFC 6716) within the `audio_samples`
//! perceptual codec framework. It is gated on the `opus-codec` feature flag.
//!
//! | Module | Purpose |
//! |--------|---------|
//! | [`lpc`](crate::codecs::opus::lpc) | Levinson–Durbin LPC analysis/synthesis, pitch estimation, LTP primitives. |
//! | [`mode`](crate::codecs::opus::mode) | `OpusMode`, `OpusBandwidth`, `OpusConfig`, and `detect_mode`. |
//! | [`silk`](crate::codecs::opus::silk) | SILK frame encode/decode: stateful LPC + LTP + 16-bit quantisation. |
//! | [`celt`](crate::codecs::opus::celt) | CELT frame encode/decode: delegates to the psychoacoustic pipeline. |
//! | [`hybrid`](crate::codecs::opus::hybrid) | Hybrid mode: SILK low band + CELT high band with IIR crossover. |
//! | [`stereo`](crate::codecs::opus::stereo) | M/S stereo codec [`OpusStereoCodec`](crate::codecs::opus::OpusStereoCodec). |
//! | [`codec`](crate::codecs::opus::codec) | [`OpusCodec`](crate::codecs::opus::OpusCodec) and [`OpusEncodedAudio`](crate::codecs::opus::OpusEncodedAudio) — the public entry points. |
//!
//! ## Design
//!
//! - **CELT** reuses the existing [`crate::codecs::perceptual`] pipeline:
//!   MDCT → psychoacoustic masking → bit allocation → scalar quantisation.
//!
//! - **SILK** uses new LPC primitives in [`lpc`](crate::codecs::opus::lpc) with cross-frame state and a
//!   single-tap long-term predictor (LTP).
//!
//! - **Hybrid** splits the signal at 8 kHz via a first-order IIR crossover
//!   (perfect reconstruction), encodes the low band with SILK and the high band
//!   with CELT, and sums on decode.
//!
//! - [`OpusCodec`](crate::codecs::opus::OpusCodec) segments audio into fixed-length frames and dispatches each
//!   to SILK, CELT, or Hybrid based on [`OpusConfig`](crate::codecs::opus::OpusConfig) or per-frame detection.
//!
//! ## What lives in the IO crate
//!
//! Bitstream packing (range coding, Ogg/RIFF containers) and `.opus` file I/O
//! are responsibilities of `audio_samples_io`. This module provides only the
//! algorithmic core: analysis, quantisation, and reconstruction.
//!
//! ## Remaining limitations
//!
//! - **No cross-frame LTP state** — LTP synthesis restarts at zero each frame.
//! - **No range/arithmetic coding** — residuals are stored as raw `Vec<i16>`.

pub mod celt;
pub mod codec;
pub mod hybrid;
pub mod lpc;
pub mod mode;
pub mod silk;
pub mod stereo;

pub use celt::{CeltEncodedFrame, celt_decode_frame, celt_encode_frame};
pub use codec::{OpusCodec, OpusEncodedAudio, OpusEncodedFrame, OpusFrameData};
pub use hybrid::{
    HYBRID_CROSSOVER_HZ, HybridEncodedFrame, hybrid_decode_frame, hybrid_encode_frame,
};
pub use lpc::{
    LpcCoefficients, SILK_LPC_ORDER, compute_autocorrelation, estimate_pitch, levinson_durbin,
    lpc_analysis, lpc_residual, lpc_residual_stateful, lpc_synthesis, lpc_synthesis_stateful,
    ltp_residual, ltp_synthesis,
};
pub use mode::{OpusBandwidth, OpusConfig, OpusMode, detect_mode};
pub use silk::{
    SilkEncodedFrame, SilkState, silk_decode_frame, silk_decode_frame_stateful, silk_encode_frame,
    silk_encode_frame_stateful,
};
pub use stereo::{OpusStereoCodec, OpusStereoEncodedAudio};