ferraus remove-sound

Learn an unwanted sound and subtract it everywhere

Quality tier: best-effort. Results are reported with a quality or confidence estimate.

Synopsis

ferraus remove-sound <input> [options] [-o <output>]

Learns spectral templates of an unwanted sound (a siren, a fridge, a phone buzz) from a region where it plays alone (--learn) or from a saved model, then subtracts the best-matching template from every frame. Best-effort: reports the residual energy left in the learned region as a quality estimate. --save-model writes the learned templates for reuse with --model.

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

Examples

Learn the siren from 10-14 s and remove it

ferraus remove-sound street.wav --learn 0:10..0:14 -o clean.wav

Reuse a saved model of a buzz

ferraus remove-sound take2.wav --model buzz.json --strength 90% -o clean.wav

Learn a fridge hum, remove it, and save the model for the next take

ferraus remove-sound kitchen.wav --learn 1:20..1:26 --save-model fridge.json -o clean.wav

No dialogue here: subtract across the whole spectrum, with more templates and passes

ferraus remove-sound bed.wav --learn 0:02..0:05 --protect-speech off --complexity 32 --passes 3 -o clean.wav

Options

Flag	Type	Default	Meaning
`--learn`	range	—	Region containing only the unwanted sound (start..end)
`--model`	path	—	Load templates saved earlier with --save-model instead of --learn
`--save-model`	path	—	Write the learned templates to this JSON file
`--complexity`	integer	`20`	Number of spectral templates learned (more follows a changing sound) Range: 1..64.
`--passes`	integer	`2`	Subtraction passes Range: 1..8.
`--strength`	percent	`70%`	How hard to subtract, in percent
`--protect-speech`	on\|off	`on`	Limit reduction in the 100 Hz-4 kHz speech band (on\|off)
`--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.
Percentages accept 80% or the fraction 0.8; a bare 80 means 80x, not 80%.
Treating best-effort output as final: check the reported quality/confidence in --json.

For models

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

{"command": "remove-sound", "defaults": {"complexity": "20", "passes": "2", "strength": "70%", "protect_speech": "on", "mix": "100%"}}