audio-bed-check 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ """Checks for rendered audio beds and voiceover mixes. See README.md."""
2
+
3
+ from .checks import (
4
+ LoopResult,
5
+ NoSpeechError,
6
+ SeparationResult,
7
+ StepsResult,
8
+ level_steps,
9
+ loop_score,
10
+ separation,
11
+ )
12
+ from .decode import DecodeError, decode
13
+ from .loudness import block_loudness, k_weight, momentary, true_peak
14
+
15
+ __version__ = "0.1.0"
16
+
17
+ __all__ = [
18
+ "DecodeError", "LoopResult", "NoSpeechError", "SeparationResult", "StepsResult",
19
+ "block_loudness", "decode", "k_weight", "level_steps", "loop_score", "momentary", "separation",
20
+ "true_peak",
21
+ "__version__",
22
+ ]
@@ -0,0 +1,5 @@
1
+ """`python -m audio_bed_check`: the same command as `audio-bed-check`."""
2
+
3
+ from .cli import main
4
+
5
+ raise SystemExit(main())
@@ -0,0 +1,408 @@
1
+ """The three checks. Pure functions of a sample array and a rate; nothing here touches files or ffmpeg."""
2
+
3
+ import math
4
+ from dataclasses import dataclass
5
+
6
+ import numpy as np
7
+
8
+ from .loudness import HOP, WINDOW, block_loudness, k_weight, true_peak
9
+
10
+ # seconds; under this the 400 ms momentary window correlates neighbouring frames by itself
11
+ LOOP_SHORTEST_LAG = 0.5
12
+ # a loop correlates at every multiple of its period; the fundamental is the shortest peak within
13
+ # this of the strongest, so a half-period peak cannot name the repeat
14
+ LOOP_PEAK_TOLERANCE = 0.05
15
+ LOOP_WINDOW = 100 # frames (10 s) of envelope changes correlated at a time
16
+ LOOP_MIN_WINDOW = 30 # frames; files under 30 s use a third of their length, never less than this
17
+ LOOP_STRIDE = 5 # frames between window starts
18
+
19
+
20
+ @dataclass(frozen=True)
21
+ class LoopResult:
22
+ """score: Pearson correlation of the envelope's frame-to-frame changes at period_s, over the
23
+ best-matching 10 s window; 1.0 is an exact repeat. When nothing reached the threshold, score is
24
+ the strongest local maximum at lags of min_period_s or more, never below 0.0, and period_s is None."""
25
+
26
+ score: float
27
+ period_s: float | None
28
+ threshold: float
29
+ min_period_s: float
30
+ passed: bool
31
+ notes: tuple[str, ...] = ()
32
+
33
+
34
+ def _weighted(samples: np.ndarray, sr: int, weighted: np.ndarray | None) -> np.ndarray:
35
+ """The caller's K-weighted signal, or k_weight(samples, sr) when there is none."""
36
+ if weighted is None:
37
+ return k_weight(samples, sr)
38
+ if np.shape(weighted) != np.shape(samples):
39
+ raise ValueError("weighted must be k_weight(samples, sr): same shape as samples")
40
+ return weighted
41
+
42
+
43
+ def _lag_scores(d: np.ndarray, window: int, first: int, last: int) -> np.ndarray:
44
+ """For each lag k in first..last, the best Pearson correlation of d[s:s+window] with
45
+ d[s+k:s+k+window] over window starts s every LOOP_STRIDE frames. Window sums come from cumulative
46
+ sums, so one lag is O(len(d)) in numpy. A window with no variation cannot win (scores -1)."""
47
+ m = len(d)
48
+ cum_d = np.concatenate([[0.0], np.cumsum(d)])
49
+ cum_d2 = np.concatenate([[0.0], np.cumsum(d * d)])
50
+ scores = np.full(last - first + 1, -1.0)
51
+ # a loop over lags, all numpy inside: measured 0.3 s for a 10-minute bed, 4 s for an hour
52
+ for i, k in enumerate(range(first, last + 1)):
53
+ s = np.arange(0, m - k - window + 1, LOOP_STRIDE)
54
+ cum_prod = np.concatenate([[0.0], np.cumsum(d[:m - k] * d[k:])])
55
+ sum_a, sum_b = cum_d[s + window] - cum_d[s], cum_d[s + k + window] - cum_d[s + k]
56
+ ss_a = cum_d2[s + window] - cum_d2[s] - sum_a * sum_a / window
57
+ ss_b = cum_d2[s + k + window] - cum_d2[s + k] - sum_b * sum_b / window
58
+ cross = cum_prod[s + window] - cum_prod[s] - sum_a * sum_b / window
59
+ ok = (ss_a > 1e-12) & (ss_b > 1e-12)
60
+ if ok.any():
61
+ scores[i] = float((cross[ok] / np.sqrt(ss_a[ok] * ss_b[ok])).max())
62
+ return scores
63
+
64
+
65
+ def loop_score(
66
+ samples: np.ndarray, sr: int, *, min_period: float = 6.0, threshold: float = 0.9,
67
+ weighted: np.ndarray | None = None,
68
+ ) -> LoopResult:
69
+ """Does the bed repeat itself?
70
+
71
+ Works on d, the frame-to-frame changes of the momentary loudness (dB, 100 ms hop). A copied clip
72
+ copies its fine texture, so d repeats exactly where the audio repeats, while a fade or a gain
73
+ change moves the level and barely touches d. For every lag from 0.5 s to the file length minus
74
+ one window, the score is the best Pearson correlation of a 10 s window of d with the window that
75
+ many frames later (window starts every 0.5 s; a third of the file, at least 3 s, under 30 s).
76
+ So a repeat is found even when only part of the file loops, but only when the repeating stretch is
77
+ at least one period plus the window long: a 6 s clip played twice is not seen. The longest repeat
78
+ that can be found is the file length minus the window (about 10.5 s less than the file). Lags
79
+ resolve in 0.1 s steps.
80
+
81
+ The fundamental is the shortest lag whose score is a local maximum at or above `threshold` and
82
+ within LOOP_PEAK_TOLERANCE of the strongest such peak. Under `min_period` it is music-like (a
83
+ bar) and becomes a note; at or above it, the file is a loop and fails. With no peak at the
84
+ threshold, the score is the strongest local maximum at lags of `min_period` or more (0.0 when
85
+ there is none, or it is negative) and the file passes.
86
+
87
+ `weighted` is the K-weighted signal (`k_weight(samples, sr)`) if the caller has it already, so a
88
+ file is filtered once for several checks.
89
+ """
90
+ if min_period <= 0:
91
+ raise ValueError("min_period must be positive")
92
+ if not 0 < threshold <= 1:
93
+ raise ValueError("threshold must be between 0 (exclusive) and 1")
94
+ too_short = LoopResult(0.0, None, threshold, min_period, True,
95
+ (f"too short to test for a repeat longer than {min_period:g}s",))
96
+ if len(samples) / sr < 2 * min_period + 1:
97
+ return too_short
98
+ env = block_loudness(_weighted(samples, sr, weighted), sr, WINDOW, HOP)
99
+ if np.ptp(env) < 0.01: # silence or a constant tone; a steady bed still varies by tenths of a dB
100
+ return LoopResult(0.0, None, threshold, min_period, True,
101
+ ("level is constant; nothing to correlate",))
102
+ d = np.diff(env)
103
+ window = min(LOOP_WINDOW, max(LOOP_MIN_WINDOW, len(env) // 3))
104
+ first, lo = int(round(LOOP_SHORTEST_LAG / HOP)), int(round(min_period / HOP))
105
+ last = len(d) - window
106
+ if last < max(lo, first + 2):
107
+ return too_short
108
+ scores = _lag_scores(d, window, first, last)
109
+ lags = np.arange(first, last + 1)
110
+ # local maxima; never the first lag, whose only neighbour is on one side, and the last lag only
111
+ # if it is at least its neighbour, since a repeat can sit right at the end of the range. A lag
112
+ # where no window had any variation scores -1; a run of those is flat, not a peak
113
+ is_peak = np.zeros(len(scores), dtype=bool)
114
+ is_peak[1:-1] = (scores[1:-1] >= scores[:-2]) & (scores[1:-1] >= scores[2:])
115
+ is_peak[-1] = scores[-1] >= scores[-2]
116
+ is_peak &= scores > -1.0
117
+ peaks = is_peak & (scores >= threshold)
118
+ if not peaks.any():
119
+ flaggable = is_peak & (lags >= lo)
120
+ score = float(scores[flaggable].max()) if flaggable.any() else 0.0
121
+ return LoopResult(min(max(score, 0.0), 1.0), None, threshold, min_period, True)
122
+ best = scores[peaks].max()
123
+ i = int(np.flatnonzero(peaks & (scores >= best - LOOP_PEAK_TOLERANCE))[0])
124
+ k = int(lags[i])
125
+ period = round(k * HOP, 2)
126
+ passed = k < lo
127
+ notes = ()
128
+ if passed:
129
+ notes = (f"repeats every {period:.1f}s, under --min-period {min_period:g}s, not flagged",)
130
+ return LoopResult(min(float(scores[i]), 1.0), period, threshold, min_period, passed, notes)
131
+
132
+
133
+ STEP_BLOCK = 0.5 # seconds; the scale a listener hears as "the sound changed" rather than as texture
134
+ STEP_HOP = 0.1 # seconds between blocks, so a join is never more than 0.05 s from a boundary
135
+ STEP_SIDE = 20 # frames (2 s) averaged on each side of a boundary for the sustained step
136
+ STEP_GAP = 5 # frames (0.5 s) skipped at the boundary, so no block on either side straddles the join
137
+ STEP_TRANSIENT = int(round(STEP_BLOCK / STEP_HOP)) # frames between the two blocks a transient compares
138
+ STEP_FLOOR_LKFS = -70.0 # blocks under this count as silence for the step: noise this low cannot lurch
139
+ SILENT_DBTP = -60.0 # a file peaking at or under this is reported as silent; the verdict is unchanged
140
+ SILENT_NOTE = "the file is silent (peak at or under -60 dBTP)"
141
+
142
+
143
+ @dataclass(frozen=True)
144
+ class StepsResult:
145
+ """step_db: largest change in mean level between the 2 s before a join and the 2 s after it, at
146
+ step_at_s (seconds into the file, rounded to 0.01 s); the only field that decides `passed`.
147
+ range_db (max minus min) and transient_db (largest change between half-second blocks 0.5 s apart)
148
+ are reported, never failed. step_at_s is None when the file is too short to measure or the level
149
+ never changes.
150
+ Values are full precision; the CLI rounds."""
151
+
152
+ step_db: float
153
+ step_at_s: float | None
154
+ range_db: float
155
+ transient_db: float
156
+ peak_dbtp: float
157
+ max_step: float
158
+ passed: bool
159
+ notes: tuple[str, ...] = ()
160
+
161
+
162
+ def level_steps(samples: np.ndarray, sr: int, *, max_step: float = 6.0, edge: float = 0.75,
163
+ weighted: np.ndarray | None = None) -> StepsResult:
164
+ """Does the level lurch?
165
+
166
+ Half-second K-weighted blocks every 0.1 s. At every boundary the sustained step is the mean of
167
+ the 2 s of blocks after a 0.5 s transition gap against the 2 s of blocks before it; the gap means
168
+ no block on either side straddles a join, so the reading does not depend on where the join falls
169
+ between blocks. A change held about 2 s or longer therefore fails even if it comes back.
170
+
171
+ Only the sustained step fails. A hard join shifts the level and it stays shifted; a crowd surge
172
+ spikes and comes back, and that is the recording's character, so range and transient are
173
+ reported, never failed. The first and last `edge` seconds are dropped (rounded up to whole 0.1 s
174
+ frames); a join less than about 2.5 s inside them reads smaller than it is, and inside them it is
175
+ not seen at all. Blocks under -70 LKFS count as -70 for the step, so a file of near silence
176
+ cannot fail on its own noise. A file peaking at or under -60 dBTP carries SILENT_NOTE as its last
177
+ note, which the CLI prints as a warning; it does not change `passed`.
178
+
179
+ `weighted` is the K-weighted signal (`k_weight(samples, sr)`) if the caller has it already.
180
+ """
181
+ if edge < 0:
182
+ raise ValueError("edge must be >= 0")
183
+ env = block_loudness(_weighted(samples, sr, weighted), sr, STEP_BLOCK, STEP_HOP)
184
+ skip = math.ceil(edge / STEP_HOP - 1e-9)
185
+ env = env[skip:len(env) - skip] if skip else env
186
+ peak = true_peak(samples, sr)
187
+ silent = (SILENT_NOTE,) if peak <= SILENT_DBTP else ()
188
+ if len(env) < 2 * STEP_SIDE + STEP_GAP:
189
+ frames = 2 * STEP_SIDE + STEP_GAP + 2 * skip
190
+ need = round(STEP_BLOCK + (frames - 1) * STEP_HOP, 2)
191
+ return StepsResult(0.0, None, 0.0, 0.0, peak, max_step, True,
192
+ (f"too short to measure level steps (needs at least {need:g}s)",) + silent)
193
+ range_db = float(env.max() - env.min())
194
+ transient = float(np.abs(env[STEP_TRANSIENT:] - env[:-STEP_TRANSIENT]).max())
195
+ floored = np.maximum(env, STEP_FLOOR_LKFS)
196
+ c = np.concatenate([[0.0], np.cumsum(floored)])
197
+ i = np.arange(STEP_SIDE, len(env) - STEP_GAP - STEP_SIDE + 1)
198
+ before = (c[i] - c[i - STEP_SIDE]) / STEP_SIDE
199
+ after = (c[i + STEP_GAP + STEP_SIDE] - c[i + STEP_GAP]) / STEP_SIDE
200
+ steps = np.abs(after - before)
201
+ if steps.max() < 1e-9: # every boundary ties, so no place is the worst
202
+ # the floor flattened a varying file; a file that really is flat (digital zeros) says so
203
+ floored_flat = env.max() <= STEP_FLOOR_LKFS and np.ptp(env) > 1e-9
204
+ note = ("every block is under -70 LKFS; nothing to measure" if floored_flat
205
+ else "no level change anywhere")
206
+ return StepsResult(0.0, None, range_db, transient, peak, max_step, True, (note,) + silent)
207
+ worst = int(np.argmax(steps))
208
+ step = float(steps[worst])
209
+ # the join sits between the end of the last block before the gap and the start of the first after
210
+ last_before_ends = (skip + i[worst] - 1) * STEP_HOP + STEP_BLOCK
211
+ first_after_starts = (skip + i[worst] + STEP_GAP) * STEP_HOP
212
+ at = round(float(last_before_ends + first_after_starts) / 2, 2)
213
+ return StepsResult(step, at, range_db, transient, peak, max_step, step <= max_step, silent)
214
+
215
+
216
+ SEP_GATE_HOP = 0.02 # seconds; RMS resolution for finding speech in the voiceover
217
+ SEP_MIN_RUN = 0.25 # seconds; shortest stretch above the gate that counts as speech
218
+ SEP_GUARD = 0.25 # seconds trimmed from each end of a gap, so tails of speech do not leak in
219
+ SEP_MIN_GAP = 0.4 # seconds; shortest usable bed-only window
220
+ SEP_BLOCK = 0.05 # seconds; fine enough that a block never straddles the edge of a 250 ms run
221
+ SEP_SILENT_LKFS = -70.0 # bed-only windows at or under this are silence: the mix holds no bed
222
+ SEP_ALIGN_TOLERANCE = 0.2 # seconds; an estimated start further than this from vo_offset is named
223
+ # a read with regular pauses matches the mix almost equally at several lags; the given offset stands
224
+ # when its match is within this fraction of the best. The fixture that needed it tied at 0.01%, so
225
+ # 2% is a generous margin
226
+ SEP_ALIGN_TIE = 0.02
227
+ # the estimate is trusted only when, at the lag found, the voiceover's level inside its speech runs
228
+ # and the mix's level at the same moments correlate at least this well (Pearson). A voice 10 dB under
229
+ # a textured bed read 0.32 or less, at wrong lags up to 14 s away; a voice level with the bed read
230
+ # 0.40 to 0.73 and one 10 dB over it 0.99
231
+ SEP_ALIGN_MIN_R = 0.5
232
+
233
+
234
+ class NoSpeechError(ValueError):
235
+ """The separation check could not run: no speech windows, no gaps between them, or (with an
236
+ offset) no window inside the mix. The CLI reports it as exit 2, not as a failing mix."""
237
+
238
+
239
+ @dataclass(frozen=True)
240
+ class SeparationResult:
241
+ """separation_lu: speech_lkfs minus bed_lkfs, where speech_lkfs is the mean over speech runs of
242
+ each run's 90th-percentile 50 ms K-weighted level in the mix and bed_lkfs the same over the
243
+ bed-only gaps; the only field that decides `passed`. runs/gaps count the windows found in the
244
+ voiceover, before any fall outside the mix. estimated_offset_s is where the voiceover's envelope
245
+ best matches the mix's (0.1 s resolution), None when either is under 0.4 s or the match is too
246
+ weak to trust (a voice buried under the bed). warnings (named so
247
+ because they are actionable, unlike the other checks' notes: a hot peak, windows dropped by the
248
+ offset, an offset that disagrees with the estimate) never fail. Values are full precision; the
249
+ CLI rounds."""
250
+
251
+ separation_lu: float
252
+ speech_lkfs: float
253
+ bed_lkfs: float
254
+ runs: int
255
+ gaps: int
256
+ peak_dbtp: float
257
+ min_lu: float
258
+ passed: bool
259
+ estimated_offset_s: float | None = None
260
+ warnings: tuple[str, ...] = ()
261
+
262
+
263
+ # speech_runs and gaps_between are module-public for the tests; they are not re-exported by the package.
264
+ def speech_runs(vo: np.ndarray, sr: int, gate_dbfs: float = -44.0) -> list[tuple[float, float]]:
265
+ """(start, end) seconds of every stretch of the voiceover above the gate for at least SEP_MIN_RUN.
266
+
267
+ Mono or stereo: the gate reads the RMS over every sample of every channel in a hop, the mean power
268
+ over channels (identical channels read as mono; a voice on one channel reads 3 dB lower), so a
269
+ voice on one channel or in anti-phase still counts. Run lengths are compared in whole hops.
270
+ """
271
+ x = np.asarray(vo, dtype=np.float64)
272
+ h = int(round(SEP_GATE_HOP * sr))
273
+ blocks = len(x) // h
274
+ if blocks == 0:
275
+ return []
276
+ rms = np.sqrt((x[:blocks * h] ** 2).reshape(blocks, -1).mean(axis=1))
277
+ with np.errstate(divide="ignore"):
278
+ loud = 20 * np.log10(rms) > gate_dbfs
279
+ shortest = math.ceil(SEP_MIN_RUN / SEP_GATE_HOP - 1e-9) # hops; 0.25 s is 12.5, so 13
280
+ runs, start = [], None
281
+ # a plain scan: a 10-minute voiceover is 30,000 hops, nothing next to the K-weighting
282
+ for i, on in enumerate(loud):
283
+ if on and start is None:
284
+ start = i
285
+ elif not on and start is not None:
286
+ if i - start >= shortest:
287
+ runs.append((round(start * SEP_GATE_HOP, 2), round(i * SEP_GATE_HOP, 2)))
288
+ start = None
289
+ if start is not None and blocks - start >= shortest:
290
+ runs.append((round(start * SEP_GATE_HOP, 2), round(blocks * SEP_GATE_HOP, 2)))
291
+ return runs
292
+
293
+
294
+ def gaps_between(runs: list[tuple[float, float]]) -> list[tuple[float, float]]:
295
+ """Bed-only windows: the space between consecutive runs, trimmed by SEP_GUARD, kept if SEP_MIN_GAP
296
+ or longer less one gate hop, so a 0.9 s pause is kept wherever it falls on the 20 ms grid."""
297
+ gaps = []
298
+ for (_, end), (start, _) in zip(runs, runs[1:], strict=False):
299
+ a, b = end + SEP_GUARD, start - SEP_GUARD
300
+ # one gate hop of slack: off the 20 ms grid a run's end rounds up a hop and the next start
301
+ # rounds down, so a 0.9 s pause measures 0.88 s
302
+ if b - a >= SEP_MIN_GAP - SEP_GATE_HOP - 1e-9:
303
+ gaps.append((round(a, 2), round(b, 2)))
304
+ return gaps
305
+
306
+
307
+ def _window_level(blocks: np.ndarray, t0: float, t1: float) -> float | None:
308
+ """90th percentile of the blocks fully inside [t0, t1),
309
+ or None when the window is not wholly in the mix."""
310
+ i0 = math.ceil(t0 / SEP_BLOCK - 1e-9)
311
+ i1 = math.floor(t1 / SEP_BLOCK + 1e-9)
312
+ if i0 < 0 or i1 > len(blocks) or i1 <= i0:
313
+ return None
314
+ return float(np.percentile(blocks[i0:i1], 90))
315
+
316
+
317
+ def _estimate_offset(vo: np.ndarray, mix_weighted: np.ndarray, sr: int, runs: list[tuple[float, float]],
318
+ vo_offset: float = 0.0) -> float | None:
319
+ """Where the voiceover seems to start in the mix, seconds, at 0.1 s resolution; None when either
320
+ file is shorter than one 400 ms window, or when the match is too weak to trust.
321
+
322
+ `mix_weighted` is the mix already K-weighted. Cross-correlates the momentary envelopes (LKFS,
323
+ floored at -70 and with their means removed). The voiceover's is kept only inside its speech runs
324
+ and zero elsewhere, so the match is the shape of the read: louder in the mix where the voice is,
325
+ and the read's own texture. Lags run over plus or minus the mix's length. A read with regular
326
+ pauses matches at several lags almost equally, so when the match at `vo_offset` is within
327
+ SEP_ALIGN_TIE (2%) of the best, `vo_offset` (to the nearest 0.1 s) is the estimate.
328
+
329
+ The estimate stands only when, at that lag, the voiceover's envelope inside its runs and the mix's
330
+ at the same moments correlate at SEP_ALIGN_MIN_R (0.5) or more. A voice buried under a textured
331
+ bed otherwise lands on whatever lag the bed's texture happens to match.
332
+ """
333
+ v_raw = np.maximum(block_loudness(k_weight(vo, sr), sr, WINDOW, HOP), SEP_SILENT_LKFS)
334
+ m_raw = np.maximum(block_loudness(mix_weighted, sr, WINDOW, HOP), SEP_SILENT_LKFS)
335
+ if len(v_raw) == 0 or len(m_raw) == 0:
336
+ return None
337
+ centres = np.arange(len(v_raw)) * HOP + WINDOW / 2
338
+ inside = np.zeros(len(v_raw), dtype=bool)
339
+ for a, b in runs:
340
+ inside |= (centres >= a) & (centres < b)
341
+ v = np.where(inside, v_raw - v_raw.mean(), 0.0)
342
+ m = m_raw - m_raw.mean()
343
+ corr = np.correlate(m, v, mode="full") # index k is lag k - (len(v) - 1): m[j + lag] against v[j]
344
+ lags = np.arange(len(corr)) - (len(v) - 1)
345
+ keep = np.abs(lags) <= len(m)
346
+ corr, lags = corr[keep], lags[keep]
347
+ best = int(np.argmax(corr))
348
+ given = int(round(vo_offset / HOP)) - int(lags[0])
349
+ if 0 <= given < len(corr) and corr[given] >= corr[best] - SEP_ALIGN_TIE * abs(corr[best]):
350
+ best = given
351
+ lag = int(lags[best])
352
+ j = np.flatnonzero(inside)
353
+ j = j[(j + lag >= 0) & (j + lag < len(m_raw))]
354
+ if len(j) < 3:
355
+ return None
356
+ a, b = v_raw[j], m_raw[j + lag]
357
+ if np.ptp(a) < 1e-9 or np.ptp(b) < 1e-9:
358
+ return None
359
+ if float(np.corrcoef(a, b)[0, 1]) < SEP_ALIGN_MIN_R:
360
+ return None
361
+ return round(lag * HOP, 2)
362
+
363
+
364
+ def separation(vo: np.ndarray, mix: np.ndarray, sr: int, *, min_lu: float = 10.0, gate_dbfs: float = -44.0,
365
+ vo_offset: float = 0.0) -> SeparationResult:
366
+ """Is the voice on top of the bed?
367
+
368
+ Speech windows come from the voiceover on its own; each is measured in the MIX (voice plus bed)
369
+ and compared with the bed-only gaps between them. The 90th percentile per window, so a breath
370
+ inside a run does not drag the speech figure down. The result is what a listener hears, which is
371
+ also what WCAG G56 describes, not the ratio of the two stems.
372
+
373
+ Bed-only windows at or under -70 LKFS mean the mix holds no bed (the voiceover given as the mix,
374
+ usually) and raise NoSpeechError. The voiceover's start in the mix is estimated from the two
375
+ envelopes; when the estimate is trusted and more than 0.2 s from `vo_offset` a warning names it.
376
+ """
377
+ runs = speech_runs(vo, sr, gate_dbfs)
378
+ if not runs:
379
+ raise NoSpeechError(f"no speech found in the voiceover above {gate_dbfs:g} dBFS")
380
+ gaps = gaps_between(runs)
381
+ if not gaps:
382
+ raise NoSpeechError(
383
+ f"the voiceover has no pause of {SEP_MIN_GAP + 2 * SEP_GUARD:g}s or more between speech runs "
384
+ f"({SEP_MIN_GAP:g}s after a {SEP_GUARD:g}s guard at each end); either --vo is the mix rather "
385
+ "than the voiceover alone, or its noise floor is above --gate")
386
+ weighted = k_weight(mix, sr) # once: the windows and the offset estimate both read it
387
+ blocks = block_loudness(weighted, sr, SEP_BLOCK, SEP_BLOCK)
388
+ speech = [v for v in (_window_level(blocks, a + vo_offset, b + vo_offset) for a, b in runs)
389
+ if v is not None]
390
+ bed = [v for v in (_window_level(blocks, a + vo_offset, b + vo_offset) for a, b in gaps) if v is not None]
391
+ if not speech or not bed:
392
+ raise NoSpeechError("the voiceover's speech windows fall outside the mix; check --vo-offset")
393
+ speech_lkfs, bed_lkfs = float(np.mean(speech)), float(np.mean(bed))
394
+ if bed_lkfs <= SEP_SILENT_LKFS:
395
+ raise NoSpeechError("the bed-only windows are silent in the mix; is MIX the rendered mix?")
396
+ sep = speech_lkfs - bed_lkfs
397
+ peak = true_peak(mix, sr)
398
+ estimate = _estimate_offset(vo, weighted, sr, runs, vo_offset)
399
+ warnings: tuple[str, ...] = ()
400
+ dropped = len(runs) + len(gaps) - len(speech) - len(bed)
401
+ if dropped:
402
+ warnings += (f"{dropped} window(s) fall outside the mix; check --vo-offset",)
403
+ if estimate is not None and abs(estimate - vo_offset) > SEP_ALIGN_TOLERANCE + 1e-9:
404
+ warnings += (f"the voiceover seems to start at {estimate:.1f}s in the mix; check --vo-offset",)
405
+ if peak > -1.0:
406
+ warnings += ("mix true peak above -1 dBTP",)
407
+ return SeparationResult(sep, speech_lkfs, bed_lkfs, len(runs), len(gaps), peak, min_lu, sep >= min_lu,
408
+ estimate, warnings)
audio_bed_check/cli.py ADDED
@@ -0,0 +1,208 @@
1
+ """Command line: subcommands loop, steps, bed, separation. Exit 0 pass, 1 fail, 2 usage/decode error."""
2
+
3
+ import argparse
4
+ import dataclasses
5
+ import json
6
+ import math
7
+ import sys
8
+ from importlib.metadata import version as _version
9
+
10
+ from .checks import SILENT_NOTE, level_steps, loop_score, separation
11
+ from .decode import DecodeError, decode
12
+ from .loudness import k_weight
13
+
14
+ PROFILES = {"music": 10.0, "ambience": 15.0, "wcag": 20.0}
15
+ OVERRIDE = "--min-separation" # what the profile column says when the flag replaced the profile
16
+
17
+
18
+ def _number(text: str) -> float:
19
+ value = float(text)
20
+ if not math.isfinite(value):
21
+ raise argparse.ArgumentTypeError(f"must be a finite number, got {text}")
22
+ return value
23
+
24
+
25
+ def _positive(text: str) -> float:
26
+ value = _number(text)
27
+ if value <= 0:
28
+ raise argparse.ArgumentTypeError(f"must be a positive number, got {text}")
29
+ return value
30
+
31
+
32
+ def _non_negative(text: str) -> float:
33
+ value = _number(text)
34
+ if value < 0:
35
+ raise argparse.ArgumentTypeError(f"must be zero or more, got {text}")
36
+ return value
37
+
38
+
39
+ def _score(text: str) -> float:
40
+ value = _number(text)
41
+ if not 0 < value <= 1:
42
+ raise argparse.ArgumentTypeError(f"must be between 0 (exclusive) and 1, got {text}")
43
+ return value
44
+
45
+
46
+ def build_parser() -> argparse.ArgumentParser:
47
+ p = argparse.ArgumentParser(
48
+ prog="audio-bed-check",
49
+ description="Check an audio bed for loops and level steps, or a mix for voice-over-bed separation. "
50
+ "Exit 0 when every check passes, 1 when any fails, 2 when a check could not run.",
51
+ )
52
+ p.add_argument("--version", action="version", version=f"%(prog)s {_version('audio-bed-check')}")
53
+ sub = p.add_subparsers(dest="command", required=True)
54
+
55
+ def common(sp):
56
+ sp.add_argument("--json", action="store_true", help="print a JSON list, one object per file")
57
+ sp.add_argument("--ffmpeg", metavar="PATH",
58
+ help="ffmpeg to use (default: $AUDIO_BED_CHECK_FFMPEG, then PATH)")
59
+
60
+ def loop_flags(sp):
61
+ sp.add_argument("--min-period", type=_positive, default=6.0, metavar="S",
62
+ help="shortest repeat length that counts as a loop, seconds "
63
+ "(default 6; shorter repeats are noted)")
64
+ sp.add_argument("--loop-threshold", type=_score, default=0.9, metavar="SCORE",
65
+ help="correlation at which a repeat fails, 0 to 1 (default 0.9)")
66
+
67
+ def steps_flags(sp):
68
+ sp.add_argument("--max-step", type=_positive, default=6.0, metavar="DB",
69
+ help="largest sustained level step allowed, dB (default 6)")
70
+ sp.add_argument("--edge", type=_non_negative, default=0.75, metavar="S",
71
+ help="seconds ignored at each end so fades are not read as steps (default 0.75)")
72
+
73
+ for name, flag_sets, text in (
74
+ ("loop", (loop_flags,), "does the bed repeat itself?"),
75
+ ("steps", (steps_flags,), "does the level lurch at a join?"),
76
+ ("bed", (loop_flags, steps_flags), "loop and steps together"),
77
+ ):
78
+ sp = sub.add_parser(name, help=text, description=text)
79
+ sp.add_argument("files", nargs="+", metavar="BED", help="audio or video file; anything ffmpeg reads")
80
+ for add in flag_sets:
81
+ add(sp)
82
+ common(sp)
83
+
84
+ sp = sub.add_parser("separation", help="is the voice far enough above the bed?",
85
+ description="Measures the rendered mix inside the voiceover's speech windows "
86
+ "against the gaps between them.")
87
+ sp.add_argument("mix", metavar="MIX", help="the rendered mix (audio or video)")
88
+ sp.add_argument("--vo", required=True, metavar="VO",
89
+ help="the voiceover on its own, as it was placed in the mix")
90
+ sp.add_argument("--profile", choices=PROFILES, default="music",
91
+ help="minimum separation: music 10 LU, ambience 15 LU, wcag 20 LU (default music)")
92
+ sp.add_argument("--min-separation", type=_positive, metavar="LU", help="override the profile's minimum")
93
+ sp.add_argument("--gate", type=_number, default=-44.0, metavar="DBFS",
94
+ help="level above which the voiceover counts as speech (default -44)")
95
+ sp.add_argument("--vo-offset", type=_number, default=0.0, metavar="S",
96
+ help="where the voiceover starts in the mix, seconds (default 0)")
97
+ common(sp)
98
+ return p
99
+
100
+
101
+ def _round(value: float) -> float:
102
+ """2 decimals, and anything within 0.005 of zero is 0.0, so nothing prints as -0.0 or -0.00."""
103
+ return 0.0 if abs(value) < 0.005 else round(value, 2)
104
+
105
+
106
+ def _result(r) -> dict:
107
+ """A result as a dict with floats rounded to 2 decimals; the dataclasses keep full precision."""
108
+ return {k: _round(v) if isinstance(v, float) else v for k, v in dataclasses.asdict(r).items()}
109
+
110
+
111
+ def _run(args) -> list[dict]:
112
+ results = []
113
+ if args.command == "separation":
114
+ vo, sr = decode(args.vo, args.ffmpeg)
115
+ mix, _ = decode(args.mix, args.ffmpeg)
116
+ overridden = args.min_separation is not None
117
+ min_lu = args.min_separation if overridden else PROFILES[args.profile]
118
+ r = separation(vo, mix, sr, min_lu=min_lu, gate_dbfs=args.gate, vo_offset=args.vo_offset)
119
+ results.append({"file": args.mix, "passed": r.passed,
120
+ "profile": OVERRIDE if overridden else args.profile, "separation": _result(r)})
121
+ return results
122
+ for path in args.files:
123
+ try:
124
+ samples, sr = decode(path, args.ffmpeg)
125
+ except DecodeError as e: # one unreadable file must not throw away the rest of the batch
126
+ results.append({"file": path, "passed": False, "error": str(e)})
127
+ continue
128
+ entry = {"file": path, "passed": True}
129
+ weighted = k_weight(samples, sr) # once per file, shared by both checks
130
+ if args.command in ("loop", "bed"):
131
+ r = loop_score(samples, sr, min_period=args.min_period, threshold=args.loop_threshold,
132
+ weighted=weighted)
133
+ entry["loop"] = _result(r)
134
+ entry["passed"] = entry["passed"] and r.passed
135
+ if args.command in ("steps", "bed"):
136
+ r = level_steps(samples, sr, max_step=args.max_step, edge=args.edge, weighted=weighted)
137
+ entry["steps"] = _result(r)
138
+ entry["passed"] = entry["passed"] and r.passed
139
+ results.append(entry)
140
+ return results
141
+
142
+
143
+ def _num(value: float, decimals: int) -> str:
144
+ """A printed number: fixed decimals, and never "-0.0" or "-0.00" for something that rounds to zero."""
145
+ text = f"{value:.{decimals}f}"
146
+ return f"{0.0:.{decimals}f}" if float(text) == 0 else text
147
+
148
+
149
+ def _verdict(passed: bool) -> str:
150
+ return "ok " if passed else "FAIL"
151
+
152
+
153
+ def _render(entry: dict) -> str:
154
+ lines = [entry["file"]]
155
+ if "error" in entry:
156
+ lines.append(f" error {entry['error']}")
157
+ if "loop" in entry:
158
+ r = entry["loop"]
159
+ if r["notes"]:
160
+ detail = r["notes"][0]
161
+ elif r["period_s"] is None:
162
+ detail = f"no repeat at or above {_num(r['threshold'], 2)}"
163
+ else:
164
+ detail = f"repeats every {_num(r['period_s'], 1)}s, at or above {_num(r['threshold'], 2)}"
165
+ lines.append(f" {_verdict(r['passed'])} loop {_num(r['score'], 2)} ({detail})")
166
+ if "steps" in entry:
167
+ r = entry["steps"]
168
+ notes = [n for n in r["notes"] if n != SILENT_NOTE]
169
+ if r["step_at_s"] is None:
170
+ detail = notes[0] if notes else "no level step measured"
171
+ lines.append(f" {_verdict(r['passed'])} step {detail}")
172
+ else:
173
+ lines.append(f" {_verdict(r['passed'])} step {_num(r['step_db'], 2)} dB at "
174
+ f"{_num(r['step_at_s'], 2)}s (max {_num(r['max_step'], 2)})")
175
+ lines.append(f" info range {_num(r['range_db'], 1)} dB "
176
+ f"transient {_num(r['transient_db'], 1)} dB peak {_num(r['peak_dbtp'], 1)} dBTP")
177
+ if SILENT_NOTE in r["notes"]:
178
+ lines.append(f" warn {SILENT_NOTE}")
179
+ if "separation" in entry:
180
+ r = entry["separation"]
181
+ lines.append(f" {_verdict(r['passed'])} separation {_num(r['separation_lu'], 2)} LU "
182
+ f"(speech {_num(r['speech_lkfs'], 2)}, bed {_num(r['bed_lkfs'], 2)} LKFS; "
183
+ f"min {_num(r['min_lu'], 2)}, {entry['profile']})")
184
+ lines.append(f" info peak {_num(r['peak_dbtp'], 1)} dBTP speech windows {r['runs']} "
185
+ f"bed windows {r['gaps']}")
186
+ for w in r["warnings"]:
187
+ lines.append(f" warn {w}")
188
+ return "\n".join(lines)
189
+
190
+
191
+ def main(argv=None) -> int:
192
+ args = build_parser().parse_args(argv)
193
+ try:
194
+ results = _run(args)
195
+ except (DecodeError, ValueError) as e: # NoSpeechError and the library's argument guards are ValueErrors
196
+ print(f"audio-bed-check: {e}", file=sys.stderr)
197
+ return 2
198
+ if args.json:
199
+ print(json.dumps(results, indent=2))
200
+ else:
201
+ print("\n\n".join(_render(r) for r in results))
202
+ if any("error" in r for r in results):
203
+ return 2
204
+ return 0 if all(r["passed"] for r in results) else 1
205
+
206
+
207
+ if __name__ == "__main__":
208
+ sys.exit(main())