ferraus waveform

Export a waveform image (PNG, SVG) or JSON peaks

Synopsis

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

Draws the waveform as a PNG or SVG image, or writes min/max peaks per time bucket and channel as JSON for web players and agents. The format follows the output extension (.png by default, .svg, .json). Images show the peak envelope with the RMS level drawn darker inside it.

Examples

1200x200 PNG thumbnail

ferraus waveform song.wav -o song.png

Peaks for a web player, 20 buckets per second

ferraus waveform episode.mp3 -o peaks.json --peaks-per-second 20

SVG with one lane per channel

ferraus waveform stereo.wav --split --width 800 --height 300 -o wave.svg

Options

Flag	Type	Default	Meaning
`--width`	integer	`1200`	Image width in pixels
`--height`	integer	`200`	Image height in pixels
`--peaks-per-second`	number	`50`	JSON only: min/max buckets per second of audio
`--split`	flag	—	Draw each channel in its own lane instead of one mixed waveform
`--color`	text	`#1f6feb`	Waveform colour, #rrggbb
`--background`	text	`transparent`	Background colour, #rrggbb or transparent

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.

For models

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

{"command": "waveform", "defaults": {"width": "1200", "height": "200", "peaks_per_second": "50", "color": "#1f6feb", "background": "transparent"}}