Common Mistakes¶

Pitfalls that have caught designers before. Read this once. Save yourself a phone call from a venue tech at 6pm on opening night.

File and naming¶

Filename case sensitivity¶

Linux is case-sensitive. The .ishow file says Thunder.wav, the actual file on the Node is thunder.wav. The Node can't find it; cue fails silently at runtime; you blame the network.

Fix: when the designer adds an audio cue, type filenames in lowercase only, with no spaces. Use thunder.wav not Thunder.wav or Thunder Sound.wav. Tell venue tech to keep filenames lowercase.

Spaces and special characters in filenames¶

my sound.wav works in 90% of cases. The other 10% break in subtle ways during shell scripting, rsync, or path serialization.

Fix: lowercase + dashes + numbers + dots. intro-loop-v2.wav. Boring is reliable.

Forgetting to give the venue tech the media files¶

You author cues that reference thunder.wav. You hand the .ishow file off. You don't include thunder.wav because "they can find it."

Fix: always hand off the show as a folder with a media/audio/ and media/video/ subfolder containing every file referenced. The venue tech can verify by extracting filenames from the .ishow and diffing against the folder contents.

File format the Node can't decode¶

You hand off intro.mov (QuickTime). Some QuickTime variants don't play reliably on Video Nodes.

Fix: for video, use H.264 in MP4. For audio, use WAV (uncompressed) or 44.1 kHz / 16-bit MP3. These are reliable. Test on the actual Node before the show.

Channel and node references¶

nodeId mismatch with venue config¶

You author aud-1, aud-2, aud-3. Venue tech provisions the Nodes with config that says audio-1, audio-2, audio-3. Runtime tells the Node aud-1 doesn't exist; cue fails.

Fix: coordinate node IDs with the venue tech BEFORE authoring. Pick a convention (aud-1/vid-1/gpio-1 is the v0.1.0 default), tell the venue tech, and stick to it.

Channel names mismatch with Node config¶

Studio default GPIO channel names are gp1 through gp7 mapping to BCM 17/18/22/23/24/25/27. If the venue's GPIO Node has a different config (e.g. they're using a relay HAT with non-default pins), your gp1 doesn't fire what you think.

Fix: ask the venue tech for their Node config before authoring. Match channel names to their reality.

IP addresses placeholder, never updated¶

Studio lets you set arbitrary IP addresses for nodes. You set 10.0.0.10 while authoring. Venue's actual subnet is 192.168.1.0/24. The IPs are wrong.

Fix: Studio's IP fields are advisory. Runtime uses the IP from the .ishow to know where to send GPIO HTTP calls, so it does matter. Either: - Author with the real IPs the venue tech assigned (preferred) - Author with placeholders, then have the tech edit the .ishow JSON before deploying

Same nodeId twice¶

You duplicated a node and forgot to change the ID. Two aud-1 nodes. Runtime gets the first one (or the second; behavior is undefined).

Fix: validator catches this. Save and validate.

Lighting¶

Look duration mismatched with cue duration¶

Cue says "fire Sunrise look, duration 5 seconds." Sunrise look is authored to take 3 seconds. Confusion.

The cue's duration field is informational in v0.1.0 — it's used for AUTO-mode advance timing, not for constraining the look. The look plays for its own internal duration (3 seconds in this case) regardless.

Fix: match cue duration to look duration when in doubt. If you want the cue to "wait" for the look to finish before advancing in AUTO mode, set the cue duration to >= the look duration.

Two cues firing different looks on the same fixtures simultaneously¶

Cue 5 fires "warm wash". Cue 6 (right after) fires "blackout". If cue 5's look is still interpolating when cue 6 fires, the values fight. Last-write-wins on each channel.

Fix: typically what you want. If not, give cue 5's look a shorter duration so it ends before cue 6 starts.

Authored on universe 1, lights are addressed for universe 2¶

