ferraus plugin run

Run an effect plugin over audio

Synopsis

ferraus plugin run <input> [options] [-o <output>]

Processes the input through an effect plugin in a separate host process, offline in fixed blocks. The plugin's reported latency is compensated so every sample stays at its original position; --tail keeps processing after the input ends so reverbs and delays can ring out. The resolved parameters, preset, and native state are written to the sidecar so the run can be reproduced.

Examples

Add 30% room reverb and let it ring for 3 s

ferraus plugin run vocal.wav --plugin "Dragonfly Room Reverb" --tail 3s --mix 30% -o vocal.verb.wav

Set parameters in display units

ferraus plugin run in.wav --plugin com.acme.eq --param "Low Gain=-3dB" --param cutoff=2.5kHz -o out.wav

Restore a saved state, then load a preset, and process a guitar

ferraus plugin run guitar.wav --plugin "Surge XT Effects" --preset "Clean Chorus" --state fx.state.json -o guitar.fx.wav

Options

Flag	Type	Default	Meaning
`--plugin`	text	—	Plugin name, id, or path to a .clap/.vst3 bundle (required)
`--param`	text	—	Set a parameter: name=value, by display name or stable id; value in display units (cutoff=2.5kHz, mix=30%, gain=-6dB) or normalized (norm:0.3) Repeatable.
`--preset`	text	—	Load one of the plugin's presets by name (see 'plugin presets list') before applying --param values
`--state`	path	—	Restore native plugin state from a file written by 'plugin state save' (or a sidecar) before the preset and --param values
`--tail`	time	—	Extra time to process after the input ends (e.g. 2s); default auto: the plugin's reported tail, or 2s when it reports none
`--block-size`	integer	`512`	Processing block size in samples Range: 16..16384.
`--mix`	percent	`100%`	Dry/wet balance: 0% returns the input unchanged, 100% is fully processed
`--watchdog`	time	—	Stop the plugin host after this long without progress (default 60s, or FERRAUS_PLUGIN_WATCHDOG_S)

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
7	Plugin crashed, timed out, or was not found
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%.

For models

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

{"command": "plugin run", "defaults": {"block_size": "512", "mix": "100%"}}