Cue Types Reference¶
Studio supports 10 cue types. Each row in a cue list is one cue, of one type. Use this reference to pick the right type for what you're trying to do.
All cues share these common fields:
- Number — the display number (1.0, 2.5, etc.) — sortable, can be hand-edited
- Name — human-readable label
- Type — one of the 10 below
- Duration — text in seconds (e.g. 5.00)
- Pre-Wait — pause before firing
- Mode — MANUAL (operator presses GO), AUTO (auto-advance after duration), AUTO-FOLLOW (fire then immediately advance to next)
The type-specific fields below are what changes between cue types.
GO cue¶
What it does: Nothing. It's a manual stop point. The operator presses GO, the cue "fires" (logs a notification), and the pointer advances.
Use it for: - A pause point in the show ("wait for actor to enter") - Visually grouping a section without grouping mechanically - A documentation marker — "Scene 2 begins here"
Type-specific fields: none.
At runtime: logs Cue X.X — GO and advances. Doesn't drive any hardware.
Group cue¶
What it does: Visually groups subsequent cues. In v0.1.0, it's purely organizational — it doesn't programmatically nest cues into a runnable group.
Use it for: - Section headers in the cue list ("Act I", "Climax", "Curtain") - Visual hierarchy when the cue list gets long
Type-specific fields: none beyond the shared ones.
At runtime: logs that the group fired. Doesn't iterate child cues. (Group semantics are deferred to a later schema version.)
Audio cue¶
What it does: Tells an audio compute node to start playing a file.
Type-specific fields:
- File — filename relative to the audio Node's mediaDir (e.g. thunder.wav)
- Node — which audio Node to play on; pick from your defined audio nodes
Use it for: any sound effect, music cue, voiceover.
At runtime (v0.1.0): logs the intended action. v0.2 will actually call the Node.
Common gotchas:
- Filename is case-sensitive at the Node (Linux). Thunder.wav ≠ thunder.wav.
- The audio file must exist on the Node before showtime — designer hands media files to venue tech, who pushes them via rsync.
- Volume defaults to a Node-side default. To set it per-cue, edit the cue inspector's volume field if exposed (in v0.1.0 the cue uses Node-side default volume; per-cue volume is a v0.2 feature).
Video cue¶
What it does: Tells a video compute node to play a file fullscreen on its HDMI output.
Type-specific fields:
- File — filename relative to the video Node's mediaDir
- Node — which video Node to play on
Use it for: any fullscreen video — backgrounds, intros, "still" images held during a scene.
At runtime (v0.1.0): logs intent. v0.2 calls the Node.
Common gotchas: - Node video decode supports H.264 and HEVC well; less common formats may stutter. - 4K video on Node needs the 8 GB model and good cooling. Test before showtime. - Configured automatically — no setup needed on the Node side.
DMX cue¶
What it does: Fires a Lighting Look. The look's keyframes are interpolated and DMX values are sent on universe 1.
Type-specific fields: - Look — pick from any room's authored Lighting Looks
Use it for: any lighting state change.
At runtime: Runtime sends sACN packets at 30 Hz with the interpolated values.
Common gotchas: - A DMX cue with no Look assigned is a no-op. Validator warns on this. - Multiple DMX cues firing simultaneously will overlap — last-write-wins on each channel. If two cues target the same fixtures, the second one's values overwrite the first. - If your fixtures listen on a universe other than 1, edit the Node-side or fixture-side configuration. Studio doesn't yet support universe routing.
GPIO cue¶
What it does: Drives a relay or signal pin on a GPIO Node.
Type-specific fields:
- Node — which GPIO Node
- Channel — channel name (e.g. gp1, gp4) — these map to BCM pins in the Node's config
- Action — pulse (briefly high), set (high indefinitely), clear (low)
Use it for: - Door locks (pulse to unlock briefly) - Triggering effects (pulse a fog machine controller) - Holding states (set the "showtime" indicator high until intermission)
At runtime: Runtime POSTs to the Node at http://<node-ip>/gpio/<channel> with the action.
Common gotchas:
- Channel names must match what's in the Node's config. Default Node config uses gp1..gp7. If venue tech changed it, your channel name must change to match.
- Pulse defaults to 250 ms. Some relays need longer to actually engage. Set the cue's dur accordingly.
- set doesn't auto-clear. If you want the pin to go back low later, fire a separate cue with action clear.
Fade cue¶
What it does (v0.1.0): Placeholder. It holds for its duration and advances. The "fade curve" field is recorded but doesn't fade anything.
Use it for (today): as a wait with semantic intent. Documents "we're fading here" even if Runtime doesn't yet.
Type-specific fields:
- Curve — linear, ease-in, ease-out, ease-inout
At runtime (v0.1.0): logs "fade placeholder" and waits its duration.
Future (v0.2+): Fade between two looks, or fade audio volume, or fade video opacity. Semantic TBD.
TC cue (Timecode)¶
What it does: Drives the show's timecode transport.
Type-specific fields:
- Action — start, stop, goto
- Goto MS — for goto action only; jump to this offset in milliseconds
Use it for: - Starting the show clock at curtain rise - Stopping the clock at intermission - Jumping to a specific time in a timeline-driven section
At runtime: drives Runtime's TC counter; affects timeline clip playback (in v0.2).
Wait cue¶
What it does: Pauses the cue list for the cue's duration.
Use it for:
- Built-in pacing ("hold for 3 seconds before next cue")
- Cues that are intentionally paced even in AUTO mode
Type-specific fields: none beyond the shared duration.
At runtime: logs and waits.
Note on modes: A wait in MANUAL mode is moot — the operator presses GO when ready, regardless of duration. A wait in AUTO mode auto-advances after the duration; this is where waits earn their keep.
Trigger cue¶
What it does: Fires a logic graph node. Runtime walks the graph from that trigger and fires every connected node.
Type-specific fields: - Trigger — pick from the room's logic trigger nodes
Use it for: - Effects that combine multiple actions ("door slam" = audio + GPIO + DMX flash) - Conditional branches (when conditions are implemented in v0.2+) - Delayed sequences (trigger → delay → DMX, in v0.2)
At runtime: breadth-first walk from the trigger, applying side effects on each connected node.
Common gotchas: - The logic graph and the trigger must be in the same room. Cross-room triggers aren't supported in v0.1.0. - Trigger cues are powerful — a single GO can fire dozens of side effects. Test thoroughly. - If a logic graph has cycles, Runtime breaks them with a visited-set. Cycles still won't behave like loops; they just stop after each node fires once.
Picking the right cue type¶
| You want to… | Use |
|---|---|
| Pause the show until operator presses GO | GO cue |
| Make the cue list more readable | GROUP cue |
| Play a sound | AUDIO cue |
| Play a video | VIDEO cue |
| Change the lights | DMX cue |
| Fire a relay / unlock a door | GPIO cue |
| Document a fade visually but don't actually fade (v0.1.0) | FADE cue |
| Start/stop the show clock | TC cue |
| Insert a timed pause in AUTO mode | WAIT cue |
| Fire multiple things at once | TRIGGER cue + logic graph |
When in doubt, use a TRIGGER cue and a logic graph — that gives you the most flexibility for combining behaviors.