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.
- audio_bed_check/__init__.py +22 -0
- audio_bed_check/__main__.py +5 -0
- audio_bed_check/checks.py +408 -0
- audio_bed_check/cli.py +208 -0
- audio_bed_check/decode.py +110 -0
- audio_bed_check/loudness.py +152 -0
- audio_bed_check/skills/audio-bed-check/SKILL.md +80 -0
- audio_bed_check/skills/audio-bed-check/references/checks.md +147 -0
- audio_bed_check/skills/audio-bed-check/references/cli.md +160 -0
- audio_bed_check-0.1.0.dist-info/METADATA +181 -0
- audio_bed_check-0.1.0.dist-info/RECORD +14 -0
- audio_bed_check-0.1.0.dist-info/WHEEL +4 -0
- audio_bed_check-0.1.0.dist-info/entry_points.txt +2 -0
- audio_bed_check-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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,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())
|