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
//! Coarse and fine time alignment (spec 01, sections 1.9 and 1.10) and
//! the utterance search windows (1.11).
//!
//! The coarse estimate correlates the log-domain VAD arrays with the FFT
//! procedure of spec 02 section 2.8; the fine estimate cross-correlates
//! Hann-windowed A-sample frames of the working buffers and votes lag
//! candidates into a histogram. The search windows of 1.11 delimit the
//! per-utterance alignment passes.

use crate::dsp::{circular_convolve, correlate, hann_window, spectral_cross_correlate};
use crate::types::{RATE_8K, RATE_16K, Rate, VadData};

/// Triangular smoothing kernel of spec 01 section 1.10 step 5, computed
/// once per rate: kernel[0] = 1 and kernel[k] = kernel[A - k] =
/// 1 - k/K for k = 1..=K-1, zeros elsewhere, with radius K = A/64
/// (spec 01, 1.10 step 5).
fn smooth_kernel(rate: Rate) -> &'static [f32] {
    use std::sync::OnceLock;
    static KERNEL_8K: OnceLock<Vec<f32>> = OnceLock::new();
    static KERNEL_16K: OnceLock<Vec<f32>> = OnceLock::new();
    let slot = match rate {
        RATE_8K => &KERNEL_8K,
        RATE_16K => &KERNEL_16K,
    };
    slot.get_or_init(|| {
        let align_fft_len = rate.align_fft_len();
        let radius = align_fft_len / 64;
        let mut kernel = vec![0.0f32; align_fft_len];
        kernel[0] = 1.0;
        for k in 1..radius {
            let value = 1.0 - k as f32 / radius as f32;
            kernel[k] = value;
            kernel[align_fft_len - k] = value;
        }
        kernel
    })
}

/// Fine-alignment frame advance, A/4 samples (spec 01, 1.10 step 4e).
fn fine_advance(rate: Rate) -> usize {
    rate.align_fft_len() / 4
}

/// Whole-signal coarse delay estimation of spec 01 section 1.9 steps 1
/// to 6: the FFT cross-correlation of the two log-VAD arrays, the strict
/// maximizer starting from value 0 at index Vr - 1, and the conversion
/// to samples.
pub fn coarse_delay_whole(reference: &VadData, degraded: &VadData, rate: Rate) -> i32 {
    let x = &reference.log_vad;
    let y = &degraded.log_vad;
    if x.len() <= 1 || y.len() <= 1 {
        return 0;
    }
    lag_from_correlation(&correlate(x, y), x.len(), rate.window_samples())
}

/// Per-utterance coarse estimate of spec 01 section 1.9 step 7, seeded
/// with the whole-signal or utterance coarse delay `seed`, restricted to
/// the search window `[s0, s1)` of the reference. The seed itself is
/// returned when the correlation does not run.
pub fn coarse_delay_search(
    reference: &VadData,
    degraded: &VadData,
    s0: usize,
    s1: usize,
    seed: i32,
    rate: Rate,
) -> i32 {
    match coarse_correlation(reference, degraded, s0, s1, seed, rate) {
        Some((estimate, _)) => estimate,
        None => seed,
    }
}

