Racks, variations, songs

Racks

A rack is a complete wired graph + stage layout that can be activated and torn down as a unit. One project holds many racks , "Live Rig", "Studio Practice", "Synth Standalone", and the active rack is the one whose audio engine is running.

Switching racks tears down the old rack's plugins, hydrates the new rack's plugins (including their saved state), re-applies its performer layout, and resumes audio. In v1 this is a hard switch (audio drops for ~100-300ms). Crossfade-on-switch is on the v2 roadmap.

Rack-switch hooks:

• onActivate(rackName) fires AFTER the new rack is audible, and onDeactivate(rackName) fires just before the old rack is torn down. Both receive the rack's display name. Use onActivate to re-emit LED feedback to controllers (LEDs reset on each rack), refresh rack-specific state your script holds, and log into Diagnostics so future-you knows why a setting changed.
• The rack picker in the top toolbar's right side switches racks manually. There is no script API to switch racks in v1.

Variations

A variation is a snapshot of parameter values WITHIN a rack, same graph, different settings. Variations are perfect for "this song wants the piano patch bright, that song wants it warm" without changing the actual wiring or stage layout.

Each variation captures every plugin parameter + every widget position. Switching variations applies the snapshot to all bound parameters without re-instantiating plugins (so it's fast and audio-continuous, no drop).

Variation-switch hooks:

• There is no dedicated script hook for variation changes in v1. React to the parameter and widget movement a variation causes with widget(name).on('change', ...), or to rack activation with onActivate / onDeactivate.

Songs & setlists

Songs and setlists ship in v1 and are stored in the project file alongside racks and variations.

• A song is an instant value snapshot of a rack: per-card bypass, plugin parameters, and mixer/mute values, recalled in milliseconds with no reload. Recalling overlays the song's values onto the live rack (switching racks first if needed). Each song can carry ChordPro lyrics.
• A setlist is an ordered list of songs and may span racks.
• Songs and setlists persist in the project file (v4 schema) and are authored in the Set view.

A foot-controller's Program Change messages recall songs directly. This is a native engine binding (Program Change maps to a song index), not a script hook, so it works without any script. The script runtime does not receive program-change messages, see MIDI → Program Change and songs.

There is no "song part" sub-unit in v1, recall operates at the whole- song level.

Hardware abstraction within / across racks

Audio device + MIDI device bindings are project-scoped, not rack-scoped, one project = one rig configuration. Bring the project to a different rig:

1. Open the project on the new machine.
2. The engine warns about unmatched device names (e.g. "MIDI Mix not found").
3. In the Wiring-view inspector for each midi-in card, pick the correct device from the dropdown.
4. Save. The project now plays on this rig.

The script doesn't change, it addresses by logical name. The bindings, wires, widget layouts also don't change.