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.
Files changed (28) hide show
  1. audio_bed_check-0.1.0/.claude-plugin/marketplace.json +12 -0
  2. audio_bed_check-0.1.0/.claude-plugin/plugin.json +8 -0
  3. audio_bed_check-0.1.0/.gitignore +8 -0
  4. audio_bed_check-0.1.0/LICENSE +21 -0
  5. audio_bed_check-0.1.0/PKG-INFO +181 -0
  6. audio_bed_check-0.1.0/README.md +154 -0
  7. audio_bed_check-0.1.0/SECURITY.md +9 -0
  8. audio_bed_check-0.1.0/pyproject.toml +57 -0
  9. audio_bed_check-0.1.0/scripts/loop_sweep.py +93 -0
  10. audio_bed_check-0.1.0/skills/audio-bed-check/SKILL.md +80 -0
  11. audio_bed_check-0.1.0/skills/audio-bed-check/references/checks.md +147 -0
  12. audio_bed_check-0.1.0/skills/audio-bed-check/references/cli.md +160 -0
  13. audio_bed_check-0.1.0/src/audio_bed_check/__init__.py +22 -0
  14. audio_bed_check-0.1.0/src/audio_bed_check/__main__.py +5 -0
  15. audio_bed_check-0.1.0/src/audio_bed_check/checks.py +408 -0
  16. audio_bed_check-0.1.0/src/audio_bed_check/cli.py +208 -0
  17. audio_bed_check-0.1.0/src/audio_bed_check/decode.py +110 -0
  18. audio_bed_check-0.1.0/src/audio_bed_check/loudness.py +152 -0
  19. audio_bed_check-0.1.0/tests/__init__.py +0 -0
  20. audio_bed_check-0.1.0/tests/synth.py +166 -0
  21. audio_bed_check-0.1.0/tests/test_cli.py +271 -0
  22. audio_bed_check-0.1.0/tests/test_decode.py +210 -0
  23. audio_bed_check-0.1.0/tests/test_docs.py +100 -0
  24. audio_bed_check-0.1.0/tests/test_ffmpeg_oracle.py +133 -0
  25. audio_bed_check-0.1.0/tests/test_loop.py +262 -0
  26. audio_bed_check-0.1.0/tests/test_loudness.py +144 -0
  27. audio_bed_check-0.1.0/tests/test_separation.py +232 -0
  28. 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,8 @@
1
+ {
2
+ "name": "audio-bed-check",
3
+ "version": "0.1.0",
4
+ "description": "Check an audio bed for loops and level steps, and a voiceover mix for speech-over-bed separation.",
5
+ "author": { "name": "oo-pibe" },
6
+ "license": "MIT",
7
+ "skills": "./skills/"
8
+ }
@@ -0,0 +1,8 @@
1
+ .venv/
2
+ __pycache__/
3
+ *.pyc
4
+ dist/
5
+ build/
6
+ *.egg-info/
7
+ .pytest_cache/
8
+ .ruff_cache/
@@ -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.