/// Fine time alignment of spec 01 section 1.10 for one utterance search
/// window `[s0, s1]` and initial delay `d0`, returning the fine delay in
/// samples and its confidence.
///
/// `reference` and `degraded` are the working buffers (after 1.5 and
/// 1.6) and `degraded_nominal` is the degraded nominal length N.
pub fn fine_delay(
    reference: &[f32],
    degraded: &[f32],
    s0: usize,
    s1: usize,
    d0: i32,
    degraded_nominal: usize,
    rate: Rate,
) -> (i32, f32) {
    let align_fft_len = rate.align_fft_len();
    let window = hann_window(align_fft_len);
    let mut histogram = vec![0.0f32; align_fft_len];

    // Step 3: the cursors, with the negative-degraded-cursor clamp that
    // replaces (not adds to) the reference cursor.
    let mut ref_cursor = (s0 * rate.window_samples()) as i64;
    let mut deg_cursor = ref_cursor + i64::from(d0);
    if deg_cursor < 0 {
        ref_cursor = i64::from(-d0);
        deg_cursor = 0;
    }

    // Step 4: accumulate the weighted lag histogram over A-sample frames
    // with a 75 percent overlap. Step 4c takes the absolute values of
    // the correlation; v is 0.99 times the maximum of those absolute
    // values, and every lag whose absolute value exceeds v votes
    // (step 4d).
    let mut frame_ref = vec![0.0f32; align_fft_len];
    let mut frame_deg = vec![0.0f32; align_fft_len];
    while deg_cursor + align_fft_len as i64 <= degraded_nominal as i64
        && ref_cursor + align_fft_len as i64 <= (s1 * rate.window_samples()) as i64
    {
        let ref_start = ref_cursor as usize;
        let deg_start = deg_cursor as usize;
        for i in 0..align_fft_len {
            frame_ref[i] = window[i] * reference[ref_start + i];
            frame_deg[i] = window[i] * degraded[deg_start + i];
        }
        let spectrum = spectral_cross_correlate(&frame_ref, &frame_deg);
        let peak = spectrum
            .iter()
            .map(|value| value.abs())
            .fold(0.0f32, f32::max);
        let threshold = 0.99 * peak;
        let weight = threshold.powf(0.125);
        for (lag, &value) in spectrum.iter().enumerate() {
            if value.abs() > threshold {
                histogram[lag] += weight;
            }
        }
        ref_cursor += fine_advance(rate) as i64;
        deg_cursor += fine_advance(rate) as i64;
    }

    // Step 6 before step 5: the normalization divisor Hsum is the sum of
    // the raw histogram, captured before the smoothing of step 5.
    let raw_sum: f64 = histogram.iter().map(|&h| f64::from(h)).sum();

    // Step 5: circular smoothing with the triangular kernel of radius
    // K = 8: kernel[0] = 1 and kernel[k] = kernel[A - k] = 1 - k/8 for
    // k = 1..=7. The kernel is a constant, computed once per process.
    histogram = circular_convolve(&histogram, smooth_kernel(rate));

    // Step 6: divide the smoothed histogram by the raw sum.
    if raw_sum > 0.0 {
        let raw_sum = raw_sum as f32;
        for h in histogram.iter_mut() {
            *h = (*h / raw_sum).abs();
        }
    } else {
        histogram.fill(0.0);
    }

    // Steps 7 and 8: the peak lag, folded into [-A/2, A/2), and the
    // final delay plus confidence.
    let mut peak_index = 0usize;
    let mut peak_value = 0.0f32;
    for (lag, &value) in histogram.iter().enumerate() {
        if value > peak_value {
            peak_value = value;
            peak_index = lag;
        }
    }
    let folded = if peak_index >= align_fft_len / 2 {
        peak_index as i32 - align_fft_len as i32
    } else {
        peak_index as i32
    };
    (d0 + folded, peak_value)
}

/// Lag conversion of spec 01 section 1.9 step 5 for a correlation
/// output whose first sequence had `vr` elements.
fn lag_from_correlation(correlation: &[f32], vr: usize, window_samples: usize) -> i32 {
    let (best_index, _) = maximizer(correlation, vr - 1);
    (best_index as i32 - vr as i32 + 1) * window_samples as i32
}

/// Strict maximizer of spec 01 section 1.9 step 4: starts with value 0
/// at index `vr` and updates only on strict improvement.
fn maximizer(values: &[f32], vr: usize) -> (usize, f32) {
    let mut best_value = 0.0f32;
    let mut best_index = vr;
    for (index, &value) in values.iter().enumerate() {
        if value > best_value {
            best_value = value;
            best_index = index;
        }
    }
    (best_index, best_value)
}

/// Utterance search windows of spec 01 section 1.11: runs of speech
/// windows (energy above zero, step 2) qualifying as utterances yield
/// windows widened by the 75-window margin.
pub fn search_windows(
    reference: &VadData,
    coarse_delay: i32,
    degraded_nominal: usize,
    rate: Rate,
) -> Vec<(usize, usize)> {
    let last = reference.window_count - 1;
    qualifying_runs(reference, coarse_delay, degraded_nominal, rate)
        .into_iter()
        .map(|(a, c)| (a.saturating_sub(75), (c + 75).min(last)))
        .collect()
}

