Measure a third-octave spectrum and channel levels for visualizations

The analyzer now keeps a full-rate mono PCM history and per-window left/right
RMS and peaks. The FFT and all ballistics run on the reader side when a
snapshot is taken, so the audio callback only appends samples: 31 bands with
exact base-2 edges that partition the FFT bins, an ~85 ms window that follows
the sample rate, time-based attack/fall/peak hold, and silence only after the
PCM counter has stalled for longer than a few device callbacks.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
sanapachandClaude Opus 5.5 committed 2026-11-20 23:48:13 +02:00
1 parent 038f0979af
commit aabca327b2
3 files changed
+780 -11

No files matched your search

+204 -10
View File
@@ -1,10 +1,12 @@
use std::sync::Arc;
use std::sync::atomic::{AtomicI16, AtomicU32, AtomicU64, AtomicUsize, Ordering};
use std::time::Duration;
use std::sync::{Arc, Mutex};
use std::time::{Duration, Instant};
use rodio::source::SeekError;
use rodio::{ChannelCount, Sample, SampleRate, Source};
use super::spectrum::{Meter, PCM_SAMPLES, StereoReading};
const LEVEL_SCALE: f32 = 1_000_000.0;
const SCOPE_SAMPLES: usize = 256;
const SCOPE_SAMPLE_SCALE: f32 = i16::MAX as f32;
@@ -20,6 +22,20 @@ pub struct AudioAnalysisSnapshot {
pub treble: f64,
pub beat: f64,
pub scope: Vec<f64>,
/// Third-octave band levels (see `spectrum::BAND_CENTERS_HZ`), 0.0..1.0
/// over `spectrum::FLOOR_DB`..0 dBFS, with analyzer ballistics.
pub spectrum: Vec<f64>,
/// Per-band peak-hold markers on the same scale as `spectrum`.
pub spectrum_peaks: Vec<f64>,
/// Left/right RMS levels and held sample peaks on the same dB scale.
/// Mono sources report the same value for both channels.
pub level_l: f64,
pub level_r: f64,
pub peak_l: f64,
pub peak_r: f64,
/// Sample rate of the analyzed stream in Hz (0 when nothing has played
/// since the player last stopped).
pub sample_rate: u32,
}
#[derive(Debug)]
@@ -32,6 +48,19 @@ pub struct AnalyzerShared {
beat: AtomicU32,
scope_write: AtomicUsize,
scope: Box<[AtomicI16]>,
/// Full-rate mono history for the spectrum; written by the audio thread.
pcm_write: AtomicUsize,
pcm: Box<[AtomicI16]>,
sample_rate: AtomicU32,
/// Per-window channel levels (linear, `LEVEL_SCALE`). Peaks accumulate
/// with `fetch_max` until the meter consumes them.
rms_l: AtomicU32,
rms_r: AtomicU32,
peak_l: AtomicU32,
peak_r: AtomicU32,
/// Ballistics and FFT state. Only snapshot readers (the UI side) lock it;
/// the audio thread never does.
meter: Mutex<Meter>,
}
impl Default for AnalyzerShared {
@@ -44,14 +73,26 @@ impl Default for AnalyzerShared {
treble: AtomicU32::new(0),
beat: AtomicU32::new(0),
scope_write: AtomicUsize::new(0),
scope: (0..SCOPE_SAMPLES)
.map(|_| AtomicI16::new(0))
.collect::<Vec<_>>()
.into_boxed_slice(),
scope: atomic_ring(SCOPE_SAMPLES),
pcm_write: AtomicUsize::new(0),
pcm: atomic_ring(PCM_SAMPLES),
sample_rate: AtomicU32::new(0),
rms_l: AtomicU32::new(0),
rms_r: AtomicU32::new(0),
peak_l: AtomicU32::new(0),
peak_r: AtomicU32::new(0),
meter: Mutex::new(Meter::default()),
}
}
}
fn atomic_ring(len: usize) -> Box<[AtomicI16]> {
(0..len)
.map(|_| AtomicI16::new(0))
.collect::<Vec<_>>()
.into_boxed_slice()
}
impl AnalyzerShared {
pub fn clear(&self) {
self.energy.store(0, Ordering::Relaxed);
@@ -63,10 +104,31 @@ impl AnalyzerShared {
for sample in self.scope.iter() {
sample.store(0, Ordering::Relaxed);
}
self.pcm_write.store(0, Ordering::Relaxed);
for sample in self.pcm.iter() {
sample.store(0, Ordering::Relaxed);
}
for level in [&self.rms_l, &self.rms_r, &self.peak_l, &self.peak_r] {
level.store(0, Ordering::Relaxed);
}
self.sequence.store(0, Ordering::Relaxed);
}
/// Like [`Self::clear`], and also forgets the sample rate: nothing is
/// loaded any more.
pub fn reset(&self) {
self.clear();
self.sample_rate.store(0, Ordering::Relaxed);
}
pub fn snapshot(&self) -> AudioAnalysisSnapshot {
self.snapshot_at(Instant::now())
}
/// Like [`Self::snapshot`] with an explicit clock, so meter ballistics are
/// deterministic in tests. Ballistics are time-based: how often callers
/// read does not change how fast bars rise or fall.
pub fn snapshot_at(&self, now: Instant) -> AudioAnalysisSnapshot {
let write = self.scope_write.load(Ordering::Relaxed);
let len = self.scope.len().max(1);
let scope = (0..self.scope.len())
@@ -76,6 +138,24 @@ impl AnalyzerShared {
})
.collect();
let sample_rate = self.sample_rate.load(Ordering::Relaxed);
let pcm_write = self.pcm_write.load(Ordering::Relaxed);
let stereo = StereoReading {
rms_l: load_norm(&self.rms_l) as f32,
rms_r: load_norm(&self.rms_r) as f32,
peak_l: f64::from(self.peak_l.swap(0, Ordering::Relaxed)) as f32 / LEVEL_SCALE,
peak_r: f64::from(self.peak_r.swap(0, Ordering::Relaxed)) as f32 / LEVEL_SCALE,
};
let reading = {
let mut meter = self
.meter
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
meter.update(now, pcm_write, sample_rate, stereo, |out| {
self.copy_pcm(pcm_write, out)
})
};
AudioAnalysisSnapshot {
sequence: self.sequence.load(Ordering::Relaxed),
energy: load_norm(&self.energy),
@@ -84,6 +164,29 @@ impl AnalyzerShared {
treble: load_norm(&self.treble),
beat: load_norm(&self.beat),
scope,
spectrum: reading.spectrum,
spectrum_peaks: reading.spectrum_peaks,
level_l: reading.level_l,
level_r: reading.level_r,
peak_l: reading.peak_l,
peak_r: reading.peak_r,
sample_rate,
}
}
/// Copies the newest `out.len()` mono samples, oldest first. Slots not
/// written since the last clear read as silence.
fn copy_pcm(&self, write: usize, out: &mut [f32]) {
let len = self.pcm.len();
let count = out.len().min(len);
let start = write.wrapping_sub(count);
for (offset, slot) in out.iter_mut().enumerate() {
*slot = if offset < count && write >= count - offset {
let index = start.wrapping_add(offset) % len;
f32::from(self.pcm[index].load(Ordering::Relaxed)) / SCOPE_SAMPLE_SCALE
} else {
0.0
};
}
}
@@ -96,6 +199,21 @@ impl AnalyzerShared {
self.sequence.fetch_add(1, Ordering::Relaxed);
}
fn push_pcm(&self, sample: f32) {
let index = self.pcm_write.fetch_add(1, Ordering::Relaxed) % self.pcm.len();
let value = (sample.clamp(-1.0, 1.0) * SCOPE_SAMPLE_SCALE).round() as i16;
self.pcm[index].store(value, Ordering::Relaxed);
}
fn store_channels(&self, sample_rate: f32, rms: [f32; 2], peak: [f32; 2]) {
self.sample_rate
.store(sample_rate.round() as u32, Ordering::Relaxed);
store_norm(&self.rms_l, rms[0]);
store_norm(&self.rms_r, rms[1]);
self.peak_l.fetch_max(norm_bits(peak[0]), Ordering::Relaxed);
self.peak_r.fetch_max(norm_bits(peak[1]), Ordering::Relaxed);
}
fn push_scope(&self, sample: f32) {
let index = self.scope_write.fetch_add(1, Ordering::Relaxed) % self.scope.len();
let value = (sample.clamp(-1.0, 1.0) * SCOPE_SAMPLE_SCALE).round() as i16;
@@ -181,6 +299,10 @@ struct AnalyzerState {
mid_alpha: f32,
channel_index: usize,
frame_sum: f32,
/// Left/right of the current frame (mono feeds both).
frame_lr: [f32; 2],
channel_sq: [f32; 2],
channel_peak: [f32; 2],
frame_count: usize,
window_frames: usize,
scope_counter: usize,
@@ -208,6 +330,9 @@ impl AnalyzerState {
mid_alpha: 0.0,
channel_index: 0,
frame_sum: 0.0,
frame_lr: [0.0; 2],
channel_sq: [0.0; 2],
channel_peak: [0.0; 2],
frame_count: 0,
window_frames: 0,
scope_counter: 0,
@@ -252,6 +377,9 @@ impl AnalyzerState {
fn reset_filters(&mut self) {
self.channel_index = 0;
self.frame_sum = 0.0;
self.frame_lr = [0.0; 2];
self.channel_sq = [0.0; 2];
self.channel_peak = [0.0; 2];
self.frame_count = 0;
self.scope_counter = 0;
self.low_bass = 0.0;
@@ -275,10 +403,21 @@ impl AnalyzerState {
0.0
};
self.frame_sum += sample;
// First channel is left, second right; extra channels only feed mono.
if self.channel_index < 2 {
self.frame_lr[self.channel_index] = sample;
}
self.channel_index += 1;
if self.channel_index < self.channels {
return;
}
if self.channels == 1 {
self.frame_lr[1] = self.frame_lr[0];
}
for (channel, value) in self.frame_lr.iter().enumerate() {
self.channel_sq[channel] += value * value;
self.channel_peak[channel] = self.channel_peak[channel].max(value.abs());
}
let mono = self.frame_sum / self.channels as f32;
self.channel_index = 0;
@@ -299,6 +438,7 @@ impl AnalyzerState {
self.mid_sq += mid * mid;
self.treble_sq += treble * treble;
self.frame_count += 1;
shared.push_pcm(sample);
self.scope_counter += 1;
if self.scope_counter >= self.scope_stride {
@@ -339,10 +479,21 @@ impl AnalyzerState {
self.smooth_beat,
);
shared.store_channels(
self.sample_rate,
[
(self.channel_sq[0] / frames).sqrt(),
(self.channel_sq[1] / frames).sqrt(),
],
self.channel_peak,
);
self.full_sq = 0.0;
self.bass_sq = 0.0;
self.mid_sq = 0.0;
self.treble_sq = 0.0;
self.channel_sq = [0.0; 2];
self.channel_peak = [0.0; 2];
self.frame_count = 0;
}
}
@@ -361,10 +512,11 @@ fn smooth_level(previous: f32, next: f32, attack: f32, release: f32) -> f32 {
}
fn store_norm(target: &AtomicU32, value: f32) {
target.store(
(value.clamp(0.0, 1.0) * LEVEL_SCALE).round() as u32,
Ordering::Relaxed,
);
target.store(norm_bits(value), Ordering::Relaxed);
}
fn norm_bits(value: f32) -> u32 {
(value.clamp(0.0, 1.0) * LEVEL_SCALE).round() as u32
}
fn load_norm(source: &AtomicU32) -> f64 {
@@ -452,4 +604,46 @@ mod tests {
assert!(snapshot.bass > 0.0);
assert!(snapshot.scope.iter().any(|sample| sample.abs() > 0.001));
}
#[test]
fn analyzed_source_feeds_the_spectrum_and_channel_meters() {
let shared = Arc::new(AnalyzerShared::default());
let source = TestSource::sine(48_000, 2, 48_000, 1_000.0);
let analyzed = AnalyzedSource::new(source, Arc::clone(&shared));
for _ in analyzed {}
let snapshot = shared.snapshot();
assert_eq!(snapshot.sample_rate, 48_000);
let bands = crate::player::BAND_CENTERS_HZ;
let at_1k = bands.iter().position(|hz| *hz == 1_000.0).unwrap();
let loudest = snapshot
.spectrum
.iter()
.enumerate()
.max_by(|left, right| left.1.total_cmp(right.1))
.map(|(index, _)| index);
assert_eq!(loudest, Some(at_1k));
assert!(snapshot.level_l > 0.5 && (snapshot.level_l - snapshot.level_r).abs() < 1e-6);
assert!(snapshot.peak_l >= snapshot.level_l);
}
#[test]
fn pcm_history_reads_newest_samples_and_silence_before_the_first() {
let shared = AnalyzerShared::default();
for value in [0.25_f32, 0.5, -0.5] {
shared.push_pcm(value);
}
let mut out = [1.0_f32; 5];
shared.copy_pcm(shared.pcm_write.load(Ordering::Relaxed), &mut out);
let rounded: Vec<f32> = out
.iter()
.map(|value| (value * 4.0).round() / 4.0)
.collect();
assert_eq!(rounded, [0.0, 0.0, 0.25, 0.5, -0.5]);
shared.clear();
shared.copy_pcm(shared.pcm_write.load(Ordering::Relaxed), &mut out);
assert!(out.iter().all(|value| *value == 0.0));
}
}
+3 -1
View File
@@ -6,6 +6,7 @@
mod analyzer;
mod opus;
mod spectrum;
use std::sync::Arc;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
@@ -15,6 +16,7 @@ use std::time::Duration;
use rodio::{Decoder, DeviceSinkBuilder, Player, Source, stream::MixerDeviceSink};
pub use analyzer::AudioAnalysisSnapshot;
pub use spectrum::{BAND_CENTERS_HZ, FLOOR_DB};
pub trait TrackReadSeek: std::io::Read + std::io::Seek + Send + Sync {}
@@ -453,7 +455,7 @@ fn handle(
if let Some(out) = output.take() {
out.player.stop();
}
shared.analysis.clear();
shared.analysis.reset();
playing.track_loaded = false;
playing.base = Duration::ZERO;
}
+573
View File
@@ -0,0 +1,573 @@
//! Display meter for visualizations: a third-octave spectrum and stereo levels
//! with analyzer ballistics (fast attack, steady fall, peak hold).
//!
//! The audio thread only writes samples and per-window channel levels into
//! `AnalyzerShared`; the FFT and all smoothing run here, on the reader side,
//! when a snapshot is taken. Ballistics are time-based: rises and falls
//! advance with the clock, not with the number of snapshots.
use std::sync::Arc;
use std::time::Instant;
use rustfft::num_complex::Complex;
use rustfft::{Fft, FftPlanner};
/// Mono samples kept for the spectrum: enough for an ~85 ms window at
/// 192 kHz. The FFT uses the newest `fft_len(rate)` of them.
pub const PCM_SAMPLES: usize = 16_384;
/// Bottom of the display scale: values are normalized from `FLOOR_DB`..0 dBFS
/// to 0.0..1.0, so a full-scale sine reads 1.0.
pub const FLOOR_DB: f32 = -60.0;
/// Nominal ISO third-octave band centres (Hz), 20 Hz .. 20 kHz. These are
/// labels; band edges come from the exact base-2 centres (see `exact_center`)
/// so neighbouring bands meet without gaps or overlaps.
pub const BAND_CENTERS_HZ: [f32; 31] = [
20.0, 25.0, 31.5, 40.0, 50.0, 63.0, 80.0, 100.0, 125.0, 160.0, 200.0, 250.0, 315.0, 400.0,
500.0, 630.0, 800.0, 1_000.0, 1_250.0, 1_600.0, 2_000.0, 2_500.0, 3_150.0, 4_000.0, 5_000.0,
6_300.0, 8_000.0, 10_000.0, 12_500.0, 16_000.0, 20_000.0,
];
const BANDS: usize = BAND_CENTERS_HZ.len();
/// Index of the 1 kHz band.
const KHZ_BAND: i32 = 17;
const MIN_FFT: usize = 4096;
const BAND_ATTACK_SECS: f32 = 0.025;
const BAND_FALL_DB_PER_SEC: f32 = 36.0;
const PEAK_HOLD_SECS: f32 = 1.2;
const PEAK_FALL_DB_PER_SEC: f32 = 18.0;
const LEVEL_ATTACK_SECS: f32 = 0.05;
const LEVEL_RELEASE_SECS: f32 = 0.3;
/// Longest step applied at once; a stalled reader must not fast-forward a
/// whole second of decay in one frame.
const MAX_STEP_SECS: f32 = 0.25;
/// Audio arrives in device-callback bursts (rodio uses ~46 ms buffers), so a
/// snapshot may see no new samples while playback runs. Only a longer stall
/// (pause, stop) counts as silence.
const STALL_SECS: f32 = 0.15;
/// FFT length for a sample rate: ~85 ms of audio, a power of two.
fn fft_len(sample_rate: u32) -> usize {
(sample_rate as usize * MIN_FFT / 48_000)
.next_power_of_two()
.clamp(MIN_FFT, PCM_SAMPLES)
}
/// Exact base-2 third-octave centre of band `index` (1 kHz at index 17).
fn exact_center(index: usize) -> f32 {
1_000.0 * 2f32.powf((index as i32 - KHZ_BAND) as f32 / 3.0)
}
/// Linear channel levels of the latest analysis window.
#[derive(Debug, Clone, Copy, Default)]
pub struct StereoReading {
pub rms_l: f32,
pub rms_r: f32,
/// Highest sample peaks since the previous reading.
pub peak_l: f32,
pub peak_r: f32,
}
#[derive(Debug, Clone, Default)]
pub struct MeterReading {
pub spectrum: Vec<f64>,
pub spectrum_peaks: Vec<f64>,
pub level_l: f64,
pub level_r: f64,
pub peak_l: f64,
pub peak_r: f64,
}
struct Hold {
db: f32,
age: f32,
}
impl Hold {
fn new() -> Self {
Self {
db: FLOOR_DB,
age: 0.0,
}
}
fn update(&mut self, value_db: f32, dt: f32) {
if value_db >= self.db {
self.db = value_db;
self.age = 0.0;
return;
}
self.age += dt;
if self.age > PEAK_HOLD_SECS {
self.db = (self.db - PEAK_FALL_DB_PER_SEC * dt).max(value_db);
}
}
}
/// FFT plan, window and band bin ranges for one sample rate.
struct Analysis {
sample_rate: u32,
fft: Arc<dyn Fft<f32>>,
window: Vec<f32>,
/// Sum of squared window weights, for power normalization.
window_power: f32,
pcm: Vec<f32>,
buffer: Vec<Complex<f32>>,
scratch: Vec<Complex<f32>>,
/// Inclusive bin range per band; `None` above Nyquist.
bins: [Option<(usize, usize)>; BANDS],
}
impl Analysis {
fn new(sample_rate: u32) -> Self {
let len = fft_len(sample_rate);
let fft = FftPlanner::<f32>::new().plan_fft_forward(len);
let scratch = vec![Complex::default(); fft.get_inplace_scratch_len()];
let window: Vec<f32> = (0..len)
.map(|index| {
let phase = std::f32::consts::TAU * index as f32 / len as f32;
0.5 - 0.5 * phase.cos()
})
.collect();
let window_power = window.iter().map(|weight| weight * weight).sum();
Self {
sample_rate,
fft,
window,
window_power,
pcm: vec![0.0; len],
buffer: vec![Complex::default(); len],
scratch,
bins: band_bins(sample_rate, len),
}
}
/// Band power in dBFS (a full-scale sine reads 0 dB in its band). The
/// caller has filled `pcm`.
fn band_targets(&mut self) -> [f32; BANDS] {
for ((slot, sample), weight) in self.buffer.iter_mut().zip(&self.pcm).zip(&self.window) {
*slot = Complex::new(sample * weight, 0.0);
}
self.fft
.process_with_scratch(&mut self.buffer, &mut self.scratch);
// One-sided power per bin, normalized so the bins of a sine sum to
// its mean square (A^2 / 2); doubled below so the sine reads 0 dB.
let scale = 2.0 / (self.buffer.len() as f32 * self.window_power);
let mut out = [FLOOR_DB; BANDS];
for (slot, range) in out.iter_mut().zip(self.bins) {
if let Some((first, last)) = range {
let power: f32 = self.buffer[first..=last]
.iter()
.map(|bin| bin.norm_sqr() * scale)
.sum();
*slot = to_db_power(2.0 * power);
}
}
out
}
}
/// Partitions the FFT bins between the bands: each bin belongs to exactly one
/// band, from the first bin at or above the band's lower edge up to the bin
/// before the next band starts. A band narrower than one bin (deep bass at
/// short windows) reads the bin that contains its centre, which it then shares
/// with its neighbour.
fn band_bins(sample_rate: u32, len: usize) -> [Option<(usize, usize)>; BANDS] {
let bin_hz = sample_rate as f32 / len as f32;
let last_bin = len / 2 - 1;
let nyquist = sample_rate as f32 / 2.0;
let edge = 2f32.powf(1.0 / 6.0);
let first_bin = |index: usize| ((exact_center(index) / edge / bin_hz).ceil() as usize).max(1);
std::array::from_fn(|index| {
let low = exact_center(index) / edge;
if low >= nyquist {
return None;
}
let first = first_bin(index);
let last = if index + 1 < BANDS {
first_bin(index + 1).saturating_sub(1)
} else {
((exact_center(index) * edge / bin_hz).floor() as usize).max(first)
}
.min(last_bin);
if first <= last {
Some((first, last))
} else {
let center = ((exact_center(index) / bin_hz).round() as usize).clamp(1, last_bin);
Some((center, center))
}
})
}
pub struct Meter {
analysis: Option<Analysis>,
bands_db: [f32; BANDS],
band_peaks: [Hold; BANDS],
level_db: [f32; 2],
level_peaks: [Hold; 2],
last_update: Option<Instant>,
last_write: usize,
/// When the PCM counter last moved, and what that audio measured; reused
/// between device callbacks until `STALL_SECS` pass.
last_fresh: Option<Instant>,
held_targets: [f32; BANDS],
held_rms: [f32; 2],
}
impl std::fmt::Debug for Meter {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("Meter")
.field("bands_db", &self.bands_db)
.field("level_db", &self.level_db)
.finish_non_exhaustive()
}
}
impl Default for Meter {
fn default() -> Self {
Self {
analysis: None,
bands_db: [FLOOR_DB; BANDS],
band_peaks: std::array::from_fn(|_| Hold::new()),
level_db: [FLOOR_DB; 2],
level_peaks: std::array::from_fn(|_| Hold::new()),
last_update: None,
last_write: 0,
last_fresh: None,
held_targets: [FLOOR_DB; BANDS],
held_rms: [0.0; 2],
}
}
}
impl Meter {
/// Advances the meter to `now`. `write` is the analyzer's PCM write
/// counter: while it keeps moving the newest audio is measured; once it
/// has not moved for `STALL_SECS` (paused, stopped) the meter is fed
/// silence and falls instead of freezing. `fill_pcm` copies the newest
/// `out.len()` mono samples, oldest first.
pub fn update(
&mut self,
now: Instant,
write: usize,
sample_rate: u32,
stereo: StereoReading,
fill_pcm: impl FnOnce(&mut [f32]),
) -> MeterReading {
let dt = self
.last_update
.map(|last| now.saturating_duration_since(last).as_secs_f32())
.unwrap_or(MAX_STEP_SECS)
.min(MAX_STEP_SECS);
self.last_update = Some(now);
let fresh = write != self.last_write;
self.last_write = write;
let (targets, rms, peaks) = if fresh && sample_rate > 0 {
if self
.analysis
.as_ref()
.is_none_or(|analysis| analysis.sample_rate != sample_rate)
{
self.analysis = Some(Analysis::new(sample_rate));
}
let analysis = self.analysis.as_mut().expect("analysis was just set");
fill_pcm(&mut analysis.pcm);
self.held_targets = analysis.band_targets();
self.held_rms = [stereo.rms_l, stereo.rms_r];
self.last_fresh = Some(now);
(
self.held_targets,
self.held_rms,
[stereo.peak_l, stereo.peak_r],
)
} else if self
.last_fresh
.is_some_and(|last| now.saturating_duration_since(last).as_secs_f32() <= STALL_SECS)
{
(self.held_targets, self.held_rms, [0.0; 2])
} else {
([FLOOR_DB; BANDS], [0.0; 2], [0.0; 2])
};
for ((current, target), peak) in self
.bands_db
.iter_mut()
.zip(targets)
.zip(self.band_peaks.iter_mut())
{
*current = follow_band(*current, target, dt);
peak.update(*current, dt);
}
for channel in 0..2 {
self.level_db[channel] = follow_level(self.level_db[channel], to_db(rms[channel]), dt);
self.level_peaks[channel].update(to_db(peaks[channel]), dt);
}
MeterReading {
spectrum: self.bands_db.iter().map(|db| normalize(*db)).collect(),
spectrum_peaks: self
.band_peaks
.iter()
.map(|hold| normalize(hold.db))
.collect(),
level_l: normalize(self.level_db[0]),
level_r: normalize(self.level_db[1]),
peak_l: normalize(self.level_peaks[0].db),
peak_r: normalize(self.level_peaks[1].db),
}
}
}
fn follow_band(current: f32, target: f32, dt: f32) -> f32 {
if target > current {
current + (target - current) * (1.0 - (-dt / BAND_ATTACK_SECS).exp())
} else {
(current - BAND_FALL_DB_PER_SEC * dt).max(target)
}
}
fn follow_level(current: f32, target: f32, dt: f32) -> f32 {
let tau = if target > current {
LEVEL_ATTACK_SECS
} else {
LEVEL_RELEASE_SECS
};
current + (target - current) * (1.0 - (-dt / tau).exp())
}
fn to_db(amplitude: f32) -> f32 {
if amplitude <= 0.0 || !amplitude.is_finite() {
FLOOR_DB
} else {
(20.0 * amplitude.log10()).max(FLOOR_DB)
}
}
fn to_db_power(power: f32) -> f32 {
if power <= 0.0 || !power.is_finite() {
FLOOR_DB
} else {
(10.0 * power.log10()).max(FLOOR_DB)
}
}
fn normalize(db: f32) -> f64 {
f64::from(((db - FLOOR_DB) / -FLOOR_DB).clamp(0.0, 1.0))
}
#[cfg(test)]
mod tests {
use std::time::Duration;
use super::*;
fn sine(frequency: f32, amplitude: f32, sample_rate: u32, len: usize) -> Vec<f32> {
(0..len)
.map(|index| {
let time = index as f32 / sample_rate as f32;
amplitude * (std::f32::consts::TAU * frequency * time).sin()
})
.collect()
}
fn band(center: f32) -> usize {
BAND_CENTERS_HZ
.iter()
.position(|value| *value == center)
.unwrap()
}
/// Feeds a steady tone for `steps` snapshots 50 ms apart.
fn settle(meter: &mut Meter, frequency: f32, sample_rate: u32, steps: u64) -> MeterReading {
let samples = sine(frequency, 0.5, sample_rate, PCM_SAMPLES);
let start = Instant::now();
let mut reading = MeterReading::default();
for step in 1..=steps {
reading = meter.update(
start + Duration::from_millis(50 * step),
step as usize,
sample_rate,
StereoReading::default(),
|out| out.copy_from_slice(&samples[..out.len()]),
);
}
reading
}
fn band_powers_db(frequency: f32, sample_rate: u32) -> [f32; BANDS] {
let mut analysis = Analysis::new(sample_rate);
let len = analysis.pcm.len();
analysis
.pcm
.copy_from_slice(&sine(frequency, 1.0, sample_rate, len));
analysis.band_targets()
}
#[test]
fn a_sine_lights_its_own_third_octave_band() {
let reading = settle(&mut Meter::default(), 1_000.0, 48_000, 10);
let at_1k = reading.spectrum[band(1_000.0)];
// -6 dBFS on a 60 dB scale reads 0.9.
assert!((at_1k - 0.9).abs() < 0.03, "1 kHz band read {at_1k}");
assert!(reading.spectrum[band(250.0)] < 0.2);
assert!(reading.spectrum[band(4_000.0)] < 0.2);
assert!(reading.spectrum_peaks[band(1_000.0)] >= at_1k);
}
#[test]
fn bands_cover_the_axis_without_gaps_or_double_counting() {
for sample_rate in [44_100, 48_000, 96_000] {
// Up to just below the top band's upper edge (~22.4 kHz) or
// Nyquist; 1/24-octave steps also land right on band edges.
let top = (sample_rate as f32 / 2.0 * 0.85).min(exact_center(BANDS - 1) * 1.1);
let mut frequency = 80.0_f32;
while frequency < top {
let powers = band_powers_db(frequency, sample_rate);
let loudest = powers.iter().copied().fold(FLOOR_DB, f32::max);
let total: f32 = powers
.iter()
.filter(|db| **db > FLOOR_DB)
.map(|db| 10f32.powf(db / 10.0))
.sum();
assert!(
(-3.5..=0.5).contains(&loudest),
"{frequency} Hz at {sample_rate}: loudest band {loudest} dB"
);
let total_db = 10.0 * total.log10();
assert!(
total_db.abs() < 0.5,
"{frequency} Hz at {sample_rate}: bands sum to {total_db} dB"
);
frequency *= 2f32.powf(1.0 / 24.0);
}
}
}
#[test]
fn deep_bass_reads_at_every_sample_rate() {
for sample_rate in [44_100, 48_000, 96_000, 192_000] {
let powers = band_powers_db(31.5, sample_rate);
assert!(
powers[band(31.5)] > -3.0,
"31.5 Hz at {sample_rate}: {} dB",
powers[band(31.5)]
);
assert!(powers[band(1_000.0)] < -40.0);
}
// Bands above Nyquist stay at the floor.
assert_eq!(band_powers_db(1_000.0, 32_000)[band(20_000.0)], FLOOR_DB);
}
#[test]
fn callback_gaps_keep_the_meter_steady_but_a_stall_falls() {
let mut meter = Meter::default();
let samples = sine(1_000.0, 0.5, 48_000, PCM_SAMPLES);
let tone = StereoReading {
rms_l: 0.35,
rms_r: 0.35,
peak_l: 0.5,
peak_r: 0.5,
};
let start = Instant::now();
let mut write = 0;
let mut steady = MeterReading::default();
for step in 1..=40u64 {
// Every third snapshot lands between two device callbacks.
if step % 3 != 0 {
write += 1;
}
let reading = meter.update(
start + Duration::from_millis(50 * step),
write,
48_000,
tone,
|out| out.copy_from_slice(&samples[..out.len()]),
);
if step > 20 {
assert!(
(reading.level_l - steady.level_l).abs() < 0.02 || step == 21,
"level jumped at step {step}"
);
assert!(
(reading.spectrum[band(1_000.0)] - 0.9).abs() < 0.03,
"band jumped at step {step}"
);
}
steady = reading;
}
// The counter stops for longer than a callback gap: paused.
let index = band(1_000.0);
let paused_at = start + Duration::from_millis(2_000);
let first = meter.update(paused_at, write, 48_000, tone, |_| {});
let later = meter.update(
paused_at + Duration::from_millis(500),
write,
48_000,
tone,
|_| {},
);
assert!(later.spectrum[index] < first.spectrum[index]);
assert!(later.level_l < first.level_l);
// The peak marker holds for 1.2 s before it falls too.
assert!((later.spectrum_peaks[index] - 0.9).abs() < 0.03);
let mut reading = later;
for step in 1..=20u64 {
reading = meter.update(
paused_at + Duration::from_millis(500 + 250 * step),
write,
48_000,
tone,
|_| {},
);
}
assert_eq!(reading.spectrum[index], 0.0);
assert!(reading.spectrum_peaks[index] < 0.5);
}
#[test]
fn channel_levels_follow_rms_and_hold_peaks() {
let mut meter = Meter::default();
let start = Instant::now();
let loud_left = StereoReading {
rms_l: 0.5,
rms_r: 0.05,
peak_l: 0.9,
peak_r: 0.1,
};
let mut reading = MeterReading::default();
for step in 1..=20 {
reading = meter.update(
start + Duration::from_millis(50 * step),
step as usize,
48_000,
loud_left,
|out| out.fill(0.0),
);
}
assert!(reading.level_l > reading.level_r);
assert!((reading.level_l - normalize(to_db(0.5))).abs() < 0.02);
assert!((reading.peak_l - normalize(to_db(0.9))).abs() < 0.01);
assert!(reading.peak_l >= reading.level_l);
}
#[test]
fn silence_and_unknown_rate_read_the_floor() {
let mut meter = Meter::default();
let reading = meter.update(Instant::now(), 1, 0, StereoReading::default(), |_| {});
assert!(reading.spectrum.iter().all(|value| *value == 0.0));
assert_eq!(reading.level_l, 0.0);
assert_eq!(reading.spectrum.len(), BAND_CENTERS_HZ.len());
}
#[test]
fn fft_length_tracks_the_sample_rate() {
assert_eq!(fft_len(44_100), 4096);
assert_eq!(fft_len(48_000), 4096);
assert_eq!(fft_len(96_000), 8192);
assert_eq!(fft_len(192_000), 16_384);
assert_eq!(fft_len(0), 4096);
}
}