Skip to main content

silence_split/
segment.rs

1//! Thresholds and silence/sound segmentation.
2
3use alloc::vec::Vec;
4use core::ops::Range;
5use core::time::Duration;
6
7use crate::analyze::{Analysis, Domain};
8use crate::errors::ConfigError;
9
10/// Where a frame turns from silence to sound.
11///
12/// For PCM analyses the values are in dB; for external scores they are probabilities.
13#[derive(Clone, Copy, Debug, PartialEq)]
14#[non_exhaustive]
15pub enum Threshold {
16    /// Derived from the file itself, with hysteresis.
17    ///
18    /// For PCM, signal-free frames are left out, `floor` is the 10th percentile of frame levels
19    /// and `ref` the 99th. Sound starts at `max(floor + 4, min(floor + 6, ref − 20))` dB and ends
20    /// 3 dB below that. If that onset exceeds `ref`, it is lowered to `floor` to retain steady
21    /// sound. This also retains steady background noise; use [`Self::Abs`] to remove it at a
22    /// known level. For scores, sound starts at 0.5 and ends below 0.35.
23    Auto,
24    /// A fixed level: dBFS for PCM, probability for scores.
25    Abs(f32),
26    /// This far below the 99th percentile frame value: dB for PCM, probability for scores.
27    BelowRef(f32),
28}
29
30/// How frame values become silence and sound spans.
31#[derive(Clone, Debug, PartialEq)]
32#[non_exhaustive]
33pub struct SegmentConfig {
34    pub(crate) threshold: Threshold,
35    pub(crate) min_silence: Duration,
36    pub(crate) min_sound: Duration,
37    pub(crate) pre: Duration,
38    pub(crate) tail: Duration,
39}
40
41impl Default for SegmentConfig {
42    /// Automatic threshold, 250 ms minimum silence, 100 ms minimum sound, 100 ms kept before
43    /// sound and 200 ms after it.
44    fn default() -> Self {
45        Self {
46            threshold: Threshold::Auto,
47            min_silence: Duration::from_millis(250),
48            min_sound: Duration::from_millis(100),
49            pre: Duration::from_millis(100),
50            tail: Duration::from_millis(200),
51        }
52    }
53}
54
55impl SegmentConfig {
56    /// Sets the threshold.
57    ///
58    /// # Errors
59    ///
60    /// [`ConfigError::InvalidThreshold`] if the value is not finite or a
61    /// [`Threshold::BelowRef`] distance is negative.
62    pub fn threshold(mut self, threshold: Threshold) -> Result<Self, ConfigError> {
63        let valid = match threshold {
64            Threshold::Auto => true,
65            Threshold::Abs(v) => v.is_finite(),
66            Threshold::BelowRef(v) => v.is_finite() && v >= 0.0,
67        };
68        if !valid {
69            return Err(ConfigError::InvalidThreshold);
70        }
71        self.threshold = threshold;
72        Ok(self)
73    }
74
75    /// Silence shorter than this counts as sound, so stop closures inside words stay whole. This
76    /// also applies to silence at either end, but never fills silence covering the entire audio.
77    #[must_use]
78    pub fn min_silence(mut self, d: Duration) -> Self {
79        self.min_silence = d;
80        self
81    }
82
83    /// Sound shorter than this counts as silence, which removes clicks.
84    #[must_use]
85    pub fn min_sound(mut self, d: Duration) -> Self {
86        self.min_sound = d;
87        self
88    }
89
90    /// Silence kept before sound (`pre`) and after it (`tail`), for onsets and reverb tails.
91    ///
92    /// When the padding of two sounds overlaps, the overlap is split in the middle.
93    #[must_use]
94    pub fn padding(mut self, pre: Duration, tail: Duration) -> Self {
95        self.pre = pre;
96        self.tail = tail;
97        self
98    }
99}
100
101/// A half-open range `[start, end)` of original samples.
102#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
103#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
104#[non_exhaustive]
105pub struct Span {
106    /// First sample.
107    pub start: u64,
108    /// One past the last sample.
109    pub end: u64,
110    /// Whether the range is silence or sound.
111    pub kind: Kind,
112}
113
114/// The content of a [`Span`].
115#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
116#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
117#[non_exhaustive]
118pub enum Kind {
119    /// Below the threshold.
120    Silence,
121    /// Sound, including its padding.
122    Sound,
123}
124
125/// Smallest dB range between the floor and the reference when normalizing levels.
126const MIN_RANGE_DB: f64 = 20.0;
127
128/// Levels resolved against one analysis and a segmentation threshold.
129///
130/// PCM values are in dBFS; external scores are probabilities. Signal-free PCM frames are excluded
131/// from the percentiles. Obtain these values with [`Analysis::levels`].
132#[derive(Clone, Copy, Debug)]
133#[non_exhaustive]
134pub struct Levels {
135    /// 10th percentile of signal-bearing frame values.
136    pub floor: f32,
137    /// 99th percentile of signal-bearing frame values.
138    pub reference: f32,
139    /// Level at which silence becomes sound.
140    pub on: f32,
141    /// Sound ends below this level.
142    pub off: f32,
143}
144
145impl Levels {
146    pub(crate) fn new(analysis: &Analysis, threshold: Threshold) -> Self {
147        let mut values: Vec<f32> = analysis
148            .values()
149            .iter()
150            .zip(analysis.no_signal())
151            .filter(|(_, no_signal)| !**no_signal)
152            .map(|(v, _)| *v)
153            .collect();
154        if values.is_empty() {
155            return Self {
156                floor: 0.0,
157                reference: 0.0,
158                on: f32::INFINITY,
159                off: f32::INFINITY,
160            };
161        }
162        values.sort_unstable_by(f32::total_cmp);
163        let percentile = |p: usize| values[percentile_index(values.len(), p)];
164        let floor = percentile(10);
165        let reference = percentile(99);
166        let (on, off) = match (analysis.domain(), threshold) {
167            (Domain::Decibels, Threshold::Auto) => {
168                let on = (floor + 4.0).max((floor + 6.0).min(reference - 20.0));
169                // A threshold above the reference cannot distinguish a steady sound from noise.
170                // Keep steady input; an absolute threshold can reject noise at a known level.
171                let on = if on > reference { floor } else { on };
172                (on, on - 3.0)
173            }
174            (Domain::Scores, Threshold::Auto) => (0.5, 0.35),
175            (_, Threshold::Abs(v)) => (v, v),
176            (_, Threshold::BelowRef(v)) => (reference - v, reference - v),
177        };
178        Self {
179            floor,
180            reference,
181            on,
182            off,
183        }
184    }
185
186    /// Frame value mapped to `0.0..=1.0` between the floor and the reference.
187    ///
188    /// The dB range is at least [`MIN_RANGE_DB`], so level ripple in flat audio does not stretch
189    /// to the full range and outweigh the length costs.
190    pub(crate) fn normalize(&self, domain: Domain, value: f64) -> f64 {
191        match domain {
192            Domain::Scores => value.clamp(0.0, 1.0),
193            Domain::Decibels => {
194                let range = f64::from(self.reference - self.floor).max(MIN_RANGE_DB);
195                ((value - f64::from(self.floor)) / range).clamp(0.0, 1.0)
196            }
197        }
198    }
199
200    /// Whether each frame is below the `off` threshold.
201    pub(crate) fn below_off(&self, analysis: &Analysis) -> Vec<bool> {
202        analysis
203            .values()
204            .iter()
205            .zip(analysis.no_signal())
206            .map(|(v, no_signal)| *no_signal || *v < self.off)
207            .collect()
208    }
209}
210
211/// Rounded percentile index, without overflowing a 32-bit `usize` for long recordings.
212fn percentile_index(len: usize, percentile: usize) -> usize {
213    ((percentile as u64 * (len - 1) as u64 + 50) / 100) as usize
214}
215
216/// Silence runs in frames after hysteresis and the minimum lengths, without padding.
217pub(crate) fn silence_runs(
218    analysis: &Analysis,
219    levels: &Levels,
220    config: &SegmentConfig,
221) -> Vec<Range<usize>> {
222    let mut sound = Vec::with_capacity(analysis.frames());
223    let mut state = false;
224    for (v, no_signal) in analysis.values().iter().zip(analysis.no_signal()) {
225        state = !*no_signal
226            && if state {
227                *v >= levels.off
228            } else {
229                *v >= levels.on
230            };
231        sound.push(state);
232    }
233    fill_short_runs(&mut sound, true, analysis.frames_in(config.min_sound));
234    if sound.iter().any(|s| *s) {
235        fill_short_runs(&mut sound, false, analysis.frames_in(config.min_silence));
236    }
237    runs(&sound)
238        .filter(|(loud, _)| !loud)
239        .map(|(_, r)| r)
240        .collect()
241}
242
243/// Flips runs of `kind` shorter than `min` frames to the other kind.
244fn fill_short_runs(flags: &mut [bool], kind: bool, min: usize) {
245    let short: Vec<Range<usize>> = runs(flags)
246        .filter(|(k, r)| *k == kind && r.len() < min)
247        .map(|(_, r)| r)
248        .collect();
249    for r in short {
250        flags[r].fill(!kind);
251    }
252}
253
254/// Maximal runs of equal flags.
255pub(crate) fn runs(flags: &[bool]) -> impl Iterator<Item = (bool, Range<usize>)> + '_ {
256    let mut start = 0;
257    core::iter::from_fn(move || {
258        let kind = *flags.get(start)?;
259        let len = flags[start..].iter().take_while(|f| **f == kind).count();
260        let run = start..start + len;
261        start += len;
262        Some((kind, run))
263    })
264}
265
266/// The middle of the overlap of two paddings, kept within the silence between the sounds.
267///
268/// `next_start` is the padded start of the later sound and `prev_end` the padded end of the
269/// earlier one, so the overlap is `[next_start, prev_end)`.
270pub(crate) fn split_point(next_start: usize, prev_end: usize, silence: &Range<usize>) -> usize {
271    next_start
272        .midpoint(prev_end)
273        .clamp(silence.start, silence.end)
274}
275
276impl Analysis {
277    /// The floor, reference and thresholds used for segmentation, or `None` when the analysis
278    /// is empty or every PCM frame is signal-free. Such an analysis is entirely silent.
279    #[must_use]
280    pub fn levels(&self, config: &SegmentConfig) -> Option<Levels> {
281        if self.no_signal().iter().all(|no_signal| *no_signal) {
282            None
283        } else {
284            Some(Levels::new(self, config.threshold))
285        }
286    }
287
288    /// Silence and sound spans covering the whole audio in order.
289    ///
290    /// Sound spans include their padding. Two sound spans are adjacent without silence between
291    /// them when their paddings overlapped.
292    #[must_use]
293    pub fn segments(&self, config: &SegmentConfig) -> Vec<Span> {
294        let sounds = self.padded_sounds(config);
295        let mut spans = Vec::with_capacity(2 * sounds.len() + 1);
296        let mut at = 0;
297        for r in sounds {
298            if r.start > at {
299                spans.push(self.span(at, r.start, Kind::Silence));
300            }
301            spans.push(self.span(r.start, r.end, Kind::Sound));
302            at = r.end;
303        }
304        if at < self.frames() {
305            spans.push(self.span(at, self.frames(), Kind::Silence));
306        }
307        spans
308    }
309
310    /// The samples from the start of the first sound to the end of the last, padding included,
311    /// or `None` if there is no sound.
312    #[must_use]
313    pub fn trim(&self, config: &SegmentConfig) -> Option<Range<u64>> {
314        let sounds = self.padded_sounds(config);
315        let first = sounds.first()?;
316        let last = sounds.last()?;
317        Some(self.position(first.start)..self.position(last.end))
318    }
319
320    fn span(&self, start: usize, end: usize, kind: Kind) -> Span {
321        Span {
322            start: self.position(start),
323            end: self.position(end),
324            kind,
325        }
326    }
327
328    /// Sound runs in frames with padding applied.
329    fn padded_sounds(&self, config: &SegmentConfig) -> Vec<Range<usize>> {
330        let levels = Levels::new(self, config.threshold);
331        let silences = silence_runs(self, &levels, config);
332        let (pre, tail) = (self.frames_in(config.pre), self.frames_in(config.tail));
333        let n = self.frames();
334        let mut sounds: Vec<Range<usize>> = Vec::new();
335        let mut at = 0;
336        let mut gap = 0..0;
337        for silence in silences.iter().chain(core::iter::once(&(n..n))) {
338            if silence.start > at {
339                let mut start = at.saturating_sub(pre);
340                let end = silence.start.saturating_add(tail).min(n);
341                if let Some(prev) = sounds.last_mut() {
342                    if start < prev.end {
343                        let mid = split_point(start, prev.end, &gap);
344                        prev.end = mid;
345                        start = mid;
346                    }
347                }
348                sounds.push(start..end);
349            }
350            at = silence.end;
351            gap = silence.clone();
352        }
353        sounds
354    }
355}
356
357#[cfg(test)]
358mod tests {
359    use super::percentile_index;
360
361    #[test]
362    fn percentile_arithmetic_covers_long_32_bit_recordings() {
363        assert_eq!(percentile_index(44_000_001, 99), 43_560_000);
364        assert_eq!(percentile_index(44_000_001, 10), 4_400_000);
365        assert_eq!(percentile_index(1, 99), 0);
366        assert_eq!(percentile_index(6, 10), 1);
367    }
368}