pesq 0.2.0

Pure Rust implementation of ITU-T P.862 PESQ speech quality assessment
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
//! Perceptual model part 1: spectra, Bark warping, loudness, scaling
//! (spec 03).
//!
//! [`run_frame_loop`] runs sections 3.1 to 3.7 over the saved model
//! copies of the two signals (spec 01 section 1.4 step 2), equalized to
//! a common nominal length (spec 01 section 1.7), with the per-utterance
//! delays of spec 01 sections 1.10 to 1.13. It produces the per-frame
//! pitch power densities, loudness densities, silence flags, and
//! reference audible powers that spec 04 consumes. The rate is taken
//! from the reference buffer: every constant here is rate-selected
//! (spec 06, 6.4 and 6.6).

mod table;
mod table16;

use crate::types::{FrameRange, RATE_8K, Rate, SignalBuffer, Utterance};
use rustfft::Fft;
use rustfft::num_complex::Complex;

/// Frame length F in samples, 32 ms (spec 03, 3.1).
pub const FRAME_LEN: usize = RATE_8K.frame_len();

/// Frame hop Q in samples, 16 ms (spec 03, 3.1).
pub const FRAME_HOP: usize = RATE_8K.frame_hop();

/// Number of Bark bands B for the 8 kHz narrowband mode (spec 03, 3.3
/// and 3.8).
pub const NUM_BANDS: usize = RATE_8K.num_bands();

/// Number of power spectrum bins the band grouping of spec 03 section
/// 3.3 consumes: bins 0..=127 at 8 kHz. The grouping starts at bin 0
/// (the already-zeroed DC bin) and the group counts of Table 1 sum to
/// F/2. The Nyquist bin is not produced by section 3.2 and is not part
/// of the grouping.
pub const NUM_POWER_BINS: usize = RATE_8K.num_power_bins();

/// Absolute-sum threshold of the 5-sample silence skip probes
/// (spec 03, 3.1 steps 1 and 2).
const SILENCE_SKIP_THRESHOLD: f64 = 500.0;

/// Audibility factor of the silence flag (spec 03, 3.4 step 2).
const SILENCE_FLAG_FACTOR: f64 = 100.0;

/// Silence flag threshold on the audible power (spec 03, 3.4 step 2).
const SILENCE_FLAG_POWER: f64 = 1e7;

/// Audibility factor of the compensation averaging (spec 03, 3.5 step 1).
const COMPENSATION_FACTOR: f64 = 100.0;

/// Offset added to both per-band averages in the compensation ratio
/// (spec 03, 3.5 step 3).
const COMPENSATION_OFFSET: f64 = 1000.0;

/// Compensation factor clamp bounds (spec 03, 3.5 step 3).
const COMPENSATION_MIN: f64 = 0.01;
const COMPENSATION_MAX: f64 = 100.0;

/// Offset added to both audible powers in the local scale ratio
/// (spec 03, 3.7 step 2).
const SCALE_OFFSET: f64 = 5000.0;

/// Smoothing weights of the local scale (spec 03, 3.7 step 3).
const SCALE_SMOOTH_PREVIOUS: f64 = 0.2;
const SCALE_SMOOTH_CURRENT: f64 = 0.8;

/// Local scale clamp bounds (spec 03, 3.7 step 5).
const SCALE_MIN: f64 = 3e-4;
const SCALE_MAX: f64 = 5.0;

/// Bark width `w[b]` of the rate's Table 1 (spec 03, 3.8 and spec 06,
/// 6.4.1), the band weight of the disturbance norm of spec 04 section
/// 4.2.
pub fn bark_width(band: usize, rate: Rate) -> f32 {
    table::bark_table(rate)[band].bark_width
}

/// Short-term power spectra of spec 03 section 3.2, holding the FFT
/// plan, the Hann window, and a scratch buffer shared by all frames.
struct Spectra {
    fft: std::sync::Arc<dyn Fft<f32>>,
    window: Vec<f32>,
    scratch: Vec<Complex<f32>>,
    power_bins: usize,
}

