ferraus declip

Repair clipped peaks by autoregressive interpolation

Synopsis

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

Finds flat-topped (clipped) runs and re-synthesises each one from the samples around it with a least-squares autoregressive model, so the restored waveform rises above the old clip level. The output gain is then lowered by --headroom (and further if needed) so the restored peaks fit below full scale.

This command is also an fx stage and a pipeline op: ferraus fx in.wav -o out.wav --fx "declip:key=value".

Examples

Detect and repair clipping automatically

ferraus declip loud.wav -o fixed.wav

Treat everything above -0.3 dBFS as clipped and leave 6 dB of room

ferraus declip take.wav --threshold -0.3dB --headroom 6dB -o fixed.wav

Repair only short clipped runs (up to 4 ms) and leave longer ones untouched

ferraus declip interview.wav --max-gap 4ms -o fixed.wav

Treat samples above 95% of full scale as clipped and use a higher model order for dense music

ferraus declip live.wav --threshold 0.95x --order 64 -o fixed.wav

Options

Flag	Type	Default	Meaning
`--threshold`	text	`auto`	Clip level as a gain (-0.1dB, 0.98x), or 'auto' to detect flat-topped runs
`--max-gap`	time	`10ms`	Longest clipped run to repair (time, e.g. 10ms); longer runs are left alone
`--headroom`	gain	`3dB`	Output gain reduction in dB applied when clipping was repaired, so restored peaks fit
`--order`	integer	`32`	Autoregressive model order (higher follows complex material better, slower) Range: 2..128.
`--mix`	percent	`100%`	Dry/wet balance: 0% returns the input unchanged, 100% is fully processed

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.
Beat-based times (4b, 1/4) need a tempo: pass --bpm or write 4b@120.
Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

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

{"command": "declip", "defaults": {"threshold": "auto", "max_gap": "10ms", "headroom": "3dB", "order": "32", "mix": "100%"}}