ferraus render

Render MIDI to audio with an instrument

Synopsis

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

Plays a MIDI file through a SoundFont (sf2, via the pure-Rust rustysynth engine), an SFZ library (native sampler), or the built-in preview synth, which needs no files, so render always works. --instrument takes a name resolved in this order: a 'sounds alias', an installed or --sound-path sound whose name or category matches (strings, nylon guitar), a General MIDI program name or number ("String Ensemble 1", gm:48) played by the gm-basic soundfont if installed or else the built-in synth, or an explicit source (sf2:<path>[@bank:program], sfz:<path>, builtin:<timbre>, plugin:"Name"). The default, gm, follows the file's own program changes. The output is the MIDI length plus --tail; the resolved instrument is recorded in the sidecar.

Examples

Render with a piano (installed piano sound, gm-basic, or the built-in synth)

ferraus render part.mid -o part.wav --instrument piano

Different instruments per track or channel

ferraus render song.mid --map "1=piano,2=strings,10=drums" -o song.wav

Replace every piano-family part with strings

ferraus render song.mid --swap piano=strings -o strings.wav

General MIDI program by name, longer tail, reverb in the same run

ferraus render idea.mid --instrument "String Ensemble 1" --tail 3s --fx "reverb:mix=0.2" -o idea.wav

Options

Flag	Type	Default	Meaning
`--instrument`	text	`gm`	Instrument name or source: piano, strings, "String Ensemble 1", gm:48, sf2:<path>, sfz:<path>, builtin:organ, plugin:"Surge XT"; gm follows the file's programs
`--map`	list	—	Instruments per track or channel: "1=piano,2=strings,10=drums" (t2= forces a track, ch10= a channel; bare numbers are tracks in multitrack files, else channels) Repeatable.
`--swap`	list	—	Substitute by General MIDI family: piano=strings plays every piano-family channel with strings Repeatable.
`--tail`	time	`2s`	Time rendered after the last MIDI event so releases ring out (2s)
`--velocity-curve`	linear \| soft \| hard	`linear`	Velocity response: soft makes quiet notes louder, hard needs more velocity to get loud
`--fx`	text	—	Effect stage applied after rendering, like the fx command: "reverb:mix=0.2" (repeatable, in order) Repeatable.

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
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.

For models

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

{"command": "render", "defaults": {"instrument": "gm", "tail": "2s", "velocity_curve": "linear"}}