impl Spectra {
    fn new(rate: Rate) -> Self {
        Self {
            fft: crate::dsp_fft::forward_plan(rate.frame_len()),
            window: crate::dsp::hann_window(rate.frame_len()),
            scratch: Vec::with_capacity(rate.frame_len()),
            power_bins: rate.num_power_bins(),
        }
    }

    /// Power spectrum of the frame starting at sample `start`: window
    /// with the Hann window, forward FFT, `real^2 + imag^2` per bin, and
    /// bin 0 forced to zero (spec 03, 3.2 steps 1 to 3). The output
    /// covers bins 0..=F/2 - 1; the band grouping of 3.3 consumes all of
    /// them starting at bin 0.
    fn power(&mut self, samples: &[f32], start: usize, out: &mut [f64]) {
        debug_assert_eq!(out.len(), self.power_bins);
        self.scratch.clear();
        self.scratch.extend(
            self.window
                .iter()
                .enumerate()
                .map(|(i, &weight)| Complex::new(samples[start + i] * weight, 0.0)),
        );
        self.fft.process(&mut self.scratch);
        for (bin, value) in self.scratch.iter().take(self.power_bins).enumerate() {
            out[bin] = f64::from(value.re * value.re + value.im * value.im);
        }
        out[0] = 0.0;
    }
}

/// Start-of-signal silence skip of spec 03 section 3.1 step 1: the
/// first s whose 5-sample absolute sum at margin + s reaches 500, capped
/// at Nmax / 2.
fn silence_skip_start(reference: &SignalBuffer, n_max: usize) -> usize {
    let margin = reference.rate.margin_samples();
    let mut skip = 0;
    while skip < n_max / 2
        && (0..5)
            .map(|i| f64::from(reference.samples[margin + skip + i].abs()))
            .sum::<f64>()
            < SILENCE_SKIP_THRESHOLD
    {
        skip += 1;
    }
    skip
}

/// End-of-signal silence skip of spec 03 section 3.1 step 2: the mirror
/// of [`silence_skip_start`] probing backward from sample
/// `Nmax - margin + P - 1`.
fn silence_skip_end(reference: &SignalBuffer, n_max: usize) -> usize {
    let margin = reference.rate.margin_samples();
    let last = n_max - margin + reference.rate.padding_samples() - 1;
    let mut skip = 0;
    while skip < n_max / 2
        && (0..5)
            .map(|i| f64::from(reference.samples[last - skip - i].abs()))
            .sum::<f64>()
            < SILENCE_SKIP_THRESHOLD
    {
        skip += 1;
    }
    skip
}

/// Frame range of spec 03 section 3.1: first processed frame
/// `skip_start / Q` (step 3), last processed frame
/// `(Nmax - 2*margin + P - skip_end) / Q - 1` (step 4), integer
/// divisions (spec 01, 1.1). `n_max` is the common nominal length Nmax
/// of spec 01 section 1.7 (the larger of the two nominal lengths), the
/// length both saved buffers have after equalization. With a fully
/// silent signal `stop` can fall below `start`; the frame loop then
/// processes an empty range.
pub fn frame_range(reference: &SignalBuffer, n_max: usize) -> FrameRange {
    let rate = reference.rate;
    let skip_start = silence_skip_start(reference, n_max);
    let skip_end = silence_skip_end(reference, n_max);
    let start = skip_start / rate.frame_hop();
    let stop = ((n_max - 2 * rate.margin_samples() + rate.padding_samples() - skip_end)
        / rate.frame_hop())
    .saturating_sub(1);
    FrameRange {
        start,
        stop,
        skip_start,
        skip_end,
    }
}

/// Delay of the governing utterance of a reference start sample: the
/// last utterance u with `start[u] * W <= r0`, the first utterance's
/// delay when none governs (spec 03, 3.2 step 4). The per-utterance
/// delay is the fine delay of spec 01 section 1.10 step 8, which already
/// includes the coarse estimate. Shared with the disturbance stage
/// (spec 04, 4.5.2 step 2).
pub(crate) fn governing_delay(r0: usize, utterances: &[Utterance], rate: Rate) -> i32 {
    utterances
        .iter()
        .rev()
        .find(|u| u.start_window * rate.window_samples() <= r0)
        .or_else(|| utterances.first())
        .map_or(0, |u| u.fine_delay)
}

