Oregami
Repositories/oxedyne/fe2o3

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
13use crate::wav::Wav;
14
15use oxedyne_fe2o3_core::prelude::*;
16
17use std::f64::consts::PI;
18
19
20const ABS_GATE: f64 = -70.0; // fixed: BS.1770-4 §2.8, LUFS
21const REL_GATE: f64 = -10.0; // fixed: BS.1770-4, LU under the ungated mean
22const LRA_GATE: f64 = -20.0; // fixed: EBU Tech 3342, LU
23const OFFSET: f64 = -0.691; // fixed: BS.1770-4, the K-weighting's gain at 1 kHz undone
24const 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)]
28pub 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.
36type Biquad = [f64; 5];
37
38fn 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
52fn 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.
60fn 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
90fn 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).
95fn 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.
106fn 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.
137pub fn true_peak(w: &Wav) -> f64 {
138 peaks(w).into_iter().fold(0.0, f64::max)
139}
140
141pub 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.
153pub 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.
179fn 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}