ferraus spectrogram

Export a spectrogram as a PNG image or JSON matrix

Synopsis

ferraus spectrogram <input> [options] [-o <output>]

Computes a short-time Fourier transform of the mono mix (Hann window) and writes it as a PNG (time left to right, low frequencies at the bottom) or as JSON (dB values per frame and bin, 0 dB = loudest point, floored at -db-range). --mel 128 groups the bins into 128 mel bands, which matches hearing and is what ML models expect; --mel 0 keeps linear FFT bins.

Examples

128-band mel spectrogram image

ferraus spectrogram song.wav -o song_spec.png

Linear-frequency matrix in JSON for analysis

ferraus spectrogram voice.wav --mel 0 --fft 4096 --hop 256 -o voice_spec.json

Fixed-size image with 60 dB range

ferraus spectrogram drums.wav --width 1200 --height 300 --db-range 60 -o drums.png

Options

Flag	Type	Default	Meaning
`--fft`	integer	`2048`	FFT size in samples (frequency resolution)
`--hop`	integer	`512`	Hop between frames in samples (time resolution)
`--mel`	integer	`128`	Number of mel bands; 0 for linear frequency bins
`--db-range`	gain	`80dB`	Dynamic range shown, in dB below the loudest point
`--fmin`	frequency	`0Hz`	Lowest mel band edge (Hz)
`--fmax`	frequency	—	Highest mel band edge (Hz); defaults to half the sample rate
`--width`	integer	`0`	PNG width in pixels; 0 = one column per frame
`--height`	integer	`0`	PNG height in pixels; 0 = one row per band

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Code	Meaning
0	Success
1	Processing failed
2	Usage or parameter error
3	Input missing or unreadable
4	Unsupported format or codec
8	Cancelled
70	Internal error (bug)

Common mistakes

Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.
Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

MCP tool: ferraus_spectrogram
Schema: ferraus schema spectrogram
Pipeline: { op: spectrogram, args: { ... } } (flag names with _ instead of -)
fx stage: no

{"command": "spectrogram", "defaults": {"fft": "2048", "hop": "512", "mel": "128", "db_range": "80dB", "fmin": "0Hz", "width": "0", "height": "0"}}