General questions

Is Ultimate VJ free?

Yes - it costs nothing and requires no account or licence key. A binary preview installs through a public Homebrew tap; that does not establish public availability of the development source.

Is there a licence file?

Not in this checkout. git ls-files shows only vendored third-party licences (Ableton Link, ASIO and the FFmpeg build) and no project licence of its own. Because of that, these docs deliberately do not describe the project as "open source" - the repository does not currently state what recipients may do with it.

This documentation update does not choose or add a project licence. Vendored dependencies have their own notices, including Ableton Link, ASIO, FFmpeg and dav1d; those notices do not substitute for an explicit project licence. Licence compatibility and distribution permissions were not assessed by this documentation QA.

Where do I report a bug?

Forthcoming in 0.2.5 (16); not yet in Homebrew. The current 0.2.4 (13) build offers local debugging and Markdown export. The pending welcome screen and Preferences → Performance offer automatic technical error reports to developers. Reports are sent only after your reporting choice is confirmed and a monitored error or stall occurs. The private developer board receives error categories and technical measurements, with no names, emails, filenames, paths, media, set contents or persistent user/device identifiers.

You can turn reporting off at any time. For detailed problem notes, choose Help → Export Runtime Report…, review the local .md file, and contact Walz Media support. See Runtime debugging and reports for the exact payload, controls and retention.

Can I sign up for email updates?

Forthcoming in 0.2.5 (16); not yet in Homebrew. In the welcome screen, enter your email address and choose Sign up. Check your inbox, open the verification link, then choose Confirm subscription. Your request stays pending until you confirm; the link expires after 24 hours and can be used once.

Signup is optional and separate from technical error reporting. Continue does not submit the email field, and diagnostic reports never include your email address. You can use UltimateVJ without joining the list. See Optional email updates.

Where do I get it?

brew tap weswalz/ultimatevj
brew install --cask weswalz/ultimatevj/ultimatevj

Full details in Installation.

Do I need a Mac?

Yes. There is no Windows or Linux build, and both the Swift package and the published cask restrict the platform: macOS 26.0 or later, and Apple Silicon (arm64) only.

An Intel Mac cannot run it, and neither can an older macOS version.

Is it compatible with Resolume?

No. Ultimate VJ follows a Resolume-like workflow - bank/layer/clip matrix, tape-deck transport, per-scope effect stacks - but it is an independent implementation.

Concretely, that means:

• It can import a limited subset of legacy .avc XML compositions. This is not full Resolume compatibility or an export path; unsupported third-party effects remain opaque.
• Native effect presets do not reconstruct proprietary Resolume effect chains.
• It does not host third-party plug-ins (no FFGL, no ISF).
• Third-party effect records it encounters during import are kept as opaque data, named "unavailable", and never silently reinterpreted.

If you need drop-in compatibility, this is not it. If you want the workflow, it is free. See Limitations.

Where are my files?

Everything lives under ~/Library/Application Support/ULTIMATEVJ/:

Preferences.json      application preferences
Autosave.uvj          the 30-second autosave
OutputMapping.json    your output geometry
Recovery/             unsaved-set copies and failed-autosave preservation; never pruned
Updates/              one folder per in-app update attempt

Your sets are wherever you saved them. Recovery/ is never cleaned up automatically - it grows until you empty it.

How often does it autosave, and can I get my work back?

Every 30 seconds, whenever there are unsaved changes, plus once at quit. Both require the Autosave every 30 seconds preference, which is on by default.

Replacing an unsaved set writes a recovery copy first, and - usefully - that happens even if autosave is switched off. See Sets, presets and storage.

If autosave restore fails, the app reports why and preserves the original bytes to Recovery/Unrestored-Autosave-<UUID>.uvj when possible. If safe preservation fails, autosave replacement is blocked and the message asks you to save another file. See Failed autosave restore.

Can an older version open a newer set?

It depends on the format version. Sets are written as version 3, or 4 when any MIDI mapping carries an explicit CC-feedback choice, 5 for MetalFX Upscaled 4K, or 6 for group semantics/layer group membership; readable range is 1…6. An unsupported version is refused with a message rather than half-loaded.

This is deliberate: the app would rather tell you than silently drop an explicit choice you made.

How far does Undo go?

32 steps of undo history, with identical consecutive edits coalesced within 0.4 seconds so slider drags do not eat the whole history. Each step is a full snapshot of the session. The trim is enforced on the undo stack; whether redo is separately bounded is not established - see Sets, presets and storage. Undo is refused while recording.

Does it phone home?

Two network behaviours exist, both narrow:

• Checking for updates fetches the published cask manifest from GitHub - at most every six hours, with a one-hour minimum gap. Manual checks never install anything.
• Ableton Link, when you enable it, discovers peers on your local network.

The local control API binds to loopback only and cannot be reached from another machine.

Does it listen to my microphone without asking?

No. Nothing captures audio until you press Enable input, and microphone permission is requested only in response to that. Selecting a device in Settings does nothing; merely opening Settings does nothing either. The bundle ships a specific usage description so the prompt explains itself.

Can I run it alongside Resolume or another VJ app?

Yes, with one caveat: there is no frame sharing in either direction. Syphon and NDI are unavailable, so the two apps cannot pass video between each other. They can coexist on one Mac and drive separate displays.

How do I build it myself?

The pinned native decoder must be built before packaging; make_app.sh hard-fails otherwise. The dependency builder only accepts [maintainer-local path] (scripts/build_ffmpeg_dependency.sh:9-11). The local packaging helper accepts Debug only; Release is rejected by its preflight (scripts/package_renderwave.py:41-45).

./scripts/build_ffmpeg_dependency.sh
./scripts/make_app.sh debug

Note that locally built apps are ad-hoc signed and carry no entitlements, so they cannot grant themselves microphone access. The release pipeline is the only path that applies entitlements, Developer ID signing and notarization. Full instructions in Installation.

Why does in-app updating refuse to work?

Update and Restart requires a managed installation: a brew binary in a standard location, a bundle named ULTIMATEVJ.app, and Homebrew's own Caskroom/ultimatevj directory. Self-built and manually copied apps can still check for updates; they cannot install them. See Updating.

What do I do if something is genuinely broken?

See Troubleshooting and Runtime debugging and reports. Available tools:

• Settings → Performance shows the render backend, whether the Metal kernels compiled, and measured frame production and preparation figures.
• Help → Runtime Debugging… enables a bounded local journal. Export Runtime Report… saves a readable Markdown report. Automatic error reporting is separately controllable in Preferences → Performance.

Not verified

• Whether a published release exists for every version string present in this repository's own history. The manifest the updater reads is whatever currently exists in the tap.
• Behaviour of the shipping app on real hardware for anything in this page that concerns devices - none of it was exercised for these docs.