dsp_spectral/lib.rs
1//! Spectral audio analysis and restoration — STFT/ISTFT, mel/MFCC features,
2//! spectral gating, HPSS source separation.
3//!
4//! `dsp-spectral` is the estate's **L1** audio layer: the analysis and
5//! restoration vocabulary that noise-reduction tools, voice activity
6//! detectors, speech front ends, and audio-restoration pipelines are built
7//! from. The numerical kernels (radix-2 FFT, cosine-sum windows, dB
8//! conversion) are owned by [`dsp_core`] (L0); this crate owns the framing,
9//! the spectral algebra on top, and the restoration primitives.
10//!
11//! # Design
12//!
13//! - **Analysis–synthesis is exact.** `istft(stft(x), x.len()) == x` to
14//! better than 1e-10, for every window and hop, because the inverse
15//! divides by the *measured* per-sample squared-window overlap instead of a
16//! constant COLA divisor. See [`stft`].
17//! - **f64 throughout**, matching `dsp-core`; f32 is a consumer concern.
18//! - **Typed errors, never panics.** Every fallible entry point returns
19//! [`SpectralError`]; the crate denies `clippy::unwrap_used`, `expect_used`,
20//! `panic`, and `indexing_slicing`, so an untrusted buffer (a decoded
21//! media file, a live capture) can only produce a typed error.
22//! - **Feature definitions are pinned.** Each descriptor is spelled out in
23//! its own module docs and checked against a naive `O(N·M)` reference
24//! implementation in the test suite to 1e-9.
25//! - **Composable restoration.** [`spectral_gate`], [`spectral_subtract`],
26//! [`harmonic_percussive_split`], and [`spectral_smooth`] all preserve the
27//! framing, so they chain freely.
28//! - **Verified.** proptest round-trips over 200 arbitrary
29//! signal/config pairs and bounds-checks the feature invariants over 300
30//! cases each; the `spectral_fuzz` cargo-fuzz target feeds arbitrary bytes
31//! as samples and arbitrary configs through the whole pipeline.
32//!
33//! # Example
34//!
35//! Denoise a noisy recording, then read out its spectral character:
36//!
37//! ```
38//! use dsp_spectral::{
39//! GateConfig, NoiseProfile, denoise, mel_frequencies, mfcc, snr_db, spectral_centroid,
40//! spectral_flatness, stft, StftConfig,
41//! };
42//!
43//! let fs = 16_000.0;
44//! let cfg = StftConfig::new(512, 128).with_sample_rate(fs);
45//! let n = 4_096;
46//!
47//! // A 500 Hz tone, and a deterministic uniform-noise generator.
48//! let clean: Vec<f64> = (0..n)
49//! .map(|i| 0.5 * (core::f64::consts::TAU * 500.0 * i as f64 / fs).sin())
50//! .collect();
51//! let mut next_noise = |seed: u64| {
52//! let mut s = seed;
53//! move || {
54//! s = s.wrapping_mul(6_364_136_223_846_793_005).wrapping_add(1);
55//! 0.02 * (((s >> 11) as f64 / (1u64 << 53) as f64) * 2.0 - 1.0)
56//! }
57//! };
58//!
59//! // Profile the noise from a noise-only segment, then gate. The profile
60//! // must come from noise at the same level as the noise being removed, or
61//! // the gate has nothing to compare against.
62//! let mut r = next_noise(0xA11CE);
63//! let noise_only: Vec<f64> = (0..n).map(|_| r()).collect();
64//! let profile = NoiseProfile::estimate(&noise_only, &cfg).expect("valid config");
65//! let mut r = next_noise(0xB0B);
66//! let noisy: Vec<f64> = clean.iter().zip((0..n).map(|_| r())).map(|(a, b)| a + b).collect();
67//!
68//! let gate = GateConfig {
69//! threshold_db: -3.0,
70//! reduction_db: -18.0,
71//! smoothing_frames: 3,
72//! };
73//! let restored = denoise(&noisy, &cfg, &profile, &gate).expect("valid");
74//! assert_eq!(restored.len(), noisy.len());
75//!
76//! // The point of the whole crate: the restoration measurably helps.
77//! let before = snr_db(&clean, &noisy);
78//! let after = snr_db(&clean, &restored);
79//! assert!(after > before, "SNR {before} dB -> {after} dB");
80//!
81//! // A lone tone centres on its own frequency and is far from flat.
82//! let tone = stft(&clean, &cfg).expect("valid");
83//! let centroid = spectral_centroid(&tone, fs);
84//! // The first and last frames are half zero-padded (`center: true`), which
85//! // smears the tone's sidelobes, so the tight claim is made on the interior.
86//! let interior = ¢roid[1..centroid.len() - 1];
87//! assert!(
88//! interior.iter().all(|c| (c - 500.0).abs() < 160.0),
89//! "centroid {centroid:?}"
90//! );
91//! // Broadband noise pulls the centroid up and the flatness toward 1, so the
92//! // restored signal must sit between the clean tone and the noisy input.
93//! let restored_centroid = spectral_centroid(&stft(&restored, &cfg).expect("valid"), fs);
94//! let noisy_centroid = spectral_centroid(&stft(&noisy, &cfg).expect("valid"), fs);
95//! let mean = |v: &[f64]| v.iter().sum::<f64>() / v.len() as f64;
96//! assert!(
97//! mean(&restored_centroid) < mean(&noisy_centroid),
98//! "restoration should pull the centroid back toward the tone"
99//! );
100//! assert!(
101//! spectral_flatness(&tone).iter().all(|f| (0.0..0.5).contains(f)),
102//! "a pure tone is never flat"
103//! );
104//!
105//! // Mel/MFCC front end.
106//! assert_eq!(mel_frequencies(26, 20.0, 7_800.0).len(), 26);
107//! let spec = stft(&restored, &cfg).expect("valid");
108//! let bank = spec.mel_filterbank(26, 20.0, 7_800.0, fs);
109//! let coeffs = mfcc(&bank.energies(spec.frame(0).expect("in range")), 13);
110//! assert_eq!(coeffs.len(), 13);
111//! ```
112//!
113//! # Modules
114//!
115//! | Module | Contents |
116//! |---|---|
117//! | [`stft`] | [`stft`] / [`istft`] / [`Spectrum`], frame layout, time-scale helper |
118//! | [`config`] | [`StftConfig`] — window, hop, transform size, centring, overlap |
119//! | [`window`] | [`Window`] — Hann, Hamming, Blackman, Blackman–Harris, flat top, rectangular |
120//! | [`features`] | centroid, bandwidth, flatness, rolloff, flux, zero-crossing rate |
121//! | [`dct`] | standalone orthonormal DCT-II |
122//! | [`mel`] | [`MelBank`], mel scale, MFCC (DCT-II), real cepstrum |
123//! | [`restore`] | [`NoiseProfile`], [`spectral_gate`], [`spectral_subtract`], [`harmonic_percussive_split`], [`spectral_smooth`], [`denoise`] |
124//! | [`complex`] | [`Complex`] — the minimal complex value the spectral bins carry |
125//! | [`error`] | [`SpectralError`] |
126
127#![no_std]
128#![forbid(unsafe_code)]
129#![deny(missing_docs)]
130// Pedantic is surfaced (not denied) by the shared CI job; these four groups
131// are allowed here with the reason they are inherent to the domain, and
132// nothing else is suppressed.
133#![allow(
134 clippy::cast_precision_loss,
135 clippy::cast_possible_truncation,
136 clippy::cast_possible_wrap,
137 clippy::cast_sign_loss,
138 reason = "spectral algebra is index math: bin numbers and hop offsets are usize by construction and become f64 bin frequencies, and f64 magnitudes become back into linear gains. Every conversion is bounded by an explicit range check (bins < fft_size/2 + 1, taps indexed through .get()) before it is used."
139)]
140
141extern crate alloc;
142
143pub mod complex;
144pub mod config;
145pub mod dct;
146pub mod error;
147pub mod features;
148pub mod mel;
149pub mod restore;
150pub mod stft;
151pub mod window;
152
153pub use complex::Complex;
154pub use config::StftConfig;
155pub use error::SpectralError;
156pub use features::{
157 spectral_bandwidth, spectral_centroid, spectral_flatness, spectral_flux, spectral_rolloff,
158 zero_crossing_rate,
159};
160pub use mel::{
161 hz_to_mel, mel_frequencies, mel_to_hz, mfcc, mfcc_with_lifter, real_cepstrum, MelBank,
162};
163pub use restore::{
164 denoise, harmonic_percussive_split, snr_db, spectral_gate, spectral_smooth, spectral_subtract,
165 GateConfig, NoiseProfile,
166};
167pub use stft::{istft, resample_frames, stft, Spectrum};
168pub use window::Window;