Getting Started with IMMERSE Studio¶

A 30-minute walkthrough that takes you from "I just installed it" to "I have a show file ready to hand to the venue tech."

Install¶

Windows¶

Download IMMERSE-Studio-v0.1.0.zip
Unzip anywhere (Desktop is fine)
Double-click START.bat
First run: it installs Node.js dependencies (~2 minutes). Subsequent runs skip this.
Studio opens

macOS / Linux¶

Download the appropriate installer (DMG / AppImage / .deb)
Or run from source: cd immerse-designer && npm install && npm start

The first time you launch, you'll see a Welcome dialog explaining what Studio is and isn't. Read it.

Tour the interface¶

When Studio opens, you'll see:

┌─────────────────────────────────────────────────────────────┐
│  File  Edit  Devices  View  Help                            │  ← menu bar
├──────────────────┬───────────────────┬──────────────────────┤
│                  │                   │                      │
│  Sidebar         │  Module area      │  Inspector           │
│  - Scene tree    │  (whichever       │  (properties of      │
│  - Fleet         │   module is       │   the selected       │
│  - Devices       │   active)         │   thing)             │
│  - Cues          │                   │                      │
│                  │                   │                      │
└──────────────────┴───────────────────┴──────────────────────┘
│ TC display · STOPPED · Show: Untitled Show                  │  ← status bar
└─────────────────────────────────────────────────────────────┘

The 9 module tabs across the top of the module area:

Room (Ctrl+1) — floor plan, drag-and-drop devices
Nodes (Ctrl+2) — audio/video/GPIO/DMX compute nodes
Patcher (Ctrl+3) — wire device ports to node channels
Logic (Ctrl+4) — visual scripting graph
Cue List (Ctrl+5) — ordered sequence of cues
Timeline (Ctrl+6) — TC-driven clip playback
Op. UI (Ctrl+7) — placeholder; coming in v1.1
Validator (Ctrl+8) — show-wide error/warning report
Lighting Looks (Ctrl+9) — DMX scene editor

Press ? at any time to see all keyboard shortcuts.

Build your first show¶

We'll author a simple 1-room "haunted hallway" scene. Should take 15-20 minutes.

1. Create the show¶

File → New (Ctrl+N). You get an empty show with one room.

In the sidebar's Scene Tree: - Click the show name (default: "Untitled Show") to select it - In the Inspector, rename it to "Haunted Hallway Demo"

2. Add a room¶

The default show has one room called "Main Room". Rename it to "Hallway": - Click the room in the Scene Tree - Inspector → Name → "Hallway"

3. Add some compute nodes¶

Switch to Nodes module (Ctrl+2). You'll see the venue's compute nodes — the Nodes that will drive hardware.

Click + Audio in the toolbar. A new node aud-1 appears. - Inspector → Name: "Hallway Speaker Node" - Inspector → IP: 10.0.0.12 (placeholder — venue tech will tell you the real IP)

Click + Video. Node vid-1. - Name: "Hallway Screen Node" - IP: 10.0.0.13

Click + GPIO. Node gpio-1. - Name: "Effects Node" - IP: 10.0.0.14

Click + DMX. Node dmx-1. - Name: "Lighting" - IP: 10.0.0.15

(In a real venue, the tech will tell you the actual IPs and how many of each role exist.)

4. Author a Lighting Look¶

Switch to Lighting Looks (Ctrl+9). Click + Look. Rename to "Sunrise".

Set the duration to 3000 ms (3 seconds).

In the keyframe editor, click + Keyframe at 0ms. A row appears. - Add a value: device dev-1, channel ch-1, value 0 - Add another: dev-1 ch-2 value 64

Click + Keyframe at 3000ms. - dev-1 ch-1 value 255 - dev-1 ch-2 value 255

When the Sunrise look fires, slot 1 ramps from 0 to 255 over 3 seconds; slot 2 ramps from 64 to 255.

(Channel addressing in v0.1.0 is simple: ch-N becomes universe 1 slot N. Multi-universe addressing is a v0.2 feature.)

5. Build the cue list¶

Switch to Cue List (Ctrl+5). The default room has an empty cue list called "Cue List A".

Open the Cue Library in the sidebar (4^th tab, "Cues"). You'll see 10 cue type tiles.

Drag the GO tile into the cue list. Cue 1.0 appears. - Inspector → Name: "House to half"

