Skip to content

For Designers

You're using IMMERSE Studio to author shows. These docs walk you through the tool and the concepts behind it.

Read in order if you're new

  1. getting-started.md — Install Studio, build your first show, save it
  2. cue-types-reference.md — All 10 cue types and when to use each
  3. lighting-looks.md — Authoring DMX scenes with keyframes
  4. logic-graphs.md — How trigger → transport → DMX flows work
  5. validator.md — What the green checkmark means (and what it doesn't)
  6. common-mistakes.md — Pitfalls that will bite you

What Studio is, in one paragraph

IMMERSE Studio is the authoring side of a two-piece show control platform. You design rooms, devices, lighting looks, cue lists, and timelines. You save as .ishow. The file gets handed to IMMERSE Runtime — a separate program running on a venue PC — which actually plays the show on real hardware. Studio doesn't drive any hardware itself. The Fire ▶ buttons are previews / sanity checks; they emit notifications describing what would happen at runtime.

What you can build

  • Rooms — physical spaces with floor plans
  • Devices — speakers, lights, screens, buttons placed on the floor plan
  • Compute Nodes — the audio/video/GPIO/DMX nodes that drive devices
  • Patches — wiring between device ports and node channels
  • Lighting Looks — keyframed DMX scenes (color, intensity, position over time)
  • Cue Lists — ordered sequences of 10 cue types
  • Timelines — TC-driven clip playback with multiple tracks
  • Logic Graphs — visual scripting (when X happens, fire Y)

What you can't build (yet)

  • Operator UI — the touchscreen panel for the show operator. Coming in v1.1.
  • Custom cue types — limited to the 10 built-in types
  • Plugins — no extension API
  • Multi-show projects — one .ishow per show. To share assets across shows, copy/paste in Studio or hand-edit JSON.
  • Live show monitoring — Studio can't connect to a running Runtime to see what's currently firing. Different tool, different audience.

Working file format

Studio reads and writes .ishow files. These are JSON, schema 0.5.0. Plain text. You can: - Open one in a text editor to inspect - Diff two versions in git to see what changed - Hand-edit in emergencies (with caution)

The full schema is documented in ../for-developers/ishow-schema.md if you ever need it.

Working with files

Use Save As (Ctrl+Shift+S) the first time. Subsequent Save (Ctrl+S) writes back to the same path.

Studio creates backup .ishow.bak files in the same folder when you save — recover from these if your main file gets corrupted.

Pick a folder structure that you'll thank yourself for later:

shows/
├── halloween-2026/
│   ├── halloween-2026.ishow            ← the show file
│   ├── halloween-2026.ishow.bak
│   ├── media/
│   │   ├── audio/                      ← audio files referenced in cues
│   │   └── video/                      ← video files
│   ├── docs/
│   │   └── design-notes.md
│   └── README.md                       ← what this show is, who it's for
└── opening-night-2026/
    └── ...

This way the venue tech receives a single folder containing everything needed.

Workflow

A typical authoring session: 1. Open Studio 2. Open the show file (or start a new one) 3. Make changes 4. Press Ctrl+8 to validate — fix anything red before saving 5. Save (Ctrl+S) 6. Test by Fire ▶ -ing key cues to verify the configuration 7. Hand off to the venue tech with the media folder

You will NOT do this in Studio: - Test against real hardware (Studio is offline-only) - Time the show against actual stage performance (Studio's TC is a counter, not synced to anything) - See what the lights actually look like (Studio shows look authoring, not real-world output)

For all of those, you need the venue with Runtime + nodes set up.

When to involve the venue tech

Early. The schema is shared between Studio and Runtime; if the venue uses an older Runtime that doesn't support a feature you authored, the show won't load. Coordinate versions before you start authoring.

Also early on questions like: - "What's the right nodeId for the audio Node in room 2?" — they assigned the IDs - "Can we add a video screen in the lobby?" — they have to install hardware - "I want a fade between two looks — does Runtime support that?" — Fade is a v0.1.0 placeholder

Mental model

Think of Studio as writing the script and Runtime as performing it. You're the playwright, not the actor. The show's quality at runtime depends on: - How well you authored the cues (your job) - How accurately the venue tech installed the hardware (their job) - How well the operator presses GO at the right moments (the operator's job)

A great show needs all three. Studio is the easiest of the three to get right — you can iterate as much as you want, save, validate, and refine. Use that.