Concepts

Stagewright has a small vocabulary. Once these five terms click, the rest of the app reads itself.

Project

The top-level container: a single .swproj JSON file on your disk. Holds every rack, the active script, audio device selection, MIDI device bindings. Sync via git / Dropbox / USB stick. See Project format.

Rack

A wired graph of audio + MIDI + plugin nodes, plus the stage layout that performs it. One project can hold many racks, you might have a Live Rig, a Studio Practice, a Drum Machine Standalone. The active rack is the one whose audio engine is running.

In v1 racks are independent. There is no shared-resource pool across racks (the "rackspaces" model used by some other similar products in this space). Each rack hydrates from disk when it's activated; the previous rack tears down. Crossfade-on-switch is planned for a future release, not in v1.

Variation

A snapshot of parameter values within a single rack, same graph, different parameter settings. Use variations to switch a piano patch from "bright stage" to "warm intimate" without rebuilding wires.

Variation vs Rack

A variation changes parameter values inside the same rack. A rack is a fully different patch with potentially different plugins. Mid-set you swap variations; between sets you swap racks.

Song & Setlist

A Song is an instant value snapshot of a rack: per-card bypass states, plugin parameters, and mixer/mute values captured together and recalled in milliseconds with no reload. Recalling a song overlays its values onto the live rack (switching racks first if the song belongs to a different one). Songs are stored in the project file and can be recalled from the UI, the LAN remote, or a MIDI Program Change. Each song can carry ChordPro lyrics.

A Setlist is an ordered list of songs (which may span racks). You author setlists in the Set view, whose display mode drives the on-stage lyrics view, and a slim song strip shows your position in the set across every view.

No "song parts" in v1

Recall happens at the whole-song level. There is no sub-song "part" unit in v1. ChordPro verse and chorus sections exist as lyric formatting within a song, not as separate recall points.

Widget

The stage atoms. Knobs, faders, buttons, toggles, meters, labels, panels, the tuner, the metronome. Every widget can be bound to a destination:

• A plugin parameter, turning the knob writes to that parameter.
• A plugin bypass, flipping the toggle bypasses the plugin.
• A mixer peak, meter widgets follow a Channel Mixer strip's post-fader peak.
• A tuner / metronome node, read-only display widgets mirroring a Wiring-canvas Tuner / Metronome card.
• Nothing, the widget is purely script-driven (a panel-only LED that your script lights when the rack is ready).

Widgets are addressable by name from the script (widget('PIANO_VOL')) so the same widget can be touched by mouse, hardware MIDI, OSC, and script logic interchangeably.

How they fit

Project (.swproj)
├── Rack A
│   ├── Blueprint   (nodes + cables)
│   ├── Performer   (widgets bound to nodes)
│   └── Variations  (parameter snapshots)
├── Rack B
│   └── …
└── Script  (one TypeScript file, project-scoped)

Audio devices and MIDI device bindings are project-scoped too (one project = one rig configuration). The script is project- scoped, same script across racks, hook into rack-switch events to react.

Hardware abstraction

Inside a project you address controllers by logical name, not by USB port. Your script reads midi.input('Keyboard') and the project maps that to whichever physical keyboard is plugged in tonight. Compose at home on a 49-key controller; play at a venue on the 88-key stage rig, the patch doesn't care.

Mappings live in the project file alongside the audio device selection. Edit them in the Wiring canvas by setting the device on each midi-in card.