Sets, presets and storage

The set: `.uvj`

A set is your entire show. It is JSON, pretty-printed with sorted keys, and written atomically so a crash mid-save cannot leave a half file.

Top-level keys: documentID, midiMappings, keyboardMappings, renderResolutionMode, formatVersion, runtime, composition, clips, layers, groups, masterEffects, masterTransform, preferences, collections, compactLayerIDs, collapsedGroupIDs. Optional fields may be absent. The top-level groups stores group looks; composition.groups holds the routing/hierarchy records.

The declared UTI is com.walzmedia.ultimatevj.set, conforming to public.json, extension uvj.

Versioning and backward compatibility

Written formatVersion is 3 normally, 4 when a MIDI mapping carries an explicit CC-feedback choice, 5 for 4K · MetalFX Upscaled, and 6 for group semantics or layer group membership. The writer chooses the highest applicable format.
Readable versions are 1…6, with additional guards for explicit feedback, MetalFX and newer group semantics. renderResolutionMode is saved for the upscaled mode; absent mode data means native rendering.
Older documents load because newer fields are optional and decode to defaults. Missing control UUIDs are repaired once at load.
Unsupported versions are refused with "Unsupported set format version." rather than partially loaded.
Genuine duplicate UUIDs are rejected, not silently de-duplicated — control would be ambiguous.

What a set carries

Clips, layers, banks, groups, effect stacks, transforms, clip opacity and audio settings, file-tempo estimates, recent-trigger timestamps, tempo, meter, active bank, crossfader position and curve, autopilot, quantization, device choices, output geometry, MIDI and keyboard mappings, collections, and a copy of your application preferences.

Opening or creating a set keeps your current application preferences instead of adopting the file's copy. That is why a set's embedded preferences are a convenience, not a settings migration.

Validation is strict

A set that fails validation is rejected, not repaired. Dimensions and layer/bank counts, duplicate column indices, duplicate clip slots, invalid speed, coordinates or durations, invalid in/out or cue data — any of these make a file unloadable, with a message naming the problem.

Other file types

Extension	Contents	Size cap
`.uvj`	A whole set	—
`.uvjfx`	Effect stack preset (ordered instances, parameters, blend, animation)	1 MiB
`.uvjtransform`	Transform preset (the ten transform fields only)	16 KiB
`.uvjoutput`	Output mapping preset (geometry, surface order, enable state)	1 MiB
`.uvjshader`	RenderWave shader look (values, descriptor, animation)	1 MiB
`.avc`	Legacy XML composition — import only	—
`.mov`	Recording output (silent H.264)	—

Opening an .avc clears look and appearance state and does not set a save path — you must then Save to produce a .uvj.

Autosave and recovery

Behaviour	Detail
Autosave interval	Every 30 seconds, when there are changes and the Autosave preference is on
Autosave at quit	Same conditions
File	`~/Library/Application Support/ULTIMATEVJ/Autosave.uvj`
Restore on launch	Restored when the Restore preference is on; the launch flag `--fresh` skips it, once
Replacing an unsaved set	Writes `~/Library/Application Support/ULTIMATEVJ/Recovery/Set-<UUID>.uvj` first

Two things about that last row are worth remembering: the recovery write happens even when the autosave preference is off, and the Recovery/ folder is never pruned — it grows until you clean it out.

Presentation state

Collapsed group IDs and compact layer IDs save with the set and participate in Undo/Redo. Named interface layouts are separate app-local UserDefaults data under UVJNamedInterfaceLayoutsV1, not .uvj data or Preferences.json.

Failed autosave restore

If an autosave cannot be decoded or applied, the app reports the reason and tries to preserve its exact original bytes as Recovery/Unrestored-Autosave-<UUID>.uvj, verifying the copy by readback. The error/status includes the preserved path. Open another set or start a new set.

If it cannot safely preserve a copy, the original autosave remains protected and autosave will not replace it; save the current set to another file. A removed or modified preservation copy also blocks replacement of that protected original. This preserves evidence; it does not claim that an unreadable set has been repaired.

Application preferences

~/Library/Application Support/ULTIMATEVJ/Preferences.json. Changes save immediately; there is no Apply button.

Preference	Default
Render frame rate (15 / 30 / 60)	30
Restore autosaved set on launch	on
Autosave every 30 seconds	on
Trigger newly imported media	on
Clip audio enabled	off
Master audio volume	1.0
Master audio mute	off
Preferred audio input	System default
Input sensitivity	1.0
Preferred MIDI input unique ID	none
Preferred MIDI output unique ID	none

A changed preference also pins the currently selected audio input and its sensitivity.

Output geometry

Stored in three places, which is the source of most confusion:

Inside each set (runtime.outputMapping).
~/Library/Application Support/ULTIMATEVJ/OutputMapping.json, rewritten on every change.
Portable .uvjoutput presets, wherever you save them.

Explicit New or Open preserves the current mapping and display mode rather than resetting them.

Where everything lives

text

~/Library/Application Support/ULTIMATEVJ/
  Preferences.json
  Autosave.uvj
  OutputMapping.json
  Recovery/Set-<UUID>.uvj          unsaved-set replacement
  Recovery/Unrestored-Autosave-<UUID>.uvj   failed-restore preservation
  Updates/<UUID>/                  one folder per in-app update attempt

A set may also be collected into a portable folder: