Audioscan: one decode pass instead of three ffmpeg shellouts
My first real Rust tool, and what it taught me about audio measurement, calling code across a language boundary, and refusing to trust a number I had not checked.
If someone forwarded this to you: I mix and master music, and I build software with AI agents on the side. Audioscan fell out of one of those projects. It reads an audio file once and reports its format, its loudness, and where the silent gaps are, as clean structured data. It is also the first real thing I have shipped in Rust, a language built for exactly this kind of fast, careful systems work.
github.com/KiwiMaddog2020/audioscan kevinmadson@protonmail.com
Reading numbers out of another tool’s status text
I mix and master music, and one of my projects is a private catalog of the recordings I work on. It needs two unglamorous things from every take: how loud it is, so tracks sit at a consistent level instead of jumping around, and where the silent gaps fall, so it can split a long session into separate songs.
The first version got both by shelling out to ffmpeg and scraping the numbers from the progress text it prints while it runs. Two things were wrong with that. To produce any measurement at all, the file has to be decoded from its compressed form into raw PCM samples, and this approach decoded each take two or three separate times. The second problem was worse, and it bit. The ebur128 meter prints a final integrated summary at the end of the stream; my scraper once latched onto an early, transient reading from the opening of a track instead, so the catalog quietly stored a loudness off by tens of decibels. I patched the regex. But a patch on a scrape-the-chatter method only buys time until the chatter changes shape again.
Decode once, measure everything
Audioscan decodes each file exactly once, using the Rust audio library symphonia, and measures loudness with the real ebur128 crate. That is the same math ffmpeg runs under the hood, built to the EBU R128 standard streaming services use to keep playback level steady. In that same pass it finds the silent gaps and emits structured data:
{
"container": "wav", "codec": "pcm_s16le",
"sample_rate": 48000, "channels": 2, "duration_sec": 212.5,
"integrated_lufs": -14.2, "loudness_range_lu": 8.6, "true_peak_dbtp": -1.1,
"silence_threshold_db": -30.0, "silences": [[6.0, 12.0]],
"status": "ok", "warnings": []
}
The single pass is the design. As samples come off the decoder, the same stream feeds the loudness meter and a running test for when amplitude drops below the silence threshold. One read, two answers. And because the output is data rather than prose, the catalog runs the program and reads its result. Same numbers. Fewer passes. Nothing to scrape.
Trusting the numbers
You cannot claim “same numbers” without proving it, so I checked, against ffmpeg’s own loudness measurement on synthetic test signals:
| signal | metric | Audioscan | ffmpeg |
|---|---|---|---|
| 1 kHz tone, then 6 s of silence | loudness | -6.26 LUFS | -6.3 LUFS |
| silence window | [6.0, 12.0] | built at 6 to 12 s | |
| five tones at varied levels | loudness | -9.46 LUFS | -9.5 LUFS |
| loudness range | 11.0 LU | 11.0 LU |
The whole table reproduces from the repo in three commands. One caveat went into the README instead of getting buried: loudness range (LRA, the spread between the quiet and loud passages of a track) only agrees when the signal actually varies. On a flat two-level test tone, the gating statistics that LRA depends on are unstable in both tools, and the two disagree. That is expected, not a bug, and the README says so plainly. A validation table that shows only the rows that agree is not a validation table.
What the first real Rust tool taught me
I came to this from Python, JavaScript, and Swift. A few things were genuinely new.
The language boundary was the surprising part. Audioscan works as a standalone program and as a library other languages can link against directly, through a C ABI generated by cbindgen, with no separate process to launch. That is how it will eventually drop into a Mac app. Wiring it up cost me an afternoon and one ugly gotcha: a version skew between the Rust toolchain and cbindgen produced a valid header with none of the functions in it. A one-line version bump fixed it. I only noticed because the generated file was blank where it should have declared three exported functions, the kind of failure that passes every test right up until someone tries to use the thing.
New formats are a config line, not a rewrite. symphonia already handles the common formats; I enabled a few more, mp3, aac, and the AAC stream inside mp4 containers, for the compressed files the catalog ingests. The next one is a line in a feature list, not a hand-written decoder.
Folder mode is where the real care lives. Pointed at a directory, Audioscan walks it and prints one data line per file, processing several at a time. Three decisions earned their keep. Each file runs walled off, so one corrupt recording in a batch of two thousand becomes a single error row rather than a crashed run. The data stream stays byte-identical regardless of parallelism, because progress messages go to stderr and never bleed into stdout. And a soft timeout, checked between decode chunks, lets a wedged file surrender at a deadline instead of hanging the batch, while a legitimately long recording is never truncated unless you set a limit.
What it is, and isn’t
About a thousand lines of Rust. 27 tests across eight files: loudness checked against ffmpeg, real audio-file fixtures, folder-scan isolation, the cross-language bridge, the timeout, and bad-input handling. Released under two permissive licenses.
It was built to stand alone, and it is no longer standing alone: the catalog now runs its loudness measurement through audioscan in production, and reaches for the same one-pass engine to split a long session at its silences. Swapping a production system’s measurement path is a deliberate change, not something to bolt on beside a brand-new tool, so I held off until the numbers had been checked against ffmpeg. When I finally made the swap it landed as quietly as the run-a-program-read-its-data shape promised it would, which was the whole reason for building it that way. This is one person’s tool for one job, n=1, not a general-purpose media framework, and I will not pretend otherwise.
The checkable numbers
Clone it, build it, point it at a .wav, and compare the output to ffmpeg’s own
loudness measurement. The validation table, the test signals, and the folder-scan
behavior all live in the repository, and the numbers above are the ones it actually
prints. If they do not reproduce on your machine, that is a bug, and I want to hear
about it.