/// Degraded frame start `d0 = r0 + delay`; `None` when the frame lies
/// out of bounds and the degraded spectrum must be all zeros
/// (spec 03, 3.2 step 4).
fn degraded_start(r0: usize, n_max: usize, utterances: &[Utterance], rate: Rate) -> Option<usize> {
    let d0 = r0 as i64 + i64::from(governing_delay(r0, utterances, rate));
    if d0 <= 0 || d0 + rate.frame_len() as i64 >= (n_max + rate.padding_samples()) as i64 {
        return None;
    }
    Some(d0 as usize)
}

/// Warp a power spectrum into the rate's Bark bands (spec 03, section
/// 3.3): band b sums the next `n[b]` bins starting at bin 0 (the
/// already-zeroed DC bin), consuming bins 0..=F/2 - 1, then multiplies
/// by the correction factor `c[b]` and by Sp. The sums accumulate in
/// f64 and the result is stored as f32 (spec 01, 1.1).
pub fn warp_to_bark(power: &[f64], rate: Rate) -> Vec<f32> {
    let mut density = vec![0.0f32; rate.num_bands()];
    let mut bin = 0;
    for (band, row) in table::bark_table(rate).iter().enumerate() {
        let sum: f64 = power[bin..bin + row.bins].iter().sum();
        bin += row.bins;
        density[band] = (sum * f64::from(row.correction) * rate.pitch_power_scale()) as f32;
    }
    debug_assert_eq!(bin, rate.num_power_bins());
    density
}

/// Audible power of a frame with a factor (spec 03, 3.4 step 1): the
/// sum over bands 1..=B-1 (band 0 excluded) of the densities that exceed
/// `factor * t[b]`.
pub fn audible_power(density: &[f32], factor: f64, rate: Rate) -> f64 {
    let bands = table::bark_table(rate);
    let mut total = 0.0f64;
    for (band, &p) in density.iter().enumerate().skip(1) {
        if f64::from(p) > factor * f64::from(bands[band].threshold) {
            total += f64::from(p);
        }
    }
    total
}

/// Zwicker loudness density of one band (spec 03, 3.6), including the
/// loudness scaling Sl of step 4. Computed in f64 and stored as f32
/// (spec 01, 1.1).
pub fn zwicker_loudness(pitch_power: f32, band: usize, rate: Rate) -> f32 {
    let row = &table::bark_table(rate)[band];
    let threshold = f64::from(row.threshold);
    let p = f64::from(pitch_power);
    if p <= threshold {
        return 0.0;
    }
    // Low-band correction (step 1): below 4 Bark, h = 6 / (bark + 2),
    // capped at 2, raised to the power 0.15.
    let h = (if row.bark_centre < 4.0 {
        (6.0 / (f64::from(row.bark_centre) + 2.0)).min(2.0)
    } else {
        1.0
    })
    .powf(0.15);
    // Modified Zwicker exponent (step 2) and the power law (step 3).
    let z = 0.23 * h;
    let loudness = (threshold / 0.5).powf(z) * ((0.5 + 0.5 * p / threshold).powf(z) - 1.0);
    (loudness * rate.loudness_scale()) as f32
}

/// Compensation factor of spec 03 section 3.5 step 3: the ratio of the
/// per-band averages with a +1000 offset on both sides, clamped to
/// [0.01, 100].
pub fn compensation_factor(avg_ref: f64, avg_deg: f64) -> f64 {
    ((avg_deg + COMPENSATION_OFFSET) / (avg_ref + COMPENSATION_OFFSET))
        .clamp(COMPENSATION_MIN, COMPENSATION_MAX)
}

/// One step of the local gain scaling of spec 03 section 3.7 steps 2 to
/// 5. The pair is (unclamped, clamped): step 4 stores the unclamped
/// value as the next frame's previous scale, before the clamp of step 5.
pub fn local_scale(a_ref: f64, a_deg: f64, previous: f64, frame: usize) -> (f64, f64) {
    let raw = (a_ref + SCALE_OFFSET) / (a_deg + SCALE_OFFSET);
    let unclamped = if frame > 0 {
        SCALE_SMOOTH_PREVIOUS * previous + SCALE_SMOOTH_CURRENT * raw
    } else {
        raw
    };
    (unclamped, unclamped.clamp(SCALE_MIN, SCALE_MAX))
}

