ferraus leveler

Slow speech volume leveler

Synopsis

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

Rides the gain slowly so quiet and loud passages of speech end up near --target. A 300 ms RMS detector drives a gain that moves at most --amount of the way to the target (boosts settle in about 0.5 s, cuts in 0.2 s). Material below --gate is treated as background noise and never boosted; material between --gate and --range (low-level signals) is only boosted with --boost-low on.

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

Examples

Even out a speech recording

ferraus leveler podcast.wav -o level.wav

Stronger leveling for a distant speaker

ferraus leveler lecture.wav --target -16dB --amount 80% --boost-low on -o level.wav

Noisy room: freeze the gain below -50 dBFS so background noise is never pulled up

ferraus leveler panel.wav --gate -50dB --range -40dB -o level.wav

Light-touch leveling that keeps a narrator's natural dynamics

ferraus leveler audiobook.wav --target -20dB --amount 30% -o level.wav

Options

Flag	Type	Default	Meaning
`--target`	gain	`-18dB`	Target RMS level in dBFS
`--amount`	percent	`50%`	How far to move toward the target, in percent (100% levels fully)
`--range`	gain	`-50dB`	Level (dBFS RMS) below which signals count as low-level and are not boosted
`--boost-low`	on\|off	`off`	Also level signals between --gate and --range (on\|off)
`--gate`	gain	`-60dB`	Noise floor in dBFS RMS: below it the gain is frozen and never boosts
`--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.
Percentages accept 80% or the fraction 0.8; a bare 80 means 80x, not 80%.
Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

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

{"command": "leveler", "defaults": {"target": "-18dB", "amount": "50%", "range": "-50dB", "boost_low": "off", "gate": "-60dB", "mix": "100%"}}