/// Qualifying utterance runs of spec 01 sections 1.11 and 1.12 step 1:
/// maximal runs of speech windows (`energy[v] > 0`) that satisfy the
/// length and degradation-bound conditions of 1.11 step 3, as (start,
/// trigger) pairs. The trigger `c` is exclusive for a non-speech
/// trigger and `V - 1` (inclusive) for a run reaching the last window.
pub fn qualifying_runs(
    reference: &VadData,
    coarse_delay: i32,
    degraded_nominal: usize,
    rate: Rate,
) -> Vec<(usize, usize)> {
    let window_divisor = rate.window_samples() as i32;
    let b1 = 50 - coarse_delay / window_divisor;
    let b2 = (degraded_nominal as i32 - coarse_delay) / window_divisor - 50;
    let last = reference.window_count - 1;
    let mut runs = Vec::new();
    let mut a = 0usize;
    while a < reference.window_count {
        if reference.energy[a] == 0.0 {
            a += 1;
            continue;
        }
        let start = a;
        while a < reference.window_count && reference.energy[a] > 0.0 {
            a += 1;
        }
        let (c, length) = if a == reference.window_count {
            (last, last - start)
        } else {
            (a, a - start)
        };
        if length >= 50 && (start as i64) < i64::from(b2) && (c as i64) > i64::from(b1) {
            runs.push((start, c));
        }
    }
    runs
}

