truce-rack-standalone 1.1.5

cpal-driven standalone host for truce-rack (one plugin in, audio device out)
Documentation

truce-rack-standalone

crates.io docs.rs

Reference standalone host for the truce-rack audio plugin framework. cpal for the audio device, midir for hardware MIDI input, optional baseview window with the plugin's editor embedded as a child. Ships two binaries:

  • truce-rack-standalone — load one plugin, render through the default output device. With --gui opens the plugin's editor; headless otherwise.
  • truce-rack-screenshot — walk every installed plugin and capture its editor to a PNG (macOS only).

Quick start

# Scan everything every enabled format scanner can find.
cargo run --bin truce-rack-standalone --features "gui,vst3,au,au3,lv2" -- --list

# Load a plugin by name. On a `gui` build the editor opens by
# default; pass --headless to run without a window (or --seconds N).
cargo run --bin truce-rack-standalone --features "gui,vst3,au" -- --format vst3 --name "Surge XT"

# Drive a tempo/grid-synced plugin with a synthesized transport.
cargo run --bin truce-rack-standalone --features "gui,vst3" -- --format vst3 --name "Surge XT" --tempo 140 --time-sig 7/8

Default features are clap only; opt in to vst3, au, au3, lv2 as needed. The gui feature pulls baseview + the QWERTY keyboard MIDI handler. Linux gates gui off (baseview drags wayland-sys); the headless path works there. On a gui build the editor opens by default — pass --headless to suppress it.

Audio device & channels

Playback goes to cpal's default output device at its native rate unless you override it:

Flag Meaning
--list-devices List audio output + input devices and exit
--output <name> Output device (case-insensitive substring)
--output-channels <spec> direct (all, default), a channel like 3, or a pair 3-4
--sample-rate <hz> Output sample rate (falls back if unsupported)
--buffer <frames> Audio buffer size in frames

--output-channels lets a stereo plugin land on, say, outputs 3-4 of a multichannel interface (3 folds it down to a single output). The rack host is output-only, so there's no input-device selection.

MIDI input

Every visible MIDI input port is opened at startup. Narrow that with --list-midi (print ports and exit), --midi-input <name> (open only ports matching a substring), and --midi-channel <spec> (omni/all, the default, or a channel 1-16 — channel-voice messages on other channels are dropped; clock/sysex always pass).

Live menu (macOS)

In the windowed runner (--gui) on macOS, a native Settings menu switches the output device, output channel routing, MIDI input port, and MIDI channel filter live — the same choices as the CLI flags above, but changeable while the plugin runs. Device / port lists repopulate each time a submenu opens.

Host transport

There's no DAW timeline behind the runner, so it synthesizes one and passes it to the plugin every block — each format wrapper maps it to its native transport (VST3 ProcessContext, CLAP clap_event_transport, LV2 time:Position, AU host callbacks). Control it with:

Flag Default Meaning
--tempo <bpm> 120 Transport tempo in BPM
--time-sig <n/d> 4/4 Time signature, e.g. 7/8
--paused rolling Report transport stopped (song position frozen)
--no-transport off Report no transport at all (transport == None)
--seconds <n> — Run headless for n seconds, then exit

Companion crates

Per-format wrapper crates this binary dispatches to:

License

MIT or Apache-2.0, at your option.