/// Output of the perceptual model frame loop (spec 03, sections 3.1 to
/// 3.7), the input to the disturbance stage of spec 04.
///
/// The density arrays are flat with `frame * B + band` indexing and hold
/// `frame_stop + 1` entries (spec 03, 3.1 step 5). Pitch densities cover
/// frames 0..=frame_stop because the compensation averages of 3.5 span
/// that range; loudness and audible power are only produced for the
/// processed range `[frame_start, frame_stop]` and are zero before it.
#[derive(Debug, Clone)]
pub struct PerceptualModel {
    /// Sample rate this model was computed at; B derives from it.
    pub rate: Rate,
    /// Processed frame range of spec 03 section 3.1.
    pub frame_range: FrameRange,
    /// Reference pitch power densities after the compensation of spec 03
    /// section 3.5.
    pub pitch_ref: Vec<f32>,
    /// Degraded pitch power densities after the local gain scaling of
    /// spec 03 section 3.7.
    pub pitch_deg: Vec<f32>,
    /// Reference loudness densities (spec 03, 3.6).
    pub loudness_ref: Vec<f32>,
    /// Degraded loudness densities (spec 03, 3.6), from the scaled
    /// degraded densities (spec 03, 3.7 step 6).
    pub loudness_deg: Vec<f32>,
    /// Silence flag per frame (spec 03, 3.4 step 2).
    pub silence_flags: Vec<bool>,
    /// Reference audible power per frame, stored by spec 03 section 3.7
    /// step 7 and consumed by spec 04 section 4.6.
    pub audible_ref: Vec<f32>,
}

impl PerceptualModel {
    /// Stored frame count: `frame_stop + 1` (spec 03, 3.1 step 5).
    pub fn frame_count(&self) -> usize {
        self.silence_flags.len()
    }

    /// Reference pitch power density of one frame and band.
    pub fn pitch_ref_at(&self, frame: usize, band: usize) -> f32 {
        self.pitch_ref[frame * self.rate.num_bands() + band]
    }

    /// Degraded pitch power density of one frame and band.
    pub fn pitch_deg_at(&self, frame: usize, band: usize) -> f32 {
        self.pitch_deg[frame * self.rate.num_bands() + band]
    }

    /// Reference loudness density of one frame and band.
    pub fn loudness_ref_at(&self, frame: usize, band: usize) -> f32 {
        self.loudness_ref[frame * self.rate.num_bands() + band]
    }

    /// Degraded loudness density of one frame and band.
    pub fn loudness_deg_at(&self, frame: usize, band: usize) -> f32 {
        self.loudness_deg[frame * self.rate.num_bands() + band]
    }
}

