ferraus normalize

Set loudness (LUFS), peak, or RMS level to a target

Synopsis

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

Measures the input and applies the gain that lands it on the target. The default mode is integrated loudness per EBU R128 (--lufs -14, the usual streaming level). --peak -1dBTP normalizes the true (inter-sample, 4x oversampled) peak and --peak -1dB the sample peak; --rms -20dB the average level. Give one mode only. For --lufs and --rms, if the gain pushes the true peak over --ceiling a transparent lookahead true-peak limiter holds it under the ceiling (--true-peak-limit off disables that). Several inputs are normalized one by one to the same target (Match Loudness). Before and after measurements are reported as metrics.

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

Examples

Integrated loudness to -14 LUFS, true peak at most -1 dBTP

ferraus normalize song.wav -o song_streaming.wav

Match a batch of tracks to -16 LUFS

ferraus normalize ep/*.wav --lufs -16 --outdir matched/

Sample peak to -0.1 dBFS

ferraus normalize sample.wav --peak -0.1dB -o sample_max.wav

Broadcast loudness with a -2 dBTP ceiling and a JSON report

ferraus normalize vo.wav --lufs -23 --ceiling -2dBTP --json

Options

Flag	Type	Default	Meaning
`--lufs`	gain	`-14`	Integrated loudness target in LUFS (default mode), e.g. -14, -16, -23
`--peak`	gain	—	Peak target: -1dBTP for true peak, -1dB for sample peak
`--rms`	gain	—	RMS level target in dBFS, e.g. -20dB
`--true-peak-limit`	on\|off	`on`	With --lufs/--rms: limit inter-sample peaks to --ceiling after the gain
`--ceiling`	gain	`-1dBTP`	True-peak ceiling in dBTP for the limiter
`--lookahead`	time	`3ms`	Limiter lookahead (attack) duration
`--release`	time	`80ms`	Limiter release time constant (duration)
`--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
9	Output verification failed (checksum, clipping guard, duration mismatch)
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_normalize
Schema: ferraus schema normalize
Pipeline: { op: normalize, args: { ... } } (flag names with _ instead of -)
fx stage: yes

{"command": "normalize", "defaults": {"lufs": "-14", "true_peak_limit": "on", "ceiling": "-1dBTP", "lookahead": "3ms", "release": "80ms", "mix": "100%"}}