ULTIMATE VJ

Troubleshooting

Start with the status line at the bottom of the banks row. Nearly every operation reports its outcome there, including refusals. Then check Settings → Performance → Show playback diagnostics.

This page is organised by symptom, and each row names the mechanism rather than guessing at a cause.

"Nothing happened"

Symptom Mechanism worth checking
A crossfade appears instantaneous That layer's transition duration is 0. Factory layers start at 1000 ms; layers you add later start at 0 ms. the first thing to check on a newly added layer
Moving the crossfader does nothing The layer's Crossfader bus is None. Only layers assigned A or B respond
A layer went silent while another is soloed Solo anywhere silences every non-soloed layer — visual and audio
A pressed key does nothing Command and Control combinations can never be learned, and text editing, sheets and panels consume keys entirely
A clip you expect the Recent filter to show is missing Toggle-off does not stamp a recent trigger
Nothing got imported and the status line mentions a changed target The set, bank or slot changed while the file was decoding; that file was skipped, and a changed set abandons the batch

Black or missing picture

Symptom Mechanism
Output is black right after enabling surfaces An enabled surface setup with zero surfaces outputs black. Add a surface
Output went black after editing geometry Runtime mapping failures produce a black canvas plus an issue string shown in the Surfaces view. Your committed setup is untouched
Output is black and Blackout is off Check that no surface is disabled and that the source actually decodes — see the decoder refusals in Media formats
Blackout left projection visible Blackout acts on the output mailbox only; the composition preview inside the editors is deliberately not blacked out
A RenderWave effect shows black Its scope needs a prepared GPU frame: "RenderWave effects runtime is not prepared."
One effect is named "unavailable" An instance whose payload cannot be decoded here is retained, never substituted. Bypass or remove it, or open the set in a build that understands it
A held frame appears at loop points or after seeks Expected behaviour on interframe codecs: the last decoded frame stays visible while the decoder repositions. A brief held frame is normal

Won't load, won't save, won't open

Symptom Mechanism
"Unsupported set format version." The file is outside readable format versions 1–6
A set refuses to open with a validation message about speed, durations, in/out or cues Sets are rejected, not repaired. Duplicate column indices, duplicate clip slots, invalid speed, non-finite coordinates and invalid playback data all refuse to load
A file reported too many mappings rather than loading Exceeding 192 keyboard mappings, or 64 note / 128 CC MIDI mappings, makes a set unloadable rather than truncated
A clip with a saved position never resumes there The live playhead is deliberately not saved; reopening starts clips cleanly

Media

Symptom Mechanism
A video is rejected with a colour message The decoder refuses to guess. See the explicit rejection list in Media formats
An animated WebP does not animate Only GIF and APNG are recognised as animated images
A file is slow to import on first try but fine later Import validates by decoding a real frame off the main thread, at two files at a time
A previously failed file works later Only missing-file errors are retried, with 1/2/4/8-second backoff up to 4 attempts. Other failures are retained permanently until you relink

Audio

Symptom Mechanism
No sound at all File audio is off by default. Enable it at Settings → Clip audio → File playback → Enable file audio
Sound plays but pitch is wrong Expected: playback is rate-resampled, so speed changes pitch. There is no time-stretch anywhere
Audio stops mid-mix even though fewer than 32 clips play The 32-voice cap counts transition hand-off voices too
No audio in a recording Recordings are intentionally silent — video-only H.264
No audio analysis happening Nothing listens automatically. Settings → Audio input → Enable audio input
Input tier status: "no audio received" Nothing has arrived for two seconds — check device routing or pick another input

Output, recording and performance

Symptom Mechanism
Recording fails immediately Composition width or height is odd, or frame rate outside 1–120. "H.264 recording needs even output dimensions and 1–120 FPS."
Recording says the destination exists Choose a new filename; existing paths are refused
Undo/redo refuses It is refused while recording by design
Fullscreen menu shows · current composition The display's native mode is unverifiable or a dimension exceeds 4096, so the composition size is preserved and scaled instead
Frame rate lower than requested The rate is a request, not a guarantee. Read the status line and the Performance readouts, which are explicit that requested cadence is configuration rather than evidence of presentation
Fullscreen window swallowed the keyboard It can take key status and covers the whole chosen screen. On one display, plan around it
Quit hangs briefly Quit waits for recording finalization — this is deliberate, not a hang

Updates

Symptom Meaning
"This copy isn't managed by Homebrew." Installed outside the official tap, or the bundle is not named ULTIMATEVJ.app
"Homebrew manages a different copy of UltimateVJ." Another ULTIMATEVJ.app is the managed one — open that copy
"This copy has no release version." The bundle has no readable version, typically a local build

See Updating.

Nucleus of honest diagnosis

Two tools give ground truth rather than impressions. Use them before concluding something is broken:

Neither was exercised against a failing system for these pages.

Failed autosave restore

Read the error/status for the original and preserved file paths. Failed restore can create Recovery/Unrestored-Autosave-<UUID>.uvj with the original bytes. If a safe copy is unavailable or no longer matches, save your current set to another filename; the protected original will not be replaced. See recovery details.