Skip to main content

silence_split/
analyze.rs

1//! Frame analysis: PCM levels or external scores on the original sample timeline.
2
3use alloc::collections::VecDeque;
4use alloc::vec::Vec;
5use core::time::Duration;
6
7use crate::errors::{ConfigError, PLANAR_CHANNELS, PLANAR_LENGTHS, PLANAR_PENDING};
8use crate::filter::{CUTOFF_HZ, HighPass};
9use crate::math;
10use crate::sample::{Layout, Sample};
11
12const NANOS_PER_SEC: u128 = 1_000_000_000;
13
14/// `d` in whole samples at `rate`, rounded to nearest, in exact integer arithmetic.
15fn round_samples(d: Duration, rate: u32) -> u128 {
16    (d.as_nanos() * u128::from(rate) + NANOS_PER_SEC / 2) / NANOS_PER_SEC
17}
18
19fn saturating_usize(v: u128) -> usize {
20    usize::try_from(v).unwrap_or(usize::MAX)
21}
22
23/// Window and hop of the PCM analyzer.
24///
25/// Both are given in time and rounded once to whole samples when an [`Analyzer`] is created, so
26/// frame positions never drift at sample rates where the hop is not a whole number of samples.
27#[derive(Clone, Debug, PartialEq)]
28#[non_exhaustive]
29pub struct AnalyzeConfig {
30    window: Duration,
31    hop: Duration,
32}
33
34impl Default for AnalyzeConfig {
35    /// A 30 ms window every 10 ms.
36    fn default() -> Self {
37        Self {
38            window: Duration::from_millis(30),
39            hop: Duration::from_millis(10),
40        }
41    }
42}
43
44impl AnalyzeConfig {
45    /// Sets the level window and the hop between frames. The window is centered on its hop.
46    ///
47    /// # Errors
48    ///
49    /// [`ConfigError::InvalidFrames`] if the hop is zero or longer than the window.
50    pub fn frames(mut self, window: Duration, hop: Duration) -> Result<Self, ConfigError> {
51        if hop.is_zero() || window < hop {
52            return Err(ConfigError::InvalidFrames);
53        }
54        self.window = window;
55        self.hop = hop;
56        Ok(self)
57    }
58}
59
60/// What the frame values of an [`Analysis`] measure.
61#[derive(Clone, Copy, Debug, PartialEq, Eq)]
62#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
63pub(crate) enum Domain {
64    /// Frame level in dBFS of the high-passed signal.
65    Decibels,
66    /// External speech probability in `0.0..=1.0`.
67    Scores,
68}
69
70/// Incremental PCM analyzer. Push decoded audio in any block size, then [`finish`](Self::finish).
71///
72/// Each channel is high-passed at 80 Hz for detection only, the channel powers are averaged, and
73/// every hop produces one frame level in dBFS over a window centered on that hop. Only the frame
74/// levels and digital-zero flags are kept, about 1.8 MB per hour at the default 10 ms hop. Samples
75/// that are not finite (NaN or infinite) are read as zero.
76#[derive(Clone, Debug)]
77pub struct Analyzer {
78    layout: Layout,
79    hop: u64,
80    window: u64,
81    filters: Vec<HighPass>,
82    /// Channel samples of an interleaved frame split across pushes.
83    pending: Vec<f32>,
84    /// Per-sample channel-mean filtered power and whether any raw channel sample was non-zero.
85    buffer: VecDeque<(f64, bool)>,
86    /// Sample index of `buffer[0]`.
87    buffer_start: u64,
88    received: u64,
89    values: Vec<f32>,
90    zero: Vec<bool>,
91}
92
93impl Analyzer {
94    /// An analyzer for audio with `layout`.
95    ///
96    /// # Errors
97    ///
98    /// [`ConfigError::ZeroSampleRate`], [`ConfigError::ZeroChannels`],
99    /// [`ConfigError::SampleRateTooLow`] if the rate is at or below 160 Hz,
100    /// [`ConfigError::HopTooShort`] if the hop rounds to zero samples, or
101    /// [`ConfigError::InvalidFrames`] if the hop exceeds `u32::MAX` samples.
102    pub fn new(layout: Layout, config: &AnalyzeConfig) -> Result<Self, ConfigError> {
103        validate_layout(layout)?;
104        if f64::from(layout.sample_rate) <= 2.0 * CUTOFF_HZ {
105            return Err(ConfigError::SampleRateTooLow);
106        }
107        let hop = round_samples(config.hop, layout.sample_rate);
108        if hop == 0 {
109            return Err(ConfigError::HopTooShort);
110        }
111        let hop = u64::from(u32::try_from(hop).map_err(|_| ConfigError::InvalidFrames)?);
112        // The window is at least the hop, so its rounding is at least the hop's.
113        let window = u64::try_from(round_samples(config.window, layout.sample_rate))
114            .map_err(|_| ConfigError::InvalidFrames)?;
115        Ok(Self {
116            layout,
117            hop,
118            window,
119            filters: (0..layout.channels)
120                .map(|_| HighPass::new(layout.sample_rate))
121                .collect(),
122            pending: Vec::new(),
123            buffer: VecDeque::new(),
124            buffer_start: 0,
125            received: 0,
126            values: Vec::new(),
127            zero: Vec::new(),
128        })
129    }
130
131    /// Pushes interleaved samples. A trailing partial frame is kept until the next push.
132    pub fn push_interleaved<S: Sample>(&mut self, pcm: &[S]) {
133        let channels = usize::from(self.layout.channels);
134        let mut rest = pcm;
135        if !self.pending.is_empty() {
136            let take = (channels - self.pending.len()).min(rest.len());
137            self.pending.extend(rest[..take].iter().map(|s| s.to_f32()));
138            rest = &rest[take..];
139            if self.pending.len() < channels {
140                return;
141            }
142            let frame = core::mem::take(&mut self.pending);
143            self.process(frame.iter().copied());
144        }
145        let mut chunks = rest.chunks_exact(channels);
146        for frame in &mut chunks {
147            self.process(frame.iter().map(|s| s.to_f32()));
148        }
149        self.pending
150            .extend(chunks.remainder().iter().map(|s| s.to_f32()));
151    }
152
153    /// Pushes one slice per channel.
154    ///
155    /// # Panics
156    ///
157    /// If the number of slices differs from the channel count, the slices differ in length, or a
158    /// partial interleaved frame from [`push_interleaved`](Self::push_interleaved) is pending.
159    pub fn push_planar<S: Sample>(&mut self, pcm: &[&[S]]) {
160        assert!(self.pending.is_empty(), "{PLANAR_PENDING}");
161        assert_eq!(
162            pcm.len(),
163            usize::from(self.layout.channels),
164            "{PLANAR_CHANNELS}"
165        );
166        let len = pcm.first().map_or(0, |c| c.len());
167        assert!(pcm.iter().all(|c| c.len() == len), "{PLANAR_LENGTHS}");
168        for i in 0..len {
169            self.process(pcm.iter().map(|c| c[i].to_f32()));
170        }
171    }
172
173    /// Finishes the stream and returns the frame levels. A partial interleaved frame is dropped.
174    #[must_use]
175    pub fn finish(mut self) -> Analysis {
176        let len = self.received;
177        let frames = len.div_ceil(self.hop);
178        while (self.values.len() as u64) < frames {
179            self.emit(len);
180        }
181        Analysis {
182            layout: self.layout,
183            len,
184            frame_rate: self.layout.sample_rate,
185            hop: self.hop as u32,
186            domain: Domain::Decibels,
187            values: self.values,
188            zero: self.zero,
189        }
190    }
191
192    fn process(&mut self, frame: impl Iterator<Item = f32>) {
193        let mut power = 0.0;
194        let mut nonzero = false;
195        for (filter, x) in self.filters.iter_mut().zip(frame) {
196            // One NaN or infinity would stay in the filter state and silence the rest of the file.
197            let x = if x.is_finite() { x } else { 0.0 };
198            nonzero |= x != 0.0;
199            let y = filter.process(f64::from(x));
200            power += y * y;
201        }
202        self.buffer
203            .push_back((power / f64::from(self.layout.channels), nonzero));
204        self.received += 1;
205        while self.window_end(self.values.len() as u64) <= self.received {
206            self.emit(self.received);
207        }
208    }
209
210    /// Sample range `[start, end)` of frame `i`'s window, before clipping to the stream.
211    fn window_start(&self, i: u64) -> u64 {
212        (i * self.hop).saturating_sub((self.window - self.hop) / 2)
213    }
214
215    fn window_end(&self, i: u64) -> u64 {
216        i * self.hop + self.window - (self.window - self.hop) / 2
217    }
218
219    /// Emits the next frame with its window clipped to `[0, available)`.
220    fn emit(&mut self, available: u64) {
221        let i = self.values.len() as u64;
222        let start = self.window_start(i);
223        let end = self.window_end(i).min(available);
224        let from = (start - self.buffer_start) as usize;
225        let to = (end - self.buffer_start) as usize;
226        let mut power = 0.0;
227        let mut nonzero = false;
228        for &(p, nz) in self.buffer.range(from..to) {
229            power += p;
230            nonzero |= nz;
231        }
232        // The filter rings on after the input stops, so a digital-zero window gets the floor level.
233        let power = if nonzero {
234            power / (to - from) as f64
235        } else {
236            0.0
237        };
238        self.values.push(math::power_to_db(power) as f32);
239        self.zero.push(!nonzero);
240        let next = self.window_start(i + 1).min(self.received);
241        while self.buffer_start < next {
242            self.buffer.pop_front();
243            self.buffer_start += 1;
244        }
245    }
246}
247
248fn validate_layout(layout: Layout) -> Result<(), ConfigError> {
249    if layout.sample_rate == 0 {
250        return Err(ConfigError::ZeroSampleRate);
251    }
252    if layout.channels == 0 {
253        return Err(ConfigError::ZeroChannels);
254    }
255    Ok(())
256}
257
258/// Frame values on the original sample timeline, from an [`Analyzer`] or external scores.
259///
260/// Frame `i` stands for original samples `[start(i), start(i + 1))`, where
261/// `start(i) = floor(i · hop · sample_rate / frame_rate)` in exact integer arithmetic and the last
262/// frame ends at the audio length. Thresholds are resolved when segmenting or planning, not here,
263/// so one analysis serves any threshold.
264#[derive(Clone, Debug, PartialEq)]
265#[cfg_attr(
266    feature = "serde",
267    derive(serde::Serialize, serde::Deserialize),
268    serde(try_from = "AnalysisData")
269)]
270pub struct Analysis {
271    layout: Layout,
272    len: u64,
273    frame_rate: u32,
274    hop: u32,
275    domain: Domain,
276    values: Vec<f32>,
277    zero: Vec<bool>,
278}
279
280impl Analysis {
281    /// Wraps per-frame speech probabilities from an external voice activity detector.
282    ///
283    /// `len` is the length of the original audio in samples per channel. `hop` is the detector's
284    /// hop in samples at `score_rate`, which may differ from the original sample rate: a 16 kHz
285    /// detector with a 512-sample hop maps frame `i` to original sample
286    /// `floor(i · 512 · sample_rate / 16000)`. Each frame must span at least one original sample.
287    /// The scores must cover the audio: the last score starts before `len`, and less than one hop
288    /// may be missing at the end.
289    ///
290    /// # Errors
291    ///
292    /// [`ConfigError::ZeroSampleRate`], [`ConfigError::ZeroChannels`],
293    /// [`ConfigError::InvalidScoreFrames`] for a zero rate or hop or a frame shorter than one
294    /// original sample, [`ConfigError::InvalidValue`]
295    /// for a score outside `0.0..=1.0`, or [`ConfigError::FrameCountMismatch`].
296    pub fn from_scores(
297        layout: Layout,
298        len: u64,
299        score_rate: u32,
300        hop: u32,
301        scores: Vec<f32>,
302    ) -> Result<Self, ConfigError> {
303        let zero = alloc::vec![false; scores.len()];
304        let analysis = Self {
305            layout,
306            len,
307            frame_rate: score_rate,
308            hop,
309            domain: Domain::Scores,
310            values: scores,
311            zero,
312        };
313        analysis.validate()?;
314        Ok(analysis)
315    }
316
317    /// Layout of the original audio.
318    #[must_use]
319    pub fn layout(&self) -> Layout {
320        self.layout
321    }
322
323    /// Length of the original audio in samples per channel.
324    #[must_use]
325    pub fn sample_count(&self) -> u64 {
326        self.len
327    }
328
329    fn validate(&self) -> Result<(), ConfigError> {
330        validate_layout(self.layout)?;
331        let frame_samples = u64::from(self.hop) * u64::from(self.layout.sample_rate);
332        if self.frame_rate == 0 || self.hop == 0 || frame_samples < u64::from(self.frame_rate) {
333            return Err(ConfigError::InvalidScoreFrames);
334        }
335        let valid = |v: &f32| match self.domain {
336            Domain::Decibels => v.is_finite(),
337            Domain::Scores => (0.0..=1.0).contains(v),
338        };
339        let zero_scores = self.domain == Domain::Scores && self.zero.iter().any(|z| *z);
340        if !self.values.iter().all(valid) || zero_scores {
341            return Err(ConfigError::InvalidValue);
342        }
343        let n = self.values.len();
344        let len = u128::from(self.len);
345        let covered = if self.len == 0 {
346            n == 0
347        } else {
348            n > 0 && self.start(n - 1) < len && len < self.start(n + 1)
349        };
350        if !covered || self.zero.len() != n {
351            return Err(ConfigError::FrameCountMismatch);
352        }
353        Ok(())
354    }
355
356    /// Number of frames.
357    pub(crate) fn frames(&self) -> usize {
358        self.values.len()
359    }
360
361    pub(crate) fn domain(&self) -> Domain {
362        self.domain
363    }
364
365    pub(crate) fn values(&self) -> &[f32] {
366        &self.values
367    }
368
369    /// Whether each frame's window is digital zero in every channel.
370    pub(crate) fn zero(&self) -> &[bool] {
371        &self.zero
372    }
373
374    /// Unclipped original start sample of frame `i`.
375    fn start(&self, i: usize) -> u128 {
376        let num = i as u128 * u128::from(self.hop) * u128::from(self.layout.sample_rate);
377        num / u128::from(self.frame_rate)
378    }
379
380    /// Original sample of frame boundary `k` in `0..=frames`; the last boundary is the length.
381    pub(crate) fn position(&self, k: usize) -> u64 {
382        if k >= self.frames() {
383            self.len
384        } else {
385            // Validation keeps every frame start below the length.
386            self.start(k) as u64
387        }
388    }
389
390    /// Duration of one frame in seconds.
391    pub(crate) fn frame_secs(&self) -> f64 {
392        f64::from(self.hop) / f64::from(self.frame_rate)
393    }
394
395    /// `d` in frames as the exact fraction `(numerator, denominator)`.
396    fn frame_fraction(&self, d: Duration) -> (u128, u128) {
397        (
398            d.as_nanos() * u128::from(self.frame_rate),
399            u128::from(self.hop) * NANOS_PER_SEC,
400        )
401    }
402
403    /// `d` in whole frames, rounded to nearest.
404    pub(crate) fn frames_in(&self, d: Duration) -> usize {
405        let (num, den) = self.frame_fraction(d);
406        saturating_usize((num + den / 2) / den)
407    }
408
409    /// `d` in whole frames, rounded up.
410    pub(crate) fn frames_ceil(&self, d: Duration) -> usize {
411        let (num, den) = self.frame_fraction(d);
412        saturating_usize(num.div_ceil(den))
413    }
414
415    /// `d` in whole frames, rounded down.
416    pub(crate) fn frames_floor(&self, d: Duration) -> usize {
417        let (num, den) = self.frame_fraction(d);
418        saturating_usize(num / den)
419    }
420
421    /// `d` in whole original samples, rounded down.
422    pub(crate) fn samples_floor(&self, d: Duration) -> u64 {
423        let samples = d.as_nanos() * u128::from(self.layout.sample_rate) / NANOS_PER_SEC;
424        u64::try_from(samples).unwrap_or(u64::MAX)
425    }
426
427    /// `d` in original samples as a real number.
428    pub(crate) fn samples_in(&self, d: Duration) -> f64 {
429        (d.as_nanos() * u128::from(self.layout.sample_rate)) as f64 / NANOS_PER_SEC as f64
430    }
431}
432
433/// Unvalidated serialized form of [`Analysis`].
434#[cfg(feature = "serde")]
435#[derive(serde::Deserialize)]
436struct AnalysisData {
437    layout: Layout,
438    len: u64,
439    frame_rate: u32,
440    hop: u32,
441    domain: Domain,
442    values: Vec<f32>,
443    zero: Vec<bool>,
444}
445
446#[cfg(feature = "serde")]
447impl TryFrom<AnalysisData> for Analysis {
448    type Error = ConfigError;
449
450    fn try_from(d: AnalysisData) -> Result<Self, ConfigError> {
451        let analysis = Self {
452            layout: d.layout,
453            len: d.len,
454            frame_rate: d.frame_rate,
455            hop: d.hop,
456            domain: d.domain,
457            values: d.values,
458            zero: d.zero,
459        };
460        analysis.validate()?;
461        Ok(analysis)
462    }
463}