Troubleshooting

A show-control tool fails loudest at the worst moment. This page covers the problems operators actually hit, in the order they tend to appear — and how to recover without losing work.

No audio, or a playhead moves without sound

1. Confirm that the media file exists and the intended cue is selected.
2. Check the resolved Master or selected audio-bus device binding and physical channels. An unbound bus can block both preview and GO even when a global output device is listed.
3. Check cue volume, bus volume, mute and the interface’s physical output. Preview aliases Master.
4. Check for the exact error message, for example “Preview route unresolved”. Do not repeatedly assign OSC mappings or replace the audio file to solve a routing error.
5. If controls stop responding, preserve the show with Save/autosave and report the logs. Do not take an animated playhead as proof that the engine is responding.

Waveform seeks feel delayed

State whether the delay affects audible sound, the visible playhead, or both; identify the Inspector, embedded Audio Editor or detached editor. Include version 0.99.1, file format, operating system and audio device. Test one click as well as dragging, and report whether it occurs during preview or normal GO playback. The beta latency investigation was closed after improved observed behaviour; there is no claim that every intermittent cause was identified.

”Recovered autosave” — Restore or Ignore?

After a crash or forced restart, relaunching CueForge shows a recovery banner: Restore or Ignore.

• Restore loads the recovered autosave into the window. Nothing is overwritten on disk until you save — restore first, then save under a new name if unsure.
• Ignore discards the autosave permanently.

When in doubt: Restore, save as a new file, compare. See Projects, Saving and Recovery.

Missing media after moving the project

Symptom: Missing badges on cues, preflight blocks Show Mode.

1. Open the Relink Missing Media dialog from the banner.
2. If the whole media folder moved, use Locate media folder… — one folder scan repairs every reference inside it.
3. For scattered files, use per-item Choose file….
4. Choose Relink when it is the same asset that moved; choose Replace only when a different asset must stand in.

Relinking is disabled under Show Lock and in Show Mode — do it before the show. See Projects, Saving and Recovery.

The quit guard appeared — what do the buttons do?

Quitting with unsaved changes shows “Quit CueForge?”:

• Save and Quit — saves, then quits. If the save fails, an error is shown and the quit is aborted cleanly.
• Discard Changes — quits without saving.
• Cancel — stays in the project, nothing saved or lost.

Repeated Cmd+Q presses while the dialog is open are ignored, so the guard cannot be pounded through.

Cmd+Q does not respond in Edit Mode

Physical acceptance of Cmd+Q in Edit Mode is being finalised (it is confirmed working in Show Mode). If quit does not respond in Edit Mode, use CueForge → Quit CueForge from the application menu. The quit guard dialog itself works either way. See Current Limitations.

Audio is not audible

Work through the routing in order:

1. Audio output route — a cue set to None is silent by design; preflight warns “no audible output”.
2. Audio Bus — check the assigned bus is not muted and its volume is up.
3. Preview route — Preview currently aliases Master; it is not a separate silent path. Do not use Preview expecting silence in the house.
4. File missing or unreadable — check for the Missing badge; re-encode to WAV if a compressed file misbehaves.
5. Multichannel mappings — insufficient channels surface in validation; check Open Multichannel.

The waveform is still analysing

The Audio Deep Editor shows “Analyzing audio…” / “Detecting transients…” with a percentage while it builds the waveform. Large files take longer; the analysis can be cancelled, and playback is not blocked while it runs. If it seems stuck, close and reopen the editor — analysis resumes from scratch but completes.

Preflight will not let me into Show Mode

Blocking errors cannot be acknowledged away. Use Jump to cue on each red item, fix it, and re-enter. Common blockers: missing media, no output target on a video cue, a Call Cue with an invalid target. Warnings can be acknowledged for the session — read them first. See Preflight.

PANIC is active and nothing responds

That is correct behaviour: while PANIC ACTIVE is showing, all transport is blocked. Recovery is deliberate:

1. Click Recover from Panic.
2. Confirm the recovery in the dialog.
3. The banner clears and the show returns to a stopped, re-armable state.

Never automatic — the operator decides when the emergency is over.

Show Lock blocks editing, undo, or STOP

Show Lock is working as designed: it blocks editing, undo/redo, New/Open, trigger-setting changes, and STOP. Save remains allowed. PANIC always works — under Show Lock, PANIC is the emergency path. Toggle the lock with Cmd/Ctrl+L. See Show Mode.

Output window is on the wrong display or missing

1. Press O to toggle the output window.
2. Check the binding: a bound display that is disconnected shows Missing in preflight and Settings. CueForge never silently moves content to another display — that is deliberate single-display safety.
3. Bind the logical output to the correct physical display in the Outputs tool window, then verify with Blackout (B) and Test Pattern (T).

Tip: On single-display machines, bind and verify before showtime — there is no fallback display for content to move to. Display hotplug handling is implemented, but live hotplug validation is still in progress.

Video dissolve Take does not happen

Timed Dissolve Take is authored but not implemented at runtime in this beta — it fails deterministically. Switch the Take Type to Cut. Preflight flags configured dissolves; tech rehearsal should have caught it. See Video Cues.

External triggers are not arriving

1. Check the health strip in the Control Mapping window — is the protocol Listening, or Disabled?
2. Enable listeners in Settings → Triggers & Control (OSC port, MIDI device, HTTP port).
3. Remember the matching rules: HTTP matches method + path only and always returns 200; note_on vs note_off are distinct controls; duplicate sources match first mapping wins.
4. Check preflight’s external_control.* checks for listener state and source conflicts.

A mapping fired twice (or not at all)

Execution is exactly-once per trigger — but a physical controller can send note_on/note_off pairs, which are two distinct triggers. If a pad seems to fire “twice”, you have probably mapped only one of the pair, or mapped both to the same action. Map note_off to nothing (or to a deliberate action). See Control Mapping and the Trigger Inbox.

I need to report a problem

Use Help → Export Diagnostics… to write a support bundle (environment, logs, manifest) and Help → Open Logs Folder for the raw logs. CueForge does not upload diagnostics automatically — attach the bundle to your support message yourself. Include what you were doing when the problem occurred. See Projects, Saving and Recovery.