Codec Changes Need Regression Tests
A successful transcode only proves a decoder could open the result. It says nothing about lost attacks, collapsed stereo width, spectral smearing, or accidental silence.
codecguard synthesizes a deterministic stereo master, runs a real FFmpeg encode and decode, aligns encoder priming, and evaluates four independent dimensions.
The Demo
The release candidate reaches 33.396 dB SNR, 0.02087 spectral convergence, 0.9954 transient retention, and 0.00025 stereo-width error, passing every gate. The degraded build fails all four.
Signal metrics keep CI deterministic. They don't replace perceptual codecs, listening panels, or content-diverse mastering review.
A Gate That Couldn't Measure Short Clips
A CI gate has to work on the assets a pipeline actually produces, not just a three-second reference master. The multi-resolution spectral check floored its frame count at one even when the clip was shorter than the FFT window it was about to build, so any clip under 8,192 samples, roughly 170 ms, crashed with an index error. That's an entirely ordinary length for an SFX cue or a dialogue snippet.
The repo's own test was named to guarantee short clips stay measurable and passed only because its fixture happened to be just long enough. It now uses window sizes that fit the clip, falling back to a single whole-clip window.
It Couldn't Encode Opus at All
Auditing this page, I ran the gate across the codecs someone would actually ship instead of the synthetic degraded build. Two things came out of it.
First, the gate works. FLAC round-trips at 108.9 dB with exactly zero spectral error, which is the sanity check that matters: a lossless path has to look lossless. AAC at 192k, Vorbis at 128k, Opus at 96k, and MP3 at 128k all pass. Starve them and they fail on the right dimensions: AAC at 64k and MP3 at 32k both fail SNR, spectrum, and transients, and Opus at 24k fails all four.
Second, Opus and Vorbis couldn't be benchmarked at all. The output filename took its extension from the codec name, with one special case for libmp3lame, so Opus produced candidate.libopus and FFmpeg can't choose a muxer for that. The encode failed outright. An encoder name is not a container name, and that's now an explicit table, with an unknown codec raising an error that says to add it rather than building a filename nothing can write. 11 tests pass across Python 3.10 through 3.13.
Implementation Basis
The gate combines multi-resolution frequency evidence with time-domain transients, stereo energy, and aligned waveform error. Read the FFmpeg codec documentation.
Try It
Needs FFmpeg:
git clone https://github.com/ahmeddoghri/codecguard && cd codecguard
pip install -e .
codecguard demo # clean build vs degraded build
codecguard benchmark out/ --codec libopus --bitrate 96k
codecguard benchmark out/ --codec libmp3lame --bitrate 32k # watch it fail
codecguard serve # workbench on :8090