ferraus envelope

Keyframed automation of gain, pan, or pitch

Synopsis

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

What it does

Draws an automation curve through 'time=value' keyframes (times as 2s, 1:30, 4b, end, or -5s from the end) and applies it: gain in dB (interpolated in dB), pan from -100 (left) to 100 (right) or L30/R60/center (a mono input becomes stereo with a constant-power -3 dB law; a stereo input is balanced), or pitch in cents (duration-preserving granular shift; good for speech and monophonic lines, rougher on dense mixes). Values hold before the first and after the last keyframe; keyframes are hit sample-accurately.

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

Examples

A one-second fade in, then unity gain

ferraus envelope in.wav --points 0s=-60dB,1s=0dB,end=0dB -o faded-in.wav

Sweep a mono source from left to right

ferraus envelope mono.wav --target pan --points 0s=-100,4s=100 --curve spline -o sweep.wav

Bend up a semitone and back

ferraus envelope vox.wav --target pitch --points 0s=0,2s=+100cents,4s=0 -o bend.wav

Options

Global options

Every command also accepts the global options (-o, --json, --dry-run, --overwrite, --progress, ...). See Global options.

Exit codes

Common mistakes

• Forgetting that outputs are never overwritten: pass --overwrite or a new -o path when re-running.

For models

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

{"command": "envelope", "defaults": {"points": "0s=0dB,2s=-6dB,end=-60dB", "curve": "linear", "target": "gain", "mix": "100%"}}