ULTIMATE VJ
Download .mdView raw Markdown

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?

Use whatever issue tracker belongs to the copy of the source you obtained — this checkout has no configured git remote, so the source repository's own URL could not be verified from the repository itself.

Two GitHub locations are verifiable from the source, and both are useful:

When you report something, attach the two things the app offers for exactly this: the Settings → Performance readouts, and a --runtime-report capture. Both are described under "genuinely broken" below.

Where do I get it?

sh
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:

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/:

text
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:

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).

sh
./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. Two tools give ground truth rather than impressions:

Not verified