oxedyne/fe2o3/fe2o3_graphics/src/loudness.rs
7.6 KiB, 51 runs
created by r352662578:79644, which is this file's identity for as long as the history lasts, whatever it is later renamed to
download · who wrote it · its history
| 1 | //! Loudness as ITU-R BS.1770-4 and EBU R128 measure it, and a sound levelled to a target. |
| 2 | //! |
| 3 | //! [`measure`] gives the integrated loudness (K-weighted, 400 ms blocks a tenth of a second apart, gated at -70 LUFS and |
| 4 | //! then 10 LU under the mean), the loudness range of EBU Tech 3342 (3 s blocks, gated at -70 LUFS and 20 LU under, the |
| 5 | //! spread from the 10th to the 95th percentile) and the true peak, read at four times the rate by a windowed sinc. The |
| 6 | //! K-weighting's two filters are worked out for the sound's own rate from their analogue prototypes, as libebur128 does, |
| 7 | //! so 44.1 kHz is measured as truly as 48 kHz. In 5.1 sound the fourth channel (LFE) is left out and the surrounds weigh |
| 8 | //! 1.41; any other layout weighs every channel 1. |
| 9 | //! |
| 10 | //! [`level`] brings a sound to a target loudness by one gain, and where that gain would put the true peak over its |
| 11 | //! ceiling a look-ahead limiter holds the peaks under it, the gain raised again until the loudness meets the target. |
| 12 | |
| 13 | use crate::wav::Wav; |
| 14 | |
| 15 | use oxedyne_fe2o3_core::prelude::*; |
| 16 | |
| 17 | use std::f64::consts::PI; |
| 18 | |
| 19 | |
| 20 | const ABS_GATE: f64 = -70.0; // fixed: BS.1770-4 §2.8, LUFS |
| 21 | const REL_GATE: f64 = -10.0; // fixed: BS.1770-4, LU under the ungated mean |
| 22 | const LRA_GATE: f64 = -20.0; // fixed: EBU Tech 3342, LU |
| 23 | const OFFSET: f64 = -0.691; // fixed: BS.1770-4, the K-weighting's gain at 1 kHz undone |
| 24 | const TAPS: i64 = 8; // sinc taps either side of the point the true peak is read at |
| 25 | |
| 26 | /// What [`measure`] finds; a sound wholly under the absolute gate reads -inf. |
| 27 | #[derive(Clone, Copy, Debug, PartialEq)] |
| 28 | pub struct Loudness { |
| 29 | pub i: f64, // integrated loudness, LUFS |
| 30 | pub lra: f64, // loudness range, LU |
| 31 | pub tp: f64, // true peak, dBTP |
| 32 | pub thresh: f64, // the relative gate the integrated loudness was read at, LUFS |
| 33 | } |
| 34 | |
| 35 | // A biquad, b0 b1 b2 a1 a2, its state kept by the caller. |
| 36 | type Biquad = [f64; 5]; |
| 37 | |
| 38 | fn k_weighting(rate: f64) -> (Biquad, Biquad) { |
| 39 | // fixed: BS.1770-4's analogue prototypes (libebur128): the shelf's centre, gain and Q, then the high-pass's. |
| 40 | let (f0, g, q) = (1681.974450955533, 3.999843853973347, 0.7071752369554196); |
| 41 | let k = (PI * f0 / rate).tan(); |
| 42 | let (vh, vb) = (10f64.powf(g / 20.0), 10f64.powf(g / 20.0).powf(0.4996667741545416)); |
| 43 | let a0 = 1.0 + k / q + k * k; |
| 44 | let shelf = [(vh + vb * k / q + k * k) / a0, 2.0 * (k * k - vh) / a0, (vh - vb * k / q + k * k) / a0, |
| 45 | 2.0 * (k * k - 1.0) / a0, (1.0 - k / q + k * k) / a0]; |
| 46 | let (f0, q) = (38.13547087602444, 0.5003270373238773); |
| 47 | let k = (PI * f0 / rate).tan(); |
| 48 | let a0 = 1.0 + k / q + k * k; |
| 49 | (shelf, [1.0, -2.0, 1.0, 2.0 * (k * k - 1.0) / a0, (1.0 - k / q + k * k) / a0]) |
| 50 | } |
| 51 | |
| 52 | fn weights(n: usize) -> Vec<f64> { |
| 53 | match n { |
| 54 | 6 => vec![1.0, 1.0, 1.0, 0.0, 1.41, 1.41], // fixed: BS.1770-4 table 3, L R C LFE Ls Rs |
| 55 | _ => vec![1.0; n], |
| 56 | } |
| 57 | } |
| 58 | |
| 59 | // The weighted mean square of each `win`-sample block, a block every `hop` samples. |
| 60 | fn blocks(w: &Wav, win: usize, hop: usize) -> Vec<f64> { |
| 61 | let (n, ws) = (w.frames(), weights(w.chans.len())); |
| 62 | let (s1, s2) = k_weighting(w.rate as f64); |
| 63 | let mut sq = vec![0f64; n]; // each frame's weighted, K-filtered power, summed over channels |
| 64 | for (c, ch) in w.chans.iter().enumerate() { |
| 65 | if ws[c] == 0.0 { |
| 66 | continue; |
| 67 | } |
| 68 | let (mut x1, mut x2, mut y1, mut y2, mut z1, mut z2) = (0f64, 0f64, 0f64, 0f64, 0f64, 0f64); |
| 69 | for (i, x) in ch.iter().enumerate() { |
| 70 | let x = *x as f64; |
| 71 | let y = s1[0] * x + s1[1] * x1 + s1[2] * x2 - s1[3] * y1 - s1[4] * y2; |
| 72 | let z = s2[0] * y + s2[1] * y1 + s2[2] * y2 - s2[3] * z1 - s2[4] * z2; |
| 73 | (x2, x1, y2, y1, z2, z1) = (x1, x, y1, y, z1, z); |
| 74 | sq[i] += ws[c] * z * z; |
| 75 | } |
| 76 | } |
| 77 | let mut sum = vec![0f64; n + 1]; |
| 78 | for i in 0..n { |
| 79 | sum[i + 1] = sum[i] + sq[i]; |
| 80 | } |
| 81 | let mut out = Vec::new(); |
| 82 | let mut at = 0; |
| 83 | while at + win <= n { |
| 84 | out.push((sum[at + win] - sum[at]) / win as f64); |
| 85 | at += hop; |
| 86 | } |
| 87 | out |
| 88 | } |
| 89 | |
| 90 | fn lufs(z: f64) -> f64 { |
| 91 | OFFSET + 10.0 * z.log10() |
| 92 | } |
| 93 | |
| 94 | // The mean power of the blocks over the absolute gate and then over `rel` LU under their mean: (it, the relative gate). |
| 95 | fn gated(zs: &[f64], rel: f64) -> (Vec<f64>, f64) { |
| 96 | let over: Vec<f64> = zs.iter().copied().filter(|z| lufs(*z) > ABS_GATE).collect(); |
| 97 | if over.is_empty() { |
| 98 | return (over, f64::NEG_INFINITY); |
| 99 | } |
| 100 | let t = lufs(over.iter().sum::<f64>() / over.len() as f64) + rel; |
| 101 | (over.into_iter().filter(|z| lufs(*z) > t).collect(), t) |
| 102 | } |
| 103 | |
| 104 | // Each frame's magnitude read at four times the rate: its own sample and the three points after it, by a Hann-windowed |
| 105 | // sinc of TAPS either side, the most of every channel. |
| 106 | fn peaks(w: &Wav) -> Vec<f64> { |
| 107 | let phase: Vec<Vec<f64>> = (1..4).map(|p| { |
| 108 | let d = p as f64 / 4.0; |
| 109 | (-TAPS + 1..=TAPS).map(|k| { |
| 110 | let t = k as f64 - d; |
| 111 | let s = if t == 0.0 { 1.0 } else { (PI * t).sin() / (PI * t) }; |
| 112 | s * (0.5 + 0.5 * (PI * t / (TAPS as f64 + 1.0)).cos()) |
| 113 | }).collect() |
| 114 | }).collect(); |
| 115 | let mut peak = vec![0f64; w.frames()]; |
| 116 | for ch in &w.chans { |
| 117 | let n = ch.len() as i64; |
| 118 | for i in 0..n { |
| 119 | let mut m = (ch[i as usize] as f64).abs(); |
| 120 | for h in &phase { |
| 121 | let mut y = 0.0; |
| 122 | for (j, c) in h.iter().enumerate() { |
| 123 | let k = i + j as i64 - TAPS + 1; |
| 124 | if (0..n).contains(&k) { |
| 125 | y += c * ch[k as usize] as f64; |
| 126 | } |
| 127 | } |
| 128 | m = m.max(y.abs()); |
| 129 | } |
| 130 | peak[i as usize] = peak[i as usize].max(m); |
| 131 | } |
| 132 | } |
| 133 | peak |
| 134 | } |
| 135 | |
| 136 | /// The highest sample of the sound read at four times its rate, as a linear magnitude. |
| 137 | pub fn true_peak(w: &Wav) -> f64 { |
| 138 | peaks(w).into_iter().fold(0.0, f64::max) |
| 139 | } |
| 140 | |
| 141 | pub fn measure(w: &Wav) -> Loudness { |
| 142 | let r = w.rate as usize; |
| 143 | let (kept, thresh) = gated(&blocks(w, r * 2 / 5, r / 10), REL_GATE); |
| 144 | let i = if kept.is_empty() { f64::NEG_INFINITY } else { lufs(kept.iter().sum::<f64>() / kept.len() as f64) }; |
| 145 | let (mut st, _) = gated(&blocks(w, r * 3, r / 10), LRA_GATE); |
| 146 | st.sort_by(|a, b| a.total_cmp(b)); |
| 147 | let pc = |p: f64| lufs(st[((st.len() - 1) as f64 * p).round() as usize]); |
| 148 | let lra = if st.is_empty() { 0.0 } else { pc(0.95) - pc(0.10) }; |
| 149 | Loudness { i, lra, tp: 20.0 * true_peak(w).log10(), thresh } |
| 150 | } |
| 151 | |
| 152 | /// `w` brought to `target` LUFS with its true peak at most `ceiling` dBTP, measured after. |
| 153 | pub fn level(w: &Wav, target: f64, ceiling: f64) -> Outcome<(Wav, Loudness)> { |
| 154 | let m = measure(w); |
| 155 | if !m.i.is_finite() { |
| 156 | return Err(err!("The sound is silent, under BS.1770's -70 LUFS gate throughout, so it has no loudness to level."; Invalid, Input)); |
| 157 | } |
| 158 | let (top, la) = (10f64.powf(ceiling / 20.0), (w.rate as usize / 200).max(1)); // fixed: a 5 ms look-ahead |
| 159 | let mut gain = target - m.i; |
| 160 | let mut out = w.clone(); |
| 161 | for _ in 0..6 { |
| 162 | let g = 10f64.powf(gain / 20.0); |
| 163 | out.chans = w.chans.iter().map(|c| c.iter().map(|x| (*x as f64 * g) as f32).collect()).collect(); |
| 164 | if m.tp + gain > ceiling { |
| 165 | limit(&mut out, top, la); |
| 166 | } |
| 167 | let o = measure(&out); |
| 168 | if (o.i - target).abs() < 0.05 || m.tp + gain <= ceiling { |
| 169 | return Ok((out, o)); |
| 170 | } |
| 171 | gain += target - o.i; |
| 172 | } |
| 173 | let o = measure(&out); |
| 174 | Ok((out, o)) |
| 175 | } |
| 176 | |
| 177 | // A look-ahead limiter: each frame's gain the least that keeps its true peak (between samples too) under `top`, held |
| 178 | // over 2 la frames each side and then averaged over la, so that a peak is met by a ramp and never by a step. |
| 179 | fn limit(w: &mut Wav, top: f64, la: usize) { |
| 180 | let n = w.frames(); |
| 181 | // fixed: 0.98 of the ceiling, a margin for the gain's own ramp reshaping the peak. |
| 182 | let mut need: Vec<f64> = peaks(w).into_iter().map(|p| if p > top * 0.98 { top * 0.98 / p } else { 1.0 }).collect(); |
| 183 | let held: Vec<f64> = (0..n).map(|i| need[i.saturating_sub(2 * la)..(i + 2 * la + 1).min(n)].iter().copied().fold(1.0, f64::min)).collect(); |
| 184 | let mut sum = 0.0; |
| 185 | for i in 0..n { |
| 186 | sum += held[i]; |
| 187 | if i >= la { |
| 188 | sum -= held[i - la]; |
| 189 | } |
| 190 | need[i] = sum / (i.min(la - 1) + 1) as f64; |
| 191 | } |
| 192 | let shift = la / 2; |
| 193 | for c in w.chans.iter_mut() { |
| 194 | for i in 0..n { |
| 195 | c[i] = (c[i] as f64 * need[(i + shift).min(n - 1)]) as f32; |
| 196 | } |
| 197 | } |
| 198 | } |