Drag the DMX tile into the list, dropping below cue 1. - Cue 2.0 appears. - Inspector → Name: "Sunrise lights up" - Inspector → Look: "Sunrise" (your earlier-authored look) - Duration: 3.00

Drag the Audio tile in. - Name: "Distant footsteps" - Audio Node: "Hallway Speaker Node (aud-1)" - File: footsteps.wav - Duration: 5.00

Drag the Wait tile in. - Duration: 2.00 — pauses the sequence

Drag the GPIO tile in. - Name: "Door slam effect" - GPIO Node: "Effects Node (gpio-1)" - Channel: gp1 - Action: pulse

Drag the Trigger tile in. - Name: "End scene" - We'll come back to this in step 7.

Press Ctrl+S, save as haunted-hallway.ishow.

6. Test the cues¶

In the cue list, double-click cue 1 (the GO cue). A notification flashes: "GO — Cue 1.0 House to half". This is Studio's "fire" preview — it doesn't actually fire hardware (because Studio isn't connected to the venue), but it confirms the cue is configured.

Double-click each subsequent cue. Each will preview-fire and tell you what would happen at runtime.

The big ■ GO button at the top of the cue list fires the next cue and advances the pointer. Press it 5 or 6 times to walk through the show.

7. Add a Logic Graph¶

Switch to Logic (Ctrl+4). The graph is empty.

In the toolbar, click + Trigger. A trigger node appears. - Inspector → Label: "End scene trigger"

Click + DMX. A DMX logic node. - Label: "Blackout" - Look: leave blank for now (or create a "Blackout" look in Lighting Looks)

Click + Transport. A transport node. - Label: "Stop TC" - Action: stop

Now wire them. Click and drag from the trigger node's output port (right side) to the DMX node's input port (left side). A wire appears.

Drag from the trigger node's output to the transport node's input.

Now the trigger has two children: when the trigger fires, both the DMX blackout and the transport-stop fire.

Go back to the Cue List. Click cue 6 (the Trigger cue you added earlier). In the Inspector, set Trigger → "End scene trigger" (the one you just created).

When cue 6 fires, the logic graph runs: trigger → blackout + transport-stop.

8. Validate¶

Switch to Validator (Ctrl+8). Studio reports any broken references in the show.

Common warnings at this stage: - "Audio cue 3.0 references missing node aud-1" — your nodeId might not match. Check the Audio cue's node assignment. - "Lighting look has no keyframes" — informational; you might have a placeholder look.

Fix anything red. Yellow warnings are OK to ignore but worth understanding. The page will show a green checkmark "No issues found" when everything's clean.

9. Save and prepare for handoff¶

Ctrl+S saves. Now organize the handoff folder:

haunted-hallway/
├── haunted-hallway.ishow         ← what you just saved
├── media/
│   ├── audio/
│   │   └── footsteps.wav         ← provide the actual file
│   └── video/                    ← empty if no video cues
└── handoff-notes.md              ← anything the tech needs to know

Hand this folder to the venue tech. They'll install Runtime, push the media to the right Pis, and run the show.

What just happened, conceptually¶

You authored: - 1 show with 1 room - 4 compute nodes (audio / video / GPIO / DMX placeholders) - 1 lighting look with 2 keyframes - 6 cues across 5 cue types - 1 logic graph with 1 trigger and 2 effects

The .ishow file contains all of this. It's about 8 KB of JSON.

When the venue tech runs Runtime with this file: - Operator presses GO at house close → "House to half" fires (does nothing real; it's a beat) - Operator presses GO → DMX cue fires Sunrise look → universe 1 slots 1&2 ramp up over 3 seconds - Operator presses GO → audio cue tells the audio Node to play footsteps.wav through the speakers - Operator presses GO → 2-second wait — operator can wait or press GO to skip - Operator presses GO → GPIO cue tells the GPIO Node to pulse pin gp1 — relay clicks → door slam SFX - Operator presses GO → trigger cue fires the logic graph → blackout + TC stop

That's a complete, runnable cue sequence in 20 minutes.

Next steps¶

Now that you've built one, see: - cue-types-reference.md for all 10 cue types and their fields - lighting-looks.md for sophisticated DMX authoring - logic-graphs.md for more complex logic patterns - common-mistakes.md to skip over the bear traps