Runtime debugging and reports

Available in UltimateVJ 0.2.4 (13) and later.

Record a problem

1. Choose Help → Runtime Debugging…. This opens Preferences → Performance.
2. Turn on Enable runtime debugging.
3. Reproduce the stall or other problem.
4. Choose Export Runtime Report…, save the .md file, and keep it with your problem notes. The same export action is in Help.
5. Turn off debugging when you finish.

Debugging is off by default. Once enabled, it stays on across app restarts until you turn it off. If the app freezes and you must reopen it, export afterward: the bounded journal retains earlier sessions until it rotates.

What is captured

• App version/build, macOS, graphics device and installed system memory.
• Requested and measured frame rate, composition size, pause/blackout and output state.
• Program and Preview failures, GPU/preparation timings, missed deadlines and busy-frame drops.
• Renderer failure receipts and recent media/audio errors.
• App error messages and RenderWave availability changes.
• A main-thread heartbeat alongside background renderer sampling, once a second. An increasing heartbeat age can help identify an unresponsive UI.

The report combines a current renderer snapshot with recent timestamped journal entries. These are diagnostic measurements, not proof of venue readiness or a diagnosis of every stall. The recorder can add overhead; enable it while reproducing an issue.

Local files

Use Show Debug Logs to open:

~/Library/Logs/UltimateVJ/Diagnostics/

The journal keeps a current and previous log of approximately 1 MiB each. Older entries rotate out. Reports can be exported while recording is off; they clearly state whether history exists.

Local Markdown exports exclude media files and full set contents, but runtime errors may contain media filenames or paths. Review the Markdown before sharing it. Automatic reporting is a separate, optional setting described below.

If export fails, the app reports that failure. A journal-write error is shown in the debugging card and in the report. A missing history message means there was no recorded journal to export.

Automatic developer reports

Forthcoming in 0.2.5 (16), not yet published to Homebrew. The current Homebrew build is 0.2.4 (13), with local debugging and Markdown export. Sections below marked 0.2.5 (16) describe the pending release.

Starting with 0.2.5 (16), Preferences → Performance includes Automatically send bug reports to developers. On the welcome screen, Send technical error reports starts selected for users without a saved reporting choice. This is a draft: Continue saves the displayed choice, while Not now or Escape closes the welcome screen without changing the saved reporting preference. Clear the checkbox before continuing to keep reports off. Preferences → Performance lets you change the choice later. Turning reporting on also enables local runtime debugging and remembers your choice after restarting.

When enabled, application errors, new Program or Preview render failures, a UI heartbeat older than five seconds, or five seconds without produced frames during active playback can submit a diagnostic. This does not diagnose the cause, capture a frozen process after it exits, or upload an Apple crash dump.

Reports go through the UltimateVJ HTTPS receiver into the private WALZMEDIA TASKS → To Do list at tasks.walz.media. The author is ULTIMATEVJ and the assignee is Codex. Board credentials stay on the server.

Only app/build and macOS versions, GPU model, system memory, numeric playback/performance counters, a random per-report ID and a fixed error category are sent. Media, set contents, clip names, file paths, filenames, local journals, raw error messages, names, email addresses, and persistent user/device identifiers are excluded. For detailed errors, separately export and review the local Markdown report.

The app keeps at most five unsent reports, retries temporary network/server failures with a delay, and limits each issue category to one capture per ten minutes. Queued reports expire after seven days. The receiver groups repeated reports of the same error category/build/GPU within the capture’s UTC day and limits incoming volume. Retries keep the original group across midnight. The settings card shows delivery, retry or rejection status.

Turn automatic reporting off to cancel an in-progress request and clear unsent reports. A report already accepted by the server remains on the private board. Turning runtime debugging off also turns automatic reporting off. Normal Quit preserves queued reports when reporting remains enabled.

Shader Browser playback

In 0.2.5 (16), Apply in Shader Browser starts the chosen shader in the captured slot, including when Trigger newly imported media is off. The file-import setting remains unchanged. Layer/master faders, blackout and clip quantization still apply.

Grid thumbnails and Neural Constellation

In 0.2.5 (16), grid thumbnails use the clip’s saved Color, ordered effects, transform, fit mode and opacity for shaders, video, stills, text and blank clips. A thumbnail is a representative frame; temporal effects use an isolated initial history rather than the live Program history. Changing a clip look rebuilds its grid image without changing the Shader Browser’s default preview.

Neural Constellation’s Node Count is limited to 45. Older supported looks above 45 are clamped when loaded, and modulation and runtime uniforms obey the same limit.

Optional email updates

Forthcoming in 0.2.5 (16); not yet in Homebrew. The welcome screen includes an optional Email address field and Sign up button for UltimateVJ updates, news and free visuals from Walz Media. Email signup is separate from technical reporting: Continue does not submit the email field, and diagnostic reports never include your address. You can use the app without signing up.

After choosing Sign up, check your email. Open the verification link, then choose Confirm subscription on the confirmation page. Your request stays pending until you complete that step. The link expires after 24 hours and can be used once. Closing the welcome screen does not cancel a signup you have already submitted.

Data handling

Automatic reports are sent only when a monitored error or stall occurs, to help improve UltimateVJ. The background heartbeat is evaluated on the Mac; regular heartbeat samples and successful actions are not uploaded. Raw error text is classified on the Mac into a small fixed category rather than uploaded or hashed. The receiver rejects unknown payload fields.

HTTPS connections necessarily expose a network address to the server while connected. The receiver does not put addresses or request headers into board cards or diagnostic receipts. Its Nginx route disables request logging and uses an in-memory address-based rate limit. Technical details such as GPU, macOS and app version remain part of the diagnostic and are disclosed here; they are not described as anonymous.

Local unsent queues keep at most five diagnostics for seven days with owner-only file permissions. Receiver deduplication receipts retain report IDs and card references for seven days. Cards stay on the private board until developers manage them. Automatic reporting does not grant developers access to the Mac, media or full sets.