audio-bed-check 0.1.0__tar.gz
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-0.1.0/.claude-plugin/marketplace.json +12 -0
- audio_bed_check-0.1.0/.claude-plugin/plugin.json +8 -0
- audio_bed_check-0.1.0/.gitignore +8 -0
- audio_bed_check-0.1.0/LICENSE +21 -0
- audio_bed_check-0.1.0/PKG-INFO +181 -0
- audio_bed_check-0.1.0/README.md +154 -0
- audio_bed_check-0.1.0/SECURITY.md +9 -0
- audio_bed_check-0.1.0/pyproject.toml +57 -0
- audio_bed_check-0.1.0/scripts/loop_sweep.py +93 -0
- audio_bed_check-0.1.0/skills/audio-bed-check/SKILL.md +80 -0
- audio_bed_check-0.1.0/skills/audio-bed-check/references/checks.md +147 -0
- audio_bed_check-0.1.0/skills/audio-bed-check/references/cli.md +160 -0
- audio_bed_check-0.1.0/src/audio_bed_check/__init__.py +22 -0
- audio_bed_check-0.1.0/src/audio_bed_check/__main__.py +5 -0
- audio_bed_check-0.1.0/src/audio_bed_check/checks.py +408 -0
- audio_bed_check-0.1.0/src/audio_bed_check/cli.py +208 -0
- audio_bed_check-0.1.0/src/audio_bed_check/decode.py +110 -0
- audio_bed_check-0.1.0/src/audio_bed_check/loudness.py +152 -0
- audio_bed_check-0.1.0/tests/__init__.py +0 -0
- audio_bed_check-0.1.0/tests/synth.py +166 -0
- audio_bed_check-0.1.0/tests/test_cli.py +271 -0
- audio_bed_check-0.1.0/tests/test_decode.py +210 -0
- audio_bed_check-0.1.0/tests/test_docs.py +100 -0
- audio_bed_check-0.1.0/tests/test_ffmpeg_oracle.py +133 -0
- audio_bed_check-0.1.0/tests/test_loop.py +262 -0
- audio_bed_check-0.1.0/tests/test_loudness.py +144 -0
- audio_bed_check-0.1.0/tests/test_separation.py +232 -0
- audio_bed_check-0.1.0/tests/test_steps.py +145 -0
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "audio-bed-check",
|
|
3
|
+
"description": "Check an audio bed for loops and level steps, and a voiceover mix for speech-over-bed separation.",
|
|
4
|
+
"owner": { "name": "oo-pibe" },
|
|
5
|
+
"plugins": [
|
|
6
|
+
{
|
|
7
|
+
"name": "audio-bed-check",
|
|
8
|
+
"source": "./",
|
|
9
|
+
"description": "Check an audio bed for loops and level steps, and a voiceover mix for speech-over-bed separation."
|
|
10
|
+
}
|
|
11
|
+
]
|
|
12
|
+
}
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 oo-pibe
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: audio-bed-check
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Check an audio bed for loops and level steps, and a voiceover mix for speech-over-bed separation.
|
|
5
|
+
Project-URL: Homepage, https://github.com/oo-pibe/audio-bed-check
|
|
6
|
+
Project-URL: Issues, https://github.com/oo-pibe/audio-bed-check/issues
|
|
7
|
+
Project-URL: Security, https://github.com/oo-pibe/audio-bed-check/blob/main/SECURITY.md
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: audio,bs1770,ducking,ebu-r128,ffmpeg,loop-detection,loudness,qa,video,voiceover
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Environment :: Console
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: Programming Language :: Python :: 3
|
|
15
|
+
Classifier: Programming Language :: Python :: 3 :: Only
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
|
|
19
|
+
Classifier: Topic :: Multimedia :: Video
|
|
20
|
+
Requires-Python: >=3.10
|
|
21
|
+
Requires-Dist: numpy>=1.26
|
|
22
|
+
Provides-Extra: dev
|
|
23
|
+
Requires-Dist: build>=1.2; extra == 'dev'
|
|
24
|
+
Requires-Dist: pytest>=8; extra == 'dev'
|
|
25
|
+
Requires-Dist: ruff>=0.6; extra == 'dev'
|
|
26
|
+
Description-Content-Type: text/markdown
|
|
27
|
+
|
|
28
|
+
# audio-bed-check
|
|
29
|
+
|
|
30
|
+
Finds three faults in a rendered audio bed that a tired ear misses: a loop, a level jump at a join,
|
|
31
|
+
and a voiceover sitting too close to the bed.
|
|
32
|
+
|
|
33
|
+
A bed is the ambience or music that sits under a voiceover or a cut. Three things go wrong with a
|
|
34
|
+
rendered one that a loudness meter does not catch: the file repeats itself, the level jumps
|
|
35
|
+
where two pieces were joined, or the voice over it is not far enough above it to be heard without
|
|
36
|
+
effort. This command measures each one and exits non-zero when one fails.
|
|
37
|
+
|
|
38
|
+
It needs Python 3.10 or later and ffmpeg, either on PATH or named with `--ffmpeg` or
|
|
39
|
+
`AUDIO_BED_CHECK_FFMPEG`. It reads anything ffmpeg reads, video included. Files keep their
|
|
40
|
+
channels: mono stays mono, stereo is measured per channel and summed the way BS.1770 does, more
|
|
41
|
+
than two channels are downmixed to two by ffmpeg; only the first audio track is read.
|
|
42
|
+
|
|
43
|
+
```
|
|
44
|
+
pip install audio-bed-check
|
|
45
|
+
|
|
46
|
+
audio-bed-check bed ambience.wav # loop and level steps
|
|
47
|
+
audio-bed-check separation final.mp4 --vo read.wav
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
ambience.wav
|
|
52
|
+
FAIL loop 1.00 (repeats every 12.0s, at or above 0.90)
|
|
53
|
+
ok step 0.59 dB at 38.15s (max 6.00)
|
|
54
|
+
info range 3.0 dB transient 2.7 dB peak -5.1 dBTP
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Exit 0 when every check passes, 1 when any fails, 2 when it could not run (a bad flag, an unreadable
|
|
58
|
+
file, no speech found in the voiceover). A `warn` line, such as a file peaking at or under -60 dBTP or a
|
|
59
|
+
voiceover that seems to start somewhere other than `--vo-offset`, never changes the exit code.
|
|
60
|
+
`--json` prints the numbers as a list of objects; the field list is in the command reference.
|
|
61
|
+
`python -m audio_bed_check` is the same command.
|
|
62
|
+
|
|
63
|
+
Check the bed before it is encoded. ffmpeg's built-in AAC at 128k rebuilt exact loops of steady
|
|
64
|
+
noise to scores between 0.88 and 0.97, some under the threshold; textured loops stayed at 1.00 after
|
|
65
|
+
AAC and MP3.
|
|
66
|
+
|
|
67
|
+
A 10-minute mono file takes about 2 s for `bed` and about 1.3 GB of memory; an hour takes about
|
|
68
|
+
40 s and 4 GB.
|
|
69
|
+
|
|
70
|
+
## The checks
|
|
71
|
+
|
|
72
|
+
`loop`: the frame-to-frame changes of the loudness envelope, correlated with themselves at every
|
|
73
|
+
lag over the best-matching 10 s window. A copied clip copies its texture, so a loop scores near 1.0
|
|
74
|
+
even when only part of the file repeats, or it fades out, or each repeat sits at a different gain.
|
|
75
|
+
Among the peaks that reach the threshold (`--loop-threshold`, 0.9), it reports the shortest one
|
|
76
|
+
scoring within 0.05 of the strongest. That is the repeat length rather than a multiple of it. A
|
|
77
|
+
repeat of 6 seconds or longer (`--min-period`) fails. A shorter one is reported and passes, because
|
|
78
|
+
music repeats at bar length. The loop check needs 13 s at the defaults; a shorter file reports ok
|
|
79
|
+
with a note.
|
|
80
|
+
|
|
81
|
+
`steps`: half-second loudness blocks every 0.1 s. The sustained step is the mean level over two
|
|
82
|
+
seconds after a half-second gap against the two seconds before; it fails above 6 dB (`--max-step`).
|
|
83
|
+
A bad join moves the level and it stays moved. A crowd surge spikes and comes back, so the largest
|
|
84
|
+
half-second transient and the range are printed but never fail the file. A change held about two
|
|
85
|
+
seconds or longer does fail, even if it comes back: a +7 dB plateau reads 3.9 dB held one second
|
|
86
|
+
and 6.7 held two. The steps check needs 6.5 s at the default edge; a shorter file reports ok with a
|
|
87
|
+
note.
|
|
88
|
+
|
|
89
|
+
`separation`: speech windows are found in the voiceover file, then compared with the bed-only gaps
|
|
90
|
+
between them. Each window's level is its 90th percentile of 50 ms K-weighted blocks. Both kinds of
|
|
91
|
+
window are measured in the mix, so the figure is voice plus bed against bed, which is closer to what
|
|
92
|
+
a listener hears than the gain on each stem. Profiles set the minimum: `music` 10 LU (the default),
|
|
93
|
+
`ambience` 15 LU, `wcag` 20 LU. The read needs pauses of 0.9 seconds or more. The voiceover's start
|
|
94
|
+
in the mix is estimated from the two envelopes, and a warning names it when it is more than 0.2 s
|
|
95
|
+
from `--vo-offset` (no estimate, and no warning, when the voice is too far under the bed to match); a mix whose bed-only windows are silent (the voiceover passed as the mix) is
|
|
96
|
+
refused.
|
|
97
|
+
|
|
98
|
+
The check compares speech windows with the bed in the gaps between them, so a bed that is ducked
|
|
99
|
+
under speech barely changes the figure. Torcoli et al. measured speech against the ducked
|
|
100
|
+
background, so treat the floors as approximate for ducked mixes.
|
|
101
|
+
|
|
102
|
+
| Check | Fails when | Default | Source |
|
|
103
|
+
|---|---|---|---|
|
|
104
|
+
| loop | repeat score at or above | 0.9, repeats of 6 s or longer | validation below |
|
|
105
|
+
| steps | sustained step above | 6 dB | chosen in one production pipeline where a 7 dB join was audible; no published source |
|
|
106
|
+
| separation, music | voice less than | 10 LU above bed | Torcoli et al., JAES 2019 |
|
|
107
|
+
| separation, ambience | voice less than | 15 LU above bed | Torcoli et al., JAES 2019 |
|
|
108
|
+
| separation, wcag | voice less than | 20 LU above bed | WCAG 2 technique G56 (stated there in dB(A) SPL) |
|
|
109
|
+
|
|
110
|
+
Every default can be changed with a flag; the full list is in
|
|
111
|
+
[skills/audio-bed-check/references/cli.md](https://github.com/oo-pibe/audio-bed-check/blob/main/skills/audio-bed-check/references/cli.md).
|
|
112
|
+
|
|
113
|
+
## Where the numbers come from
|
|
114
|
+
|
|
115
|
+
The loop check is validated on generated signals. The figures here are from one run of
|
|
116
|
+
[scripts/loop_sweep.py](https://github.com/oo-pibe/audio-bed-check/blob/main/scripts/loop_sweep.py),
|
|
117
|
+
which prints them. In that run, 400 unlooped beds of 30 to 600 seconds produced no failures
|
|
118
|
+
and the worst scored 0.75. Other seeds reach about 0.78, and longer files score higher by chance.
|
|
119
|
+
Loops under fades, in part of a file, with crossfaded joins or at changing gain all failed with the
|
|
120
|
+
right period, the lowest at 0.96. On one other seed a 10 s loop at gains up to 6 dB apart was named
|
|
121
|
+
at 20 s; it still failed. Beds with a 6 dB swell every 8 or 20 seconds passed, the highest at 0.85.
|
|
122
|
+
|
|
123
|
+
A repeat is seen only when the repeating stretch is at least one period plus the 10 s window long,
|
|
124
|
+
so a 6 to 8 second clip played twice usually is not. The longest repeat it can see is the file
|
|
125
|
+
length minus the window: about 10.5 s less than the file, or a third less under 30 s. A gain cycle
|
|
126
|
+
with nothing under it, such as a steady tremolo or the same swell twice on room tone, reads as a
|
|
127
|
+
loop; the details are in
|
|
128
|
+
[references/checks.md](https://github.com/oo-pibe/audio-bed-check/blob/main/skills/audio-bed-check/references/checks.md).
|
|
129
|
+
|
|
130
|
+
The loudness code is ITU-R BS.1770-4 K-weighting written in numpy. The test suite compares its
|
|
131
|
+
momentary loudness with ffmpeg's `ebur128` filter on the same file (median difference under 0.1 LU,
|
|
132
|
+
95th percentile under 0.2 LU), and its true peak on a test tone (within 0.2 dB). These tests skip
|
|
133
|
+
when no ffmpeg is found, or when the one found was built without `ebur128`.
|
|
134
|
+
|
|
135
|
+
## From Python
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
from audio_bed_check import decode, loop_score, level_steps, separation
|
|
139
|
+
|
|
140
|
+
samples, sr = decode("ambience.wav")
|
|
141
|
+
loop_score(samples, sr).passed # False if it repeats
|
|
142
|
+
level_steps(samples, sr).step_db # the worst sustained step, dB
|
|
143
|
+
|
|
144
|
+
vo, _ = decode("read.wav")
|
|
145
|
+
mix, _ = decode("final.mp4")
|
|
146
|
+
separation(vo, mix, sr, min_lu=15).separation_lu
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
The check functions are pure functions of a float array at 48 kHz; `decode` always returns that.
|
|
150
|
+
|
|
151
|
+
## For coding agents
|
|
152
|
+
|
|
153
|
+
The package ships an [Agent Skill](https://github.com/oo-pibe/audio-bed-check/tree/main/skills/audio-bed-check)
|
|
154
|
+
describing when to run which check and how to read the result. Claude Code users can install it as a
|
|
155
|
+
plugin:
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
/plugin marketplace add oo-pibe/audio-bed-check
|
|
159
|
+
/plugin install audio-bed-check@audio-bed-check
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Prior art
|
|
163
|
+
|
|
164
|
+
- ITU-R BS.1770-4, the loudness algorithm.
|
|
165
|
+
- Rafii and Pardo, REPET, IEEE TASLP 21(1), 2013: the repeating-period idea behind the loop check.
|
|
166
|
+
- Torcoli, Freke-Morin, Paulus, Simon and Shirley, "Preferred Levels for Background Ducking to
|
|
167
|
+
Produce Esthetically Pleasing Audio for TV with Clear Speech", JAES 67(12), 2019,
|
|
168
|
+
doi:10.17743/jaes.2019.0052: the source of the 10 LU (music) and 15 LU (ambience) floors. The
|
|
169
|
+
same study found non-expert listeners wanted about 4 LU more than experts.
|
|
170
|
+
- WCAG 2 technique G56, the 20 dB speech-over-background rule, stated there in dB(A) SPL.
|
|
171
|
+
- ffmpeg's `ebur128` filter, the reference the loudness tests compare against.
|
|
172
|
+
|
|
173
|
+
## Origin
|
|
174
|
+
|
|
175
|
+
Extracted from the video pipeline at [Road to Kickoff](https://roadtokickoff.com). A bed there
|
|
176
|
+
stepped 7 dB at two joins, got past every automated check, and was caught by ear. The 6 dB step
|
|
177
|
+
limit comes from that bed.
|
|
178
|
+
|
|
179
|
+
## License
|
|
180
|
+
|
|
181
|
+
MIT.
|
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
# audio-bed-check
|
|
2
|
+
|
|
3
|
+
Finds three faults in a rendered audio bed that a tired ear misses: a loop, a level jump at a join,
|
|
4
|
+
and a voiceover sitting too close to the bed.
|
|
5
|
+
|
|
6
|
+
A bed is the ambience or music that sits under a voiceover or a cut. Three things go wrong with a
|
|
7
|
+
rendered one that a loudness meter does not catch: the file repeats itself, the level jumps
|
|
8
|
+
where two pieces were joined, or the voice over it is not far enough above it to be heard without
|
|
9
|
+
effort. This command measures each one and exits non-zero when one fails.
|
|
10
|
+
|
|
11
|
+
It needs Python 3.10 or later and ffmpeg, either on PATH or named with `--ffmpeg` or
|
|
12
|
+
`AUDIO_BED_CHECK_FFMPEG`. It reads anything ffmpeg reads, video included. Files keep their
|
|
13
|
+
channels: mono stays mono, stereo is measured per channel and summed the way BS.1770 does, more
|
|
14
|
+
than two channels are downmixed to two by ffmpeg; only the first audio track is read.
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
pip install audio-bed-check
|
|
18
|
+
|
|
19
|
+
audio-bed-check bed ambience.wav # loop and level steps
|
|
20
|
+
audio-bed-check separation final.mp4 --vo read.wav
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
ambience.wav
|
|
25
|
+
FAIL loop 1.00 (repeats every 12.0s, at or above 0.90)
|
|
26
|
+
ok step 0.59 dB at 38.15s (max 6.00)
|
|
27
|
+
info range 3.0 dB transient 2.7 dB peak -5.1 dBTP
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
Exit 0 when every check passes, 1 when any fails, 2 when it could not run (a bad flag, an unreadable
|
|
31
|
+
file, no speech found in the voiceover). A `warn` line, such as a file peaking at or under -60 dBTP or a
|
|
32
|
+
voiceover that seems to start somewhere other than `--vo-offset`, never changes the exit code.
|
|
33
|
+
`--json` prints the numbers as a list of objects; the field list is in the command reference.
|
|
34
|
+
`python -m audio_bed_check` is the same command.
|
|
35
|
+
|
|
36
|
+
Check the bed before it is encoded. ffmpeg's built-in AAC at 128k rebuilt exact loops of steady
|
|
37
|
+
noise to scores between 0.88 and 0.97, some under the threshold; textured loops stayed at 1.00 after
|
|
38
|
+
AAC and MP3.
|
|
39
|
+
|
|
40
|
+
A 10-minute mono file takes about 2 s for `bed` and about 1.3 GB of memory; an hour takes about
|
|
41
|
+
40 s and 4 GB.
|
|
42
|
+
|
|
43
|
+
## The checks
|
|
44
|
+
|
|
45
|
+
`loop`: the frame-to-frame changes of the loudness envelope, correlated with themselves at every
|
|
46
|
+
lag over the best-matching 10 s window. A copied clip copies its texture, so a loop scores near 1.0
|
|
47
|
+
even when only part of the file repeats, or it fades out, or each repeat sits at a different gain.
|
|
48
|
+
Among the peaks that reach the threshold (`--loop-threshold`, 0.9), it reports the shortest one
|
|
49
|
+
scoring within 0.05 of the strongest. That is the repeat length rather than a multiple of it. A
|
|
50
|
+
repeat of 6 seconds or longer (`--min-period`) fails. A shorter one is reported and passes, because
|
|
51
|
+
music repeats at bar length. The loop check needs 13 s at the defaults; a shorter file reports ok
|
|
52
|
+
with a note.
|
|
53
|
+
|
|
54
|
+
`steps`: half-second loudness blocks every 0.1 s. The sustained step is the mean level over two
|
|
55
|
+
seconds after a half-second gap against the two seconds before; it fails above 6 dB (`--max-step`).
|
|
56
|
+
A bad join moves the level and it stays moved. A crowd surge spikes and comes back, so the largest
|
|
57
|
+
half-second transient and the range are printed but never fail the file. A change held about two
|
|
58
|
+
seconds or longer does fail, even if it comes back: a +7 dB plateau reads 3.9 dB held one second
|
|
59
|
+
and 6.7 held two. The steps check needs 6.5 s at the default edge; a shorter file reports ok with a
|
|
60
|
+
note.
|
|
61
|
+
|
|
62
|
+
`separation`: speech windows are found in the voiceover file, then compared with the bed-only gaps
|
|
63
|
+
between them. Each window's level is its 90th percentile of 50 ms K-weighted blocks. Both kinds of
|
|
64
|
+
window are measured in the mix, so the figure is voice plus bed against bed, which is closer to what
|
|
65
|
+
a listener hears than the gain on each stem. Profiles set the minimum: `music` 10 LU (the default),
|
|
66
|
+
`ambience` 15 LU, `wcag` 20 LU. The read needs pauses of 0.9 seconds or more. The voiceover's start
|
|
67
|
+
in the mix is estimated from the two envelopes, and a warning names it when it is more than 0.2 s
|
|
68
|
+
from `--vo-offset` (no estimate, and no warning, when the voice is too far under the bed to match); a mix whose bed-only windows are silent (the voiceover passed as the mix) is
|
|
69
|
+
refused.
|
|
70
|
+
|
|
71
|
+
The check compares speech windows with the bed in the gaps between them, so a bed that is ducked
|
|
72
|
+
under speech barely changes the figure. Torcoli et al. measured speech against the ducked
|
|
73
|
+
background, so treat the floors as approximate for ducked mixes.
|
|
74
|
+
|
|
75
|
+
| Check | Fails when | Default | Source |
|
|
76
|
+
|---|---|---|---|
|
|
77
|
+
| loop | repeat score at or above | 0.9, repeats of 6 s or longer | validation below |
|
|
78
|
+
| steps | sustained step above | 6 dB | chosen in one production pipeline where a 7 dB join was audible; no published source |
|
|
79
|
+
| separation, music | voice less than | 10 LU above bed | Torcoli et al., JAES 2019 |
|
|
80
|
+
| separation, ambience | voice less than | 15 LU above bed | Torcoli et al., JAES 2019 |
|
|
81
|
+
| separation, wcag | voice less than | 20 LU above bed | WCAG 2 technique G56 (stated there in dB(A) SPL) |
|
|
82
|
+
|
|
83
|
+
Every default can be changed with a flag; the full list is in
|
|
84
|
+
[skills/audio-bed-check/references/cli.md](https://github.com/oo-pibe/audio-bed-check/blob/main/skills/audio-bed-check/references/cli.md).
|
|
85
|
+
|
|
86
|
+
## Where the numbers come from
|
|
87
|
+
|
|
88
|
+
The loop check is validated on generated signals. The figures here are from one run of
|
|
89
|
+
[scripts/loop_sweep.py](https://github.com/oo-pibe/audio-bed-check/blob/main/scripts/loop_sweep.py),
|
|
90
|
+
which prints them. In that run, 400 unlooped beds of 30 to 600 seconds produced no failures
|
|
91
|
+
and the worst scored 0.75. Other seeds reach about 0.78, and longer files score higher by chance.
|
|
92
|
+
Loops under fades, in part of a file, with crossfaded joins or at changing gain all failed with the
|
|
93
|
+
right period, the lowest at 0.96. On one other seed a 10 s loop at gains up to 6 dB apart was named
|
|
94
|
+
at 20 s; it still failed. Beds with a 6 dB swell every 8 or 20 seconds passed, the highest at 0.85.
|
|
95
|
+
|
|
96
|
+
A repeat is seen only when the repeating stretch is at least one period plus the 10 s window long,
|
|
97
|
+
so a 6 to 8 second clip played twice usually is not. The longest repeat it can see is the file
|
|
98
|
+
length minus the window: about 10.5 s less than the file, or a third less under 30 s. A gain cycle
|
|
99
|
+
with nothing under it, such as a steady tremolo or the same swell twice on room tone, reads as a
|
|
100
|
+
loop; the details are in
|
|
101
|
+
[references/checks.md](https://github.com/oo-pibe/audio-bed-check/blob/main/skills/audio-bed-check/references/checks.md).
|
|
102
|
+
|
|
103
|
+
The loudness code is ITU-R BS.1770-4 K-weighting written in numpy. The test suite compares its
|
|
104
|
+
momentary loudness with ffmpeg's `ebur128` filter on the same file (median difference under 0.1 LU,
|
|
105
|
+
95th percentile under 0.2 LU), and its true peak on a test tone (within 0.2 dB). These tests skip
|
|
106
|
+
when no ffmpeg is found, or when the one found was built without `ebur128`.
|
|
107
|
+
|
|
108
|
+
## From Python
|
|
109
|
+
|
|
110
|
+
```python
|
|
111
|
+
from audio_bed_check import decode, loop_score, level_steps, separation
|
|
112
|
+
|
|
113
|
+
samples, sr = decode("ambience.wav")
|
|
114
|
+
loop_score(samples, sr).passed # False if it repeats
|
|
115
|
+
level_steps(samples, sr).step_db # the worst sustained step, dB
|
|
116
|
+
|
|
117
|
+
vo, _ = decode("read.wav")
|
|
118
|
+
mix, _ = decode("final.mp4")
|
|
119
|
+
separation(vo, mix, sr, min_lu=15).separation_lu
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
The check functions are pure functions of a float array at 48 kHz; `decode` always returns that.
|
|
123
|
+
|
|
124
|
+
## For coding agents
|
|
125
|
+
|
|
126
|
+
The package ships an [Agent Skill](https://github.com/oo-pibe/audio-bed-check/tree/main/skills/audio-bed-check)
|
|
127
|
+
describing when to run which check and how to read the result. Claude Code users can install it as a
|
|
128
|
+
plugin:
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
/plugin marketplace add oo-pibe/audio-bed-check
|
|
132
|
+
/plugin install audio-bed-check@audio-bed-check
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Prior art
|
|
136
|
+
|
|
137
|
+
- ITU-R BS.1770-4, the loudness algorithm.
|
|
138
|
+
- Rafii and Pardo, REPET, IEEE TASLP 21(1), 2013: the repeating-period idea behind the loop check.
|
|
139
|
+
- Torcoli, Freke-Morin, Paulus, Simon and Shirley, "Preferred Levels for Background Ducking to
|
|
140
|
+
Produce Esthetically Pleasing Audio for TV with Clear Speech", JAES 67(12), 2019,
|
|
141
|
+
doi:10.17743/jaes.2019.0052: the source of the 10 LU (music) and 15 LU (ambience) floors. The
|
|
142
|
+
same study found non-expert listeners wanted about 4 LU more than experts.
|
|
143
|
+
- WCAG 2 technique G56, the 20 dB speech-over-background rule, stated there in dB(A) SPL.
|
|
144
|
+
- ffmpeg's `ebur128` filter, the reference the loudness tests compare against.
|
|
145
|
+
|
|
146
|
+
## Origin
|
|
147
|
+
|
|
148
|
+
Extracted from the video pipeline at [Road to Kickoff](https://roadtokickoff.com). A bed there
|
|
149
|
+
stepped 7 dB at two joins, got past every automated check, and was caught by ear. The 6 dB step
|
|
150
|
+
limit comes from that bed.
|
|
151
|
+
|
|
152
|
+
## License
|
|
153
|
+
|
|
154
|
+
MIT.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
# Security
|
|
2
|
+
|
|
3
|
+
Report a vulnerability privately through GitHub's "Report a vulnerability" button on this
|
|
4
|
+
repository, or by email to contact@roadtokickoff.com. Please do not open a public issue for it.
|
|
5
|
+
|
|
6
|
+
The package itself makes no network requests. It runs ffmpeg on the files you name, with the input
|
|
7
|
+
restricted to the local file and ffmpeg's protocol whitelist set to file and pipe, so a filename that
|
|
8
|
+
looks like a URL is still read as a file. ffmpeg parses the file, so ffmpeg's demuxer bugs apply; keep
|
|
9
|
+
it updated. One environment variable is read, AUDIO_BED_CHECK_FFMPEG.
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.27"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "audio-bed-check"
|
|
7
|
+
dynamic = ["version"]
|
|
8
|
+
description = "Check an audio bed for loops and level steps, and a voiceover mix for speech-over-bed separation."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
license = "MIT"
|
|
11
|
+
requires-python = ">=3.10"
|
|
12
|
+
dependencies = ["numpy>=1.26"]
|
|
13
|
+
keywords = ["audio", "loudness", "bs1770", "ebu-r128", "loop-detection", "ducking", "ffmpeg", "video", "voiceover", "qa"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Development Status :: 4 - Beta",
|
|
16
|
+
"Environment :: Console",
|
|
17
|
+
"Intended Audience :: Developers",
|
|
18
|
+
"Programming Language :: Python :: 3",
|
|
19
|
+
"Programming Language :: Python :: 3 :: Only",
|
|
20
|
+
"Programming Language :: Python :: 3.10",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Multimedia :: Sound/Audio :: Analysis",
|
|
23
|
+
"Topic :: Multimedia :: Video",
|
|
24
|
+
]
|
|
25
|
+
|
|
26
|
+
[project.urls]
|
|
27
|
+
Homepage = "https://github.com/oo-pibe/audio-bed-check"
|
|
28
|
+
Issues = "https://github.com/oo-pibe/audio-bed-check/issues"
|
|
29
|
+
Security = "https://github.com/oo-pibe/audio-bed-check/blob/main/SECURITY.md"
|
|
30
|
+
|
|
31
|
+
[project.scripts]
|
|
32
|
+
audio-bed-check = "audio_bed_check.cli:main"
|
|
33
|
+
|
|
34
|
+
[project.optional-dependencies]
|
|
35
|
+
dev = ["pytest>=8", "ruff>=0.6", "build>=1.2"]
|
|
36
|
+
|
|
37
|
+
[tool.hatch.version]
|
|
38
|
+
path = "src/audio_bed_check/__init__.py"
|
|
39
|
+
|
|
40
|
+
[tool.hatch.build.targets.wheel]
|
|
41
|
+
packages = ["src/audio_bed_check"]
|
|
42
|
+
|
|
43
|
+
[tool.hatch.build.targets.wheel.force-include]
|
|
44
|
+
"skills" = "audio_bed_check/skills"
|
|
45
|
+
|
|
46
|
+
[tool.hatch.build.targets.sdist]
|
|
47
|
+
include = ["src", "tests", "skills", "scripts", "/.claude-plugin", "/README.md", "/SECURITY.md", "/LICENSE", "/pyproject.toml"]
|
|
48
|
+
|
|
49
|
+
[tool.ruff]
|
|
50
|
+
line-length = 110
|
|
51
|
+
target-version = "py310"
|
|
52
|
+
|
|
53
|
+
[tool.ruff.lint]
|
|
54
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
55
|
+
|
|
56
|
+
[tool.pytest.ini_options]
|
|
57
|
+
testpaths = ["tests"]
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
"""Reproduce the loop check's validation figures on generated beds. Not part of the test suite.
|
|
2
|
+
|
|
3
|
+
python scripts/loop_sweep.py # the published run
|
|
4
|
+
python scripts/loop_sweep.py --seed 1000 # the same sweep on other seeds
|
|
5
|
+
|
|
6
|
+
Prints the worst score of the unlooped beds per length, the lowest score among the looped beds and
|
|
7
|
+
whether each was caught with the right period, and the highest score among beds with periodic swells.
|
|
8
|
+
Run from the repository root; it uses the generators in tests/synth.py. The 600 s beds make a full
|
|
9
|
+
run take a few minutes.
|
|
10
|
+
"""
|
|
11
|
+
|
|
12
|
+
import argparse
|
|
13
|
+
import sys
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
|
|
16
|
+
import numpy as np
|
|
17
|
+
|
|
18
|
+
sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
|
|
19
|
+
|
|
20
|
+
from audio_bed_check.checks import loop_score # noqa: E402
|
|
21
|
+
from tests.synth import SR, fade_edges, gain, swell_gain, textured, tile # noqa: E402
|
|
22
|
+
|
|
23
|
+
UNLOOPED = [(30, 120), (48, 120), (60, 120), (180, 20), (600, 20)] # (seconds, beds)
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def fade_out(x, seconds, power=1):
|
|
27
|
+
y = x.astype(np.float64).copy()
|
|
28
|
+
k = int(seconds * SR)
|
|
29
|
+
y[-k:] *= np.linspace(1, 0, k) ** power
|
|
30
|
+
return y.astype(np.float32)
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def looped(seed):
|
|
34
|
+
"""(name, signal, period in seconds) for every kind of loop the docs say is caught."""
|
|
35
|
+
loop = tile(textured(10, seed), 6)
|
|
36
|
+
for s in (0.25, 0.5, 1.0, 2.0, 5.0):
|
|
37
|
+
yield f"{s:g} s fade-out", fade_out(loop, s), 10.0
|
|
38
|
+
yield "1 s fade in and out", fade_edges(loop, 1.0), 10.0
|
|
39
|
+
yield "whole-file fade", fade_out(loop, 60.0), 10.0
|
|
40
|
+
yield "30 s quadratic fade-out", fade_out(loop, 30.0, power=2), 10.0
|
|
41
|
+
clip = textured(10, seed)
|
|
42
|
+
yield "4 tiles then 20 s unrelated", np.concatenate([tile(clip, 4), textured(20, seed + 1)]), 10.0
|
|
43
|
+
yield "20 s unrelated then 4 tiles", np.concatenate([textured(20, seed + 2), tile(clip, 4)]), 10.0
|
|
44
|
+
yield "60 s unrelated then 2 tiles", np.concatenate([textured(60, seed + 3), tile(clip, 2)]), 10.0
|
|
45
|
+
for c in (0.2, 0.5, 1.0, 2.0, 3.0, 5.0):
|
|
46
|
+
yield f"{c:g} s crossfade", tile(textured(12, seed), 4, crossfade=c), 12.0 - c
|
|
47
|
+
rng = np.random.default_rng(seed)
|
|
48
|
+
for spread in (3, 6):
|
|
49
|
+
x = np.concatenate([gain(textured(10, seed), rng.uniform(-spread, spread)) for _ in range(6)])
|
|
50
|
+
yield f"gains within +-{spread} dB", x, 10.0
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def main():
|
|
54
|
+
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
|
|
55
|
+
ap.add_argument("--seed", type=int, default=0, help="first seed (default 0)")
|
|
56
|
+
seed = ap.parse_args().seed
|
|
57
|
+
|
|
58
|
+
print("unlooped textured beds (none should fail)")
|
|
59
|
+
print(f" {'length':>7} {'beds':>5} {'failed':>7} {'worst':>6}")
|
|
60
|
+
overall = 0.0
|
|
61
|
+
for seconds, count in UNLOOPED:
|
|
62
|
+
scores = [loop_score(textured(seconds, seed + j), SR) for j in range(count)]
|
|
63
|
+
failed = sum(not r.passed for r in scores)
|
|
64
|
+
worst = max(r.score for r in scores)
|
|
65
|
+
overall = max(overall, worst)
|
|
66
|
+
print(f" {seconds:>6}s {count:>5} {failed:>7} {worst:>6.2f}")
|
|
67
|
+
print(f" worst of all: {overall:.2f}")
|
|
68
|
+
|
|
69
|
+
print("looped beds (all should fail with the right period)")
|
|
70
|
+
lowest, wrong = 1.0, []
|
|
71
|
+
for name, x, period in looped(seed + 5000):
|
|
72
|
+
r = loop_score(x, SR)
|
|
73
|
+
lowest = min(lowest, r.score)
|
|
74
|
+
if r.passed or r.period_s is None or abs(r.period_s - period) > 0.15:
|
|
75
|
+
wrong.append(f"{name}: score {r.score:.2f}, period {r.period_s}")
|
|
76
|
+
print(f" lowest score: {lowest:.2f}; missed or wrong period: {len(wrong)}")
|
|
77
|
+
for line in wrong:
|
|
78
|
+
print(f" {line}")
|
|
79
|
+
|
|
80
|
+
print("periodic swells on a 120 s textured bed (none should fail)")
|
|
81
|
+
highest, failed = 0.0, 0
|
|
82
|
+
for j in range(10):
|
|
83
|
+
bed = textured(120, seed + 6000 + j)
|
|
84
|
+
every_20 = np.prod([swell_gain(len(bed), c, 4, 6) for c in np.arange(10, 120, 20)], axis=0)
|
|
85
|
+
every_8 = np.prod([swell_gain(len(bed), c, 3, 6) for c in np.arange(5, 120, 8)], axis=0)
|
|
86
|
+
for g in (every_20, every_8):
|
|
87
|
+
r = loop_score((bed * g).astype(np.float32), SR)
|
|
88
|
+
highest, failed = max(highest, r.score), failed + (not r.passed)
|
|
89
|
+
print(f" 20 beds, failed: {failed}, highest score: {highest:.2f}")
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
if __name__ == "__main__":
|
|
93
|
+
main()
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: audio-bed-check
|
|
3
|
+
description: "Use when a rendered audio bed, ambience track or voiceover mix needs checking before it ships: whether a bed repeats itself (a loop), whether its level jumps at a join, or whether a voiceover sits far enough above the bed to be heard. Covers the audio-bed-check command and Python library (BS.1770 loudness, ffmpeg on PATH)."
|
|
4
|
+
license: MIT
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# audio-bed-check
|
|
8
|
+
|
|
9
|
+
Three checks on finished audio, each a pass or fail with the number behind it. Install with
|
|
10
|
+
`pip install audio-bed-check`; ffmpeg must be on PATH or named in `AUDIO_BED_CHECK_FFMPEG`.
|
|
11
|
+
`python -m audio_bed_check` is the same command. Files keep their channels (stereo is measured per
|
|
12
|
+
channel and summed, as BS.1770 does); only the first audio track is read.
|
|
13
|
+
|
|
14
|
+
## Which check
|
|
15
|
+
|
|
16
|
+
- The bed on its own, before it goes under anything: `audio-bed-check bed BED.wav`. Runs `loop`
|
|
17
|
+
(does it repeat?) and `steps` (does the level lurch?). Several files at once are fine.
|
|
18
|
+
- A rendered mix with a voiceover: `audio-bed-check separation MIX.mp4 --vo READ.wav`. Needs the
|
|
19
|
+
voiceover file on its own, exactly as it was placed in the mix (`--vo-offset` if it does not start
|
|
20
|
+
at zero).
|
|
21
|
+
|
|
22
|
+
Exit 0 means every check passed, 1 means at least one failed, 2 means a check could not run (no
|
|
23
|
+
ffmpeg, unreadable file, no speech found). `warn` lines (a silent file, a hot peak, an offset that
|
|
24
|
+
disagrees with the voiceover) never change the exit code; a `warn` line is something to look at. Add `--json` to get the numbers as a list
|
|
25
|
+
of objects; `--edge`, `--gate` and `--vo-offset` are not recorded in it.
|
|
26
|
+
|
|
27
|
+
Check the bed before it is encoded: ffmpeg's AAC at 128k rebuilt exact loops of steady noise to
|
|
28
|
+
scores between 0.88 and 0.97, some under the threshold. `loop` needs 13 s
|
|
29
|
+
and `steps` 6.5 s at the defaults; a shorter file reports ok with a note, not a verdict.
|
|
30
|
+
|
|
31
|
+
## Reading the result
|
|
32
|
+
|
|
33
|
+
- `loop`: score is the correlation of the level's frame-to-frame changes at the repeat it found,
|
|
34
|
+
over the best-matching 10 s window; 1.0 is an exact repeat. Fails at 0.9 or above when the repeat
|
|
35
|
+
is at or longer than `--min-period` (6 s). A shorter repeat is reported as a note, because music
|
|
36
|
+
repeats at bar length and that is not a loop. A loop in part of the file, under a fade or at
|
|
37
|
+
changing gain is still found. A repeat is seen only when the repeating stretch is at least one
|
|
38
|
+
period plus 10 s long, so a 6 to 8 s clip played twice usually is not; a repeat longer than the
|
|
39
|
+
file minus about 10.5 s is not seen either.
|
|
40
|
+
- `steps`: fails on a sustained step above `--max-step` (6 dB): the mean level over the 2 s after a
|
|
41
|
+
0.5 s gap at a boundary against the 2 s before, on half-second blocks every 0.1 s. A change held
|
|
42
|
+
about 2 s or longer fails even if it comes back (a +7 dB plateau reads 6.7 held 2 s). Range and
|
|
43
|
+
the largest half-second transient are printed for information only, because a crowd surge comes
|
|
44
|
+
back and a join does not.
|
|
45
|
+
- `separation`: the mix inside the voiceover's speech windows against the bed-only gaps between
|
|
46
|
+
them, in LU. Fails under the profile's minimum: `music` 10, `ambience` 15, `wcag` 20. The read
|
|
47
|
+
needs pauses of 0.9 s or more. When the voiceover seems to start somewhere other than
|
|
48
|
+
`--vo-offset` (more than 0.2 s off), a `warn` line names where; rerun with that offset. A voice
|
|
49
|
+
too far under the bed to match gives no estimate and no warning. A bed
|
|
50
|
+
ducked under the speech barely changes the figure, so treat the floors as approximate for ducked
|
|
51
|
+
mixes.
|
|
52
|
+
|
|
53
|
+
Thresholds and their sources: [references/checks.md](references/checks.md). Every flag and every
|
|
54
|
+
message: [references/cli.md](references/cli.md).
|
|
55
|
+
|
|
56
|
+
## From Python
|
|
57
|
+
|
|
58
|
+
```python
|
|
59
|
+
from audio_bed_check import decode, loop_score, level_steps, separation
|
|
60
|
+
|
|
61
|
+
samples, sr = decode("bed.wav")
|
|
62
|
+
print(loop_score(samples, sr).passed, level_steps(samples, sr).step_db)
|
|
63
|
+
vo, _ = decode("read.wav"); mix, _ = decode("final.mp4")
|
|
64
|
+
print(separation(vo, mix, sr, min_lu=15).separation_lu)
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
The check functions take a float array at 48 kHz, `(n,)` mono or `(n, 2)` stereo; `decode` returns
|
|
68
|
+
48 kHz, mono or stereo as the file is (more than two channels downmixed to two).
|
|
69
|
+
|
|
70
|
+
## Do not
|
|
71
|
+
|
|
72
|
+
- Do not run `separation` on the bed alone or on the voiceover alone; it needs the voiceover and the
|
|
73
|
+
mix that contains it.
|
|
74
|
+
- Do not treat a high `transient` as a failure. Only `step` fails.
|
|
75
|
+
- Do not lower `--min-period` below the length of a musical bar unless you want bars flagged.
|
|
76
|
+
|
|
77
|
+
## Limitations
|
|
78
|
+
|
|
79
|
+
A steady gain cycle with no texture under it (tremolo, the same swell twice on room tone, beating
|
|
80
|
+
between detuned tones) also fails; the check measures repetition, not provenance.
|