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:
- Settings → Performance → Render backend (Metal or software fallback), Native effects kernels (Ready or Unavailable), Frame production and Frame preparation.
--runtime-report <path>at launch writes a JSON readback of uptime, icon verification, render-loop diagnostics and per-surface sizes and presentation; sendSIGUSR1to refresh it. It installs no periodic polling.
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.