/// Per-utterance coarse correlation of spec 01 section 1.9 step 7,
/// returning the raw correlation output alongside the estimate.
///
/// The clamps of step 7 apply as in [`coarse_delay_search`]: the
/// degraded start sd = s0 + seed/W, with s0 moved right when sd would
/// be negative, and nd = nr shortened to the degraded window count.
/// Returns `None` when the correlation does not run (either clamped
/// length at most 1, or the clamp moved s0 past s1), in which case the
/// estimate is the seed.
///
/// The split passes of spec 01 section 1.13 step 4 need the raw output
/// values: each correlation writes nr + nd - 1 values at scratch
/// offsets 0..nr + nd - 2 and thereby corrupts the split-pass window
/// that shares the scratch (spec 01, section 1.13.1).
pub(crate) fn coarse_correlation(
    reference: &VadData,
    degraded: &VadData,
    s0: usize,
    s1: usize,
    seed: i32,
    rate: Rate,
) -> Option<(i32, Vec<f32>)> {
    let window_divisor = rate.window_samples() as i32;
    let mut s0 = s0;
    let mut sd = s0 as i32 + seed / window_divisor;
    if sd < 0 {
        s0 = ((-seed) / window_divisor) as usize;
        sd = 0;
    }
    if s0 >= s1 {
        return None;
    }
    let nr = s1 - s0;
    let mut nd = nr;
    if sd as usize + nd > degraded.window_count {
        nd = degraded.window_count - sd as usize;
    }
    if nr <= 1 || nd <= 1 {
        return None;
    }
    let x = &reference.log_vad[s0..s0 + nr];
    let y = &degraded.log_vad[sd as usize..sd as usize + nd];
    let correlation = correlate(x, y);
    let (best_index, _) = maximizer(&correlation, nr - 1);
    Some((
        (best_index as i32 - nr as i32 + 1) * window_divisor + seed,
        correlation,
    ))
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{RATE_8K, SignalBuffer, WINDOW_SAMPLES};

    /// VAD data with one burst of `run` speech windows starting at
    /// `onset`, inside `total` windows.
    fn vad_with_burst(total: usize, onset: usize, run: usize) -> VadData {
        let mut energy = vec![0.0f32; total];
        for e in energy[onset..onset + run].iter_mut() {
            *e = 1.0;
        }
        let log_vad = energy
            .iter()
            .map(|&e| if e > 0.0 { 1.0 } else { 0.0 })
            .collect();
        VadData {
            window_count: total,
            energy,
            log_vad,
            threshold: 0.5,
            signal_level: 1.0,
            noise_level: 0.0,
        }
    }

    #[test]
    fn coarse_delay_finds_a_shifted_log_vad_burst() {
        let total = 400usize;
        let shift = 6usize;
        let reference = vad_with_burst(total, 100, 40);
        let degraded = vad_with_burst(total, 100 + shift, 40);
        let lag = coarse_delay_whole(&reference, &degraded, RATE_8K);
        assert_eq!(lag, shift as i32 * WINDOW_SAMPLES as i32);
    }

    #[test]
    fn coarse_delay_is_zero_for_single_window_vad() {
        let tiny = vad_with_burst(1, 0, 1);
        assert_eq!(coarse_delay_whole(&tiny, &tiny, RATE_8K), 0);
    }

    #[test]
    fn per_utterance_coarse_seeds_from_the_window() {
        let total = 400usize;
        let reference = vad_with_burst(total, 100, 40);
        let degraded = vad_with_burst(total, 106, 40);
        let estimate = coarse_delay_search(&reference, &degraded, 25, 235, 0, RATE_8K);
        assert_eq!(estimate, 6 * WINDOW_SAMPLES as i32);
    }

    #[test]
    fn per_utterance_coarse_returns_the_seed_for_tiny_windows() {
        let reference = vad_with_burst(400, 100, 40);
        let degraded = vad_with_burst(400, 100, 40);
        assert_eq!(
            coarse_delay_search(&reference, &degraded, 100, 101, 17, RATE_8K),
            17
        );
    }

    /// A working-buffer pair where the degraded signal is the reference
    /// delayed by `shift` samples. The content is aperiodic noise so the
    /// cross-correlation has a single sharp peak at the true lag (a
    /// periodic tone would repeat its peaks every period).
    fn shifted_pair(shift: usize) -> (SignalBuffer, SignalBuffer) {
        let signal_len = 16000usize;
        let mut state = 99u32;
        let mut ref_pcm = vec![0i16; signal_len];
        for sample in ref_pcm[2000..12000].iter_mut() {
            state = state.wrapping_mul(1_664_525).wrapping_add(1_013_904_223);
            *sample = ((state as f32 / u32::MAX as f32) * 8000.0 - 4000.0) as i16;
        }
        let reference = SignalBuffer::from_pcm(&ref_pcm).unwrap();
        let mut deg_pcm = vec![0i16; shift];
        deg_pcm.extend_from_slice(&ref_pcm);
        let degraded = SignalBuffer::from_pcm(&deg_pcm[..signal_len]).unwrap();
        (reference, degraded)
    }

    #[test]
    fn fine_delay_recovers_a_known_sample_shift() {
        // The degraded copy is delayed by 64 samples, so the frames
        // correlate best at lag 64 and the fine delay is 64 samples.
        let (reference, degraded) = shifted_pair(64);
        let (delay, confidence) = fine_delay(
            &reference.samples,
            &degraded.samples,
            75,
            reference.nominal_len / WINDOW_SAMPLES - 75,
            0,
            degraded.nominal_len,
            RATE_8K,
        );
        assert_eq!(delay, 64);
        assert!(confidence > 0.0);
    }

    #[test]
    fn fine_delay_is_zero_for_identical_buffers() {
        let (reference, _) = shifted_pair(0);
        let (delay, confidence) = fine_delay(
            &reference.samples,
            &reference.samples,
            75,
            reference.nominal_len / WINDOW_SAMPLES - 75,
            0,
            reference.nominal_len,
            RATE_8K,
        );
        assert_eq!(delay, 0);
        assert!(confidence > 0.0);
    }

    #[test]
    fn fine_delay_respects_the_degraded_length_clamp() {
        // A degraded nominal length that ends before the first frame is
        // reached yields an empty histogram: the delay stays the seed
        // and the confidence is zero.
        let (reference, _) = shifted_pair(0);
        let (delay, confidence) = fine_delay(
            &reference.samples,
            &reference.samples,
            75,
            reference.nominal_len / WINDOW_SAMPLES - 75,
            0,
            WINDOW_SAMPLES,
            RATE_8K,
        );
        assert_eq!(delay, 0);
        assert_eq!(confidence, 0.0);
    }

    #[test]
    fn search_windows_follow_the_run_qualification_rules() {
        // Two 60-window bursts at [100, 160) and [300, 360) in 400
        // windows, no coarse delay: both qualify and widen by 75.
        let mut vad = vad_with_burst(400, 100, 60);
        for e in vad.energy[300..360].iter_mut() {
            *e = 1.0;
        }
        let windows = search_windows(&vad, 0, 400 * WINDOW_SAMPLES, RATE_8K);
        assert_eq!(windows, vec![(25, 235), (225, 399)]);
    }

    #[test]
    fn search_windows_reject_short_runs() {
        let vad = vad_with_burst(400, 100, 49);
        assert!(search_windows(&vad, 0, 400 * WINDOW_SAMPLES, RATE_8K).is_empty());
    }

    #[test]
    fn coarse_maximizer_falls_back_to_zero_lag() {
        // Spec 01 section 1.9 step 4: the maximizer starts with value 0
        // at index Vr - 1, so with no positive correlation value the
        // fallback is k = Vr - 1, i.e. lag 0 (not +W).
        let negative = [-1.0f32, -2.0, -3.0];
        assert_eq!(lag_from_correlation(&negative, 4, WINDOW_SAMPLES), 0);
        let zeros = [0.0f32; 9];
        assert_eq!(lag_from_correlation(&zeros, 4, WINDOW_SAMPLES), 0);
    }
}