ferraus mix

Sum several files with per-input gain, pan, and offset

Synopsis

ferraus mix <inputs...> [options] [-o <output>]

Adds the inputs together. --gains, --pans, and --offsets are comma lists with one value per input, in input order (missing values mean 0 dB, unpanned, and no offset). Pans run from -100 (hard left) to +100 (hard right) on a constant-power -3 dB law: a mono source panned to the centre sits 3 dB down on each side; a stereo source is balanced (its far side is turned down). Inputs are resampled to the first file's rate. The result lasts as long as the longest input including its offset. The sum is not normalized unless --normalize peak; a warning is raised if it clips.

Examples

Lay a vocal over a beat, beat 4 dB down

ferraus mix vocal.wav beat.wav --gains 0dB,-4dB -o demo.wav

Rough mix: vocal centred, guitar left, keys right

ferraus mix vox.wav gtr.wav keys.wav --gains 0dB,-3dB,-6dB --pans 0,-40,+40 -o rough.wav

Drop a sting in at 12.5 s and peak-normalize the sum

ferraus mix music.wav sting.wav --offsets 0s,12.5s --normalize peak -o promo.wav

Options

Flag	Type	Default	Meaning
`--gains`	list	—	Gain per input in dB or as a factor, e.g. 0dB,-3dB,0.5x
`--pans`	list	—	Pan per input from -100 (left) to +100 (right), e.g. 0,-40,+40
`--offsets`	list	—	Start time per input (duration), e.g. 0s,1.5s,4b
`--normalize`	off \| peak	`off`	peak: scale the sum so its sample peak sits at --ceiling
`--ceiling`	gain	`-1dB`	Peak level (dBFS) used by --normalize peak

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.
Gains need a unit when not in dB: 0.5x is a factor, -6 and -6dB are decibels.

For models

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

{"command": "mix", "defaults": {"normalize": "off", "ceiling": "-1dB"}}