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