/// Run the frame loop of spec 03: frame range (3.1), power spectra
/// (3.2), Bark warping (3.3), audibility and silence flags (3.4),
/// frequency response compensation (3.5), Zwicker loudness (3.6), and
/// local gain scaling (3.7). The disturbance steps of spec 04 continue
/// from the returned [`PerceptualModel`].
///
/// The inputs are the saved model copies of spec 01 section 1.4 step 2,
/// equalized to the common nominal length (spec 01, 1.7), and the
/// per-utterance delays of spec 01 sections 1.10 to 1.13.
pub fn run_frame_loop(
    reference: &SignalBuffer,
    degraded: &SignalBuffer,
    utterances: &[Utterance],
) -> PerceptualModel {
    // The common nominal length Nmax of spec 01 section 1.7: both saved
    // buffers have Nmax + P samples after equalization, and the frame
    // layout (3.1), the degraded bounds (3.2 step 4), and the
    // compensation divisor (3.5 step 1) all take Nmax, not the
    // reference's own nominal length.
    let rate = reference.rate;
    let bands = rate.num_bands();
    let n_max = reference.nominal_len.max(degraded.nominal_len);
    let frame_range = frame_range(reference, n_max);
    let frame_count = frame_range.stop + 1;
    let mut spectra = Spectra::new(rate);

    let mut pitch_ref = vec![0.0f32; frame_count * bands];
    let mut pitch_deg = vec![0.0f32; frame_count * bands];
    let mut silence_flags = vec![false; frame_count];
    let mut ref_sums = vec![0.0f64; bands];
    let mut deg_sums = vec![0.0f64; bands];
    let mut ref_power = vec![0.0f64; rate.num_power_bins()];
    let mut deg_power = vec![0.0f64; rate.num_power_bins()];

    // First pass: spectra, warping, silence flags, and the per-band sums
    // of the compensation averages (spec 03, 3.2 to 3.5 step 1).
    for frame in 0..=frame_range.stop {
        let r0 = rate.margin_samples() + frame * rate.frame_hop();
        spectra.power(&reference.samples, r0, &mut ref_power);
        let ref_density = warp_to_bark(&ref_power, rate);
        let deg_density = match degraded_start(r0, n_max, utterances, rate) {
            Some(d0) => {
                spectra.power(&degraded.samples, d0, &mut deg_power);
                warp_to_bark(&deg_power, rate)
            }
            None => vec![0.0f32; bands],
        };
        silence_flags[frame] =
            audible_power(&ref_density, SILENCE_FLAG_FACTOR, rate) < SILENCE_FLAG_POWER;
        for band in 0..bands {
            pitch_ref[frame * bands + band] = ref_density[band];
            pitch_deg[frame * bands + band] = deg_density[band];
            if silence_flags[frame] {
                continue;
            }
            let limit = COMPENSATION_FACTOR * f64::from(table::bark_table(rate)[band].threshold);
            if f64::from(ref_density[band]) > limit {
                ref_sums[band] += f64::from(ref_density[band]);
            }
            if f64::from(deg_density[band]) > limit {
                deg_sums[band] += f64::from(deg_density[band]);
            }
        }
    }

    // Compensation: per-band averages over the fixed divisor of spec 03
    // section 3.5 step 1, the clamped ratio of step 3, applied to every
    // reference frame (step 4).
    let divisor = (((n_max - 2 * rate.margin_samples() + rate.padding_samples())
        / rate.frame_hop())
        - 1) as f64;
    for band in 0..bands {
        let factor = compensation_factor(ref_sums[band] / divisor, deg_sums[band] / divisor);
        for frame in 0..=frame_range.stop {
            pitch_ref[frame * bands + band] =
                (f64::from(pitch_ref[frame * bands + band]) * factor) as f32;
        }
    }

    // Second pass over the processed range: local gain scaling and
    // loudness (spec 03, 3.6 and 3.7). The "frame > 0" condition of 3.7
    // step 3 uses the absolute frame index, so with a nonzero frame
    // start the first processed frame is smoothed against the initial
    // previous scale of 1 (step 3, initial state).
    let mut loudness_ref = vec![0.0f32; frame_count * bands];
    let mut loudness_deg = vec![0.0f32; frame_count * bands];
    let mut audible_ref = vec![0.0f32; frame_count];
    let mut previous_scale = 1.0;
    // The range governs the iteration count (empty when stop < start);
    // the zip writes the stored audible power without indexing by frame.
    for (frame, audible) in
        (frame_range.start..=frame_range.stop).zip(audible_ref.iter_mut().skip(frame_range.start))
    {
        let base = frame * bands;
        let a_ref = audible_power(&pitch_ref[base..base + bands], 1.0, rate);
        let a_deg = audible_power(&pitch_deg[base..base + bands], 1.0, rate);
        let (unclamped, clamped) = local_scale(a_ref, a_deg, previous_scale, frame);
        previous_scale = unclamped;
        *audible = a_ref as f32;
        for band in 0..bands {
            pitch_deg[base + band] *= clamped as f32;
        }
        for band in 0..bands {
            loudness_ref[base + band] = zwicker_loudness(pitch_ref[base + band], band, rate);
            loudness_deg[base + band] = zwicker_loudness(pitch_deg[base + band], band, rate);
        }
    }

    PerceptualModel {
        rate,
        frame_range,
        pitch_ref,
        pitch_deg,
        loudness_ref,
        loudness_deg,
        silence_flags,
        audible_ref,
    }
}

#[cfg(test)]
mod tests;