Studio outputs DMX values in v0.1.0 only on universe 1. If your fixtures are listening on universe 2 (lighting designer's call, often when there are >512 channels of fixtures), nothing receives.

Fix: ask the lighting designer what universe to author against. In v0.1.0 you may need to re-address the fixtures to listen on universe 1, OR wait for v0.2 multi-universe support.

Saturated colors, no blackout¶

Climax cue fires bright red. Next cue advances; nothing changes the lights. Audience sits in red for the rest of the show.

Fix: every saturated/dynamic look should be followed by a calmer base state cue, even if it's just "ambient". Plan the lighting state graph, not just individual moments.

Strobe at full intensity¶

Strobing a high-intensity light isn't always epileptically safe. Your fixtures support it. Your audience may not.

Fix: check epilepsy guidance for venues you target. Stay below 3 Hz at any intensity; below ~5 Hz in general.

Cues and cue lists¶

Forgetting to hand off the right `.ishow`¶

Last-minute edits in Studio. You save as final-v3-FINAL-actually-final.ishow. Hand off final-v2.ishow by mistake. Show runs the wrong version.

Fix: delete old versions before handoff. Or use a single canonical filename like current-show.ishow and rely on backup .bak files for history.

Mode set wrong (MANUAL vs AUTO)¶

You authored a sequence in MANUAL mode (operator presses GO between each). Operator tries to run it in AUTO mode at the show; they freeze waiting for it to advance, but it can't because every cue is MANUAL.

Fix: in v0.1.0, mode is per-cue. Set AUTO mode on cues that should auto-advance after firing. Test the sequence by stepping through it in Studio before saving.

AUTO-FOLLOW chain that runs away¶

You set 50 cues in a row to AUTO-FOLLOW. Press GO once. All 50 fire in 100ms. Audio overlaps, lights flicker, GPIOs fire faster than relays can react.

Fix: AUTO-FOLLOW means "fire then immediately advance to next cue." It's intended for "fire two things at once" patterns, not for entire sequences. For sequences, use AUTO with appropriate Wait cues between, or use a logic graph.

Cue numbers conflict after copy/paste¶

You duplicated a section (cues 5-10), pasted it. Now you have two 5.0s. Sortable display gets weird.

Fix: rule of thumb: cue numbers are sortable text, not unique IDs. Studio handles dupes by assigning unique internal IDs, but the display gets confusing. Renumber after duplication.

Trigger cue without a wired graph¶

You add a Trigger cue, point it at a trigger node, but the trigger has no downstream nodes wired. Cue fires, walks the graph, finds nothing. No side effects.

Fix: validator warns. Wire something downstream of every trigger.

Logic graphs¶

Forgetting that v0.1.0 conditions are passthrough¶

Author [trigger] → [condition: scene == "act 1"] → [dmx: act-1-bow]. Expecting it to only fire if the condition is true. v0.1.0 fires regardless.

Fix: in v0.1.0, don't rely on conditions. Author logic without them, or use multiple distinct triggers fired from different cues.

Forgetting that v0.1.0 delays are passthrough¶

Same trap. [trigger] → [delay: 5000ms] → [audio] doesn't actually delay in v0.1.0. Audio fires immediately.

Fix: for now, use Wait cues in the cue list to delay between effects, or fire two triggers from two cues with the operator delay between them.

Cycles in the graph¶

Wiring A → B → C → A doesn't loop forever (Runtime breaks cycles), but the visual "loop" suggests behavior that doesn't happen.

Fix: if you want repeating behavior, fire the trigger multiple times from multiple cues, or wait for v0.2 loop semantics if needed.

Cross-room triggers don't work¶

You try to wire a trigger in room A to a DMX node in room B. Studio refuses (or accepts but Runtime ignores).

Fix: logic graphs are per-room in v0.1.0. To do cross-room effects, fire two trigger cues — one in each room — from the same operator GO sequence (use AUTO-FOLLOW between them).

Schema and saving¶

Hand-editing the `.ishow` and breaking JSON¶

You opened the file in Notepad, added a comma in the wrong place, saved. Studio refuses to load it.

Fix: if you must hand-edit, use a JSON-aware editor (VSCode, Sublime). Keep a backup of the working version. Studio's .ishow.bak files are your friend.

Mixing schema versions¶

You have show-v1.ishow from Studio v0.0.5 (schema 0.4.0). New Studio v0.1.0 reads schema 0.5.0. It auto-migrates; that's fine. But if you then save and hand it to a venue running an OLDER Runtime, the older Runtime won't understand it.

Fix: schema is forward-compatible (newer Studio reads older files), not backward-compatible. Make sure venue's Runtime version >= the version that introduced the schema you're saving in.

Forgetting to save before quitting¶

Studio prompts on close if there are unsaved changes. Don't dismiss it without thinking.

Fix: Ctrl+S liberally. Studio also creates .ishow.bak files automatically on save.

Deployment / handoff¶

Sending the file via Slack/email and the formatting breaks¶

JSON files generally survive email, but some Slack/Discord clients corrupt them. Recipient downloads, can't open.

Fix: zip the entire show folder before sending. Compressed archives are immune to client-side mangling.

Not testing on real hardware before the show¶

Studio looks fine. Validator is green. Show "should work."

It probably won't. Studio can't test: - Real network reachability - Real fixture response - Real audio levels at venue - Real video Node capability with the actual file

Fix: budget at least one tech-dress with the venue's actual hardware. A 1-hour test run reveals 90% of issues before the audience sees them.

Handing off without a show summary¶

The venue tech receives a .ishow with 200 cues. They don't know which is "house lights up" vs. "intermission" vs. "curtain call".

Fix: include a handoff-notes.md file with: - Show name + version - Number of rooms / nodes / cues - Any non-obvious cue meanings - Cues to test during pre-show - Your contact info

When in doubt¶

Validate before save. Ctrl+8.
Save with a date in the filename. haunted-hallway-2026-04-25.ishow.
Test by fire-previewing. Double-click cues to see what would happen.
Phone the venue tech. Cheap insurance. They'd rather answer a question now than fix a broken show at 7:55pm.