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 front-panel 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 on the roadmap, not in v1 (see Roadmap).

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 & Song Part

Not in v1

Songs / Song Parts / Setlists / ChordPro reader are advertised on the corporate product page but are not shipped in v1. They live under the Logic panel + a future setlist view; see Roadmap for the v2 plan.

A Song is an ordered sequence of Song Parts that share a rack. Each part picks a variation (a specific sound for "verse" / "chorus" / "bridge"). A Setlist orders songs into a show.

Widget

The front-panel 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 back-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 back canvas by setting the device on each midi-in card.