Friday fun: inspecting audio files from my terminal

I discovered something I should have known years ago. You can inspect audio files from your terminal without opening a single GUI tool, and the output is readably human.

soxi audio.wav

That one command prints everything you need to know about an audio file. Sample rate, bit depth, number of channels, duration, file size. No clicking through Audacity menus, no running a media player, no dragging a file onto a website.

Input File     : 'audio.wav'
Channels       : 1
Sample Rate    : 16000
Precision      : 16-bit
Duration       : 00:03:42.15 = 3554400 samples ~ 16661 CDDA sectors
File Size      : 7.11M
Bit Rate       : 256k
Sample Encoding: 16-bit Signed Integer PCM

That is a perfectly valid mono 16-bit 16kHz WAV file, which is exactly what most speech-to-text APIs expect. When a file fails to transcribe, the first thing I do is run soxi. Nine times out of ten the sample rate is 48kHz or the file is stereo or the bit depth is 24-bit and none of that tells me anything useful until soxi shows me.

Where I found it

sox is the full audio processing toolkit. Trim, convert, resample, apply effects, mix tracks. It has been around since the 90s and it ships with Homebrew. soxi is the read-only sibling that just dumps the header. I installed sox years ago for format conversion and never noticed soxi existed until I saw someone use it in a debugging walkthrough.

brew install sox

Then soxi comes free.

Why it matters for voice AI

Every voice API pipeline starts with an audio file. If the file is wrong in any dimension, the pipeline fails silently or nonsensically. A stereo recording sent to a mono-only endpoint produces silence on one channel. A 22kHz file resampled without dithering introduces artifacts that degrade transcription. You can chase these for an hour or run soxi in three seconds.

The output file size alone tells you something useful. A 30-second mono 16-bit 16kHz WAV is about 960KB. If your file is 5MB for the same duration, something is off. The encoding line tells you whether the API will accept it at all.

What about ffprobe?

ffprobe does the same thing and more. I use it too. But soxi output is easier to read at a glance. Less noise, fewer lines, just the fields you actually check.

ffprobe audio.wav

Gives you more detail. soxi gives you the four or five values you actually compare against the API spec. Both are fine. Pick the one whose output your eyes parse faster.

The real reason I wrote this

Because I spent three hours once debugging a pipeline that failed because the audio file was in AIFF format, not WAV. The API returned a generic error. The log said nothing useful. I eventually ran file audio.aiff and it said “AIFF audio” and I felt like an idiot. soxi would have told me in one line.

Friday fun: your terminal knows more about audio than you do. It always did. You just had to ask.

FAQ

What is soxi? soxi is a command-line tool that reads audio file headers and prints the metadata. It is part of the SoX (Sound eXchange) suite.

Does soxi work on macOS? Yes. Install SoX via Homebrew (brew install sox) and soxi is included.

What formats does soxi support? WAV, AIFF, FLAC, MP3, OGG, and most common audio formats. It reads whatever SoX supports.

How is soxi different from ffprobe? soxi output is shorter and focused on the fields you check against API requirements. ffprobe gives more technical detail. Both are useful.

Can I use soxi in a script? Yes. Use soxi -V for verbose or parse the standard output with grep or awk. It works well in CI pipelines to validate audio files before submission.