The Validator¶

The Validator (Ctrl+8) checks your show for broken references and structural problems. The same checks run inside Runtime when it loads a .ishow — if the validator says "no errors" in Studio, Runtime will accept the file.

This document explains what the validator checks, what it doesn't, and how to read its output.

How to use it¶

Press Ctrl+8 at any time. The Validator module shows:

A summary at the top — 0 errors, 2 warnings, 1 info
A list of issues, grouped by severity

Click any issue to jump to the relevant module/cue/node so you can fix it.

The status bar at the bottom of Studio also shows a small indicator: green checkmark when clean, amber when there are warnings, red when there are errors.

What "error" vs "warning" vs "info" means¶

Error (red) — Runtime will refuse to load the show. You must fix before saving for production.
Warning (amber) — Runtime will load the show but something probably won't behave as you intend. Review.
Info (blue) — A note. Doesn't affect playback. Examples: "look has only one keyframe" (technically valid but might be unintentional).

In v0.1.0, the validator currently emits errors and warnings; info-level checks are sparse. Expect more info-level checks in v0.2.

What the validator checks¶

Cues reference real things¶

Audio cue → audio node — node ID exists, node role is audio
Audio cue → file — file field is non-empty (Studio doesn't check the actual file exists; that's the venue tech's job during media distribution)
Video cue → video node — same
DMX cue → look — look ID exists in the same room
GPIO cue → GPIO node + channel — node exists, role is gpio; channel name is set
Trigger cue → logic trigger node — trigger ID exists in the same room's logic graph

Looks are well-formed¶

Look has at least one keyframe — empty looks fire but do nothing. Warning.
Look duration > 0 — duration of 0 fires the first keyframe and ends. Warning if look has multiple keyframes (interpolation never happens).

Logic graph is well-formed¶

Wire endpoints exist — both source and target nodes still exist
No wire from input to input — wires must go output → input
Logic node kinds are valid — must be one of the 8 documented kinds (trigger / condition / delay / audio / video / dmx / gpio / transport)
DMX logic node references real look — if a DMX node has a lookId, it must exist
Audio/video logic nodes reference real Pis — if set, must exist with the right role
GPIO logic node references real Node + channel

Timeline is well-formed¶

Tracks exist for all clips — orphaned clips trigger an error
Clip kinds match track kinds — DMX clip on an audio track is invalid
Clip references resolve — DMX clip's lookId must exist; audio clip's file must be set; etc.

Schema basics¶

Schema version is supported — files from much-older Studio versions migrate up; from newer versions, error
Required fields present — show name, room IDs, etc.
JSON structure intact — Studio writes valid JSON; this only fires if you hand-edited a file and broke the structure

What the validator does NOT check¶

This is the more important section. A green checkmark does not mean your show will work at runtime. It means there are no structural problems. It cannot check:

Hardware reachability¶

The validator doesn't try to ping nodes. A node could have IP 10.0.0.99 that doesn't exist on the venue network. Runtime will fail at fire-time with a connection error.

Media files exist¶

A cue references intro.mp4. The validator only checks the field is non-empty. The file might not exist on the video Node; that's only discoverable at fire-time, or by the venue tech running the media distribution check.

Channel mapping makes sense¶

A GPIO cue uses channel gp4. The validator confirms the channel name is set, but not that gp4 is mapped to a real channel on that Node (the Node has its own config the validator can't see).

Look values are reasonable¶

A look could have dev-1:ch-1 = 999. Out-of-range, but the validator doesn't catch this. Runtime clamps to 0..255 silently.

Cue durations are realistic¶

A cue can have a duration of 0.01 seconds firing audio. That's fine to author; the audio file probably plays longer than the cue. Behavior is correct (audio plays for its full natural length), but it might confuse you.

Logic graph won't fan out catastrophically¶

A trigger could fan out to 200 GPIO nodes. The validator doesn't limit this. Runtime will fire all 200 sequentially, hitting Pis at ~5ms each = 1 second total. If timing matters, your show breaks.

Same-cue-list collisions¶

Two DMX cues both fire the same look at overlapping times. Last-write-wins per channel. Usually fine; can produce odd flickers.

Conditions evaluate truthfully¶

v0.1.0 conditions are passthrough; v0.2+ will evaluate. The validator can't check whether your condition expression is meaningful (or even parseable) until evaluation is implemented.

Performance / hardware capability¶

A 4K video on a Node (4 GB) might stutter. The validator doesn't know about this. Test on real hardware.

Show-quality concerns¶

"Is this show actually good?" Outside scope.

Reading common error and warning messages¶

`cue 3.0 references missing audio node aud-2`¶

Cue 3 (an audio cue) is set to play on Node aud-2, but no node with that ID exists. Either: - Add the node (Nodes module) - Edit the cue to point to a different node - Delete the cue

`look "Sunrise" has no keyframes`¶

Warning. The look exists but is empty. Either add keyframes or delete the look. If a cue references this look, it'll fire and produce no DMX changes.

`wire endpoint missing: source node lg-7`¶

The logic wire was wired from a node that's since been deleted. Fix the wire or delete it.

`cue references missing trigger node lg-12`¶

A trigger cue points to a logic trigger node that no longer exists. Re-create the trigger node or change the cue.

`unsupported schema version 0.6.0`¶

You're trying to load a file saved by a newer version of Studio. Update Studio.

`clip 4 references missing track t-2`¶

Timeline clip orphaned. Either re-add the track or delete the clip.

Workflow recommendations¶

Validate before every save. Make it a habit.
Keep the show clean as you go. Don't accumulate 30 errors and try to fix them all at once.
Validate before sending to the venue tech. A clean show file at handoff prevents 80% of "the show file is broken" calls.
Validate after every Studio update. New rules might catch things in your existing show. Better to find them in Studio than in Runtime at the venue.

What to do when the validator's wrong¶

It can be wrong. If you're convinced an issue is bogus: 1. Look at the issue carefully — re-read the message, click into the relevant module, verify the actual data 2. If still convinced it's a false positive, email support@immersecontrol.com with: - The .ishow file (or a minimal repro) - The validator message - Why you think it's wrong

False positives in the validator are bugs and we want to know.

What to do when the validator misses something¶

You ran a show, something didn't work, and the validator was clean. Report this too — that's a "validator gap," and we expand its checks based on these reports. The history of validation rules is mostly "we added a check after a show broke at the venue."