Using sounddiff in CI

Using sounddiff in CI

sounddiff can run in your CI/CD pipeline to catch audio regressions automatically. The --ci and --threshold flags let you define acceptable limits and fail the build if they're exceeded.

Basic usage

sounddiff --ci --threshold loudness=0.5,peak=0.3 reference.wav output.wav

If either threshold is exceeded, sounddiff exits with code 1 and prints which thresholds failed.

Exit codes

Code	Meaning
0	All thresholds pass
1	One or more thresholds exceeded
2	Error (bad input, missing file, invalid threshold)

Available thresholds

Key	What it checks	Unit	Example
loudness	Absolute LUFS delta	dB	loudness=0.5 (fail if loudness changes by more than 0.5 dB)
peak	Absolute true peak delta	dBTP	peak=0.3 (fail if peak changes by more than 0.3 dBTP)
lra	Absolute loudness range delta	LU	lra=1.0 (fail if dynamic range changes by more than 1.0 LU)
duration	Absolute duration delta	seconds	duration=0.01 (fail if duration changes by more than 10ms)
correlation	Minimum overall correlation	0-1	correlation=0.99 (fail if waveforms diverge)
spectral	Max absolute spectral band delta	dB	spectral=3.0 (fail if any frequency band changes by more than 3 dB)

You can combine any number of thresholds:

sounddiff --ci --threshold loudness=0.5,peak=0.3,correlation=0.99,spectral=3.0 ref.wav test.wav

Choosing thresholds

Thresholds depend on what your pipeline does. Here are starting points for common scenarios:

Lossless transcoding (WAV to FLAC)

Should produce bit-identical output:

--threshold loudness=0.01,peak=0.01,correlation=0.999

Lossy encoding (WAV to MP3/AAC/Opus)

Expect some change, but not too much:

--threshold loudness=0.5,peak=0.5,spectral=6.0,correlation=0.95

Loudness normalization

Loudness will change (that's the point), but spectral balance and structure should be preserved:

--threshold spectral=1.0,correlation=0.98,duration=0.01

Mastering pipeline

Tight control over everything:

--threshold loudness=0.3,peak=0.2,lra=0.5,spectral=2.0,correlation=0.97

GitHub Actions example

name: Audio Quality Check
on: [push]

jobs:
  audio-check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install sounddiff
        run: pip install sounddiff

      - name: Run audio regression test
        run: |
          sounddiff --ci --threshold loudness=0.5,peak=0.3 \
            tests/fixtures/reference.wav \
            tests/fixtures/output.wav

Combining with other output formats

The --ci flag works with any output format. The threshold check happens after the report is generated, so you can get both a human-readable report and a CI exit code:

# Generate HTML report AND check thresholds
sounddiff --ci --threshold loudness=0.5 \
  --format html -o report.html \
  reference.wav output.wav

# Generate JSON for further processing AND check thresholds
sounddiff --ci --threshold loudness=0.5 \
  --format json \
  reference.wav output.wav > results.json

The exit code reflects the threshold check regardless of output format.