Full backups — .vl3x-backup.json.gz

Status: draft. Concrete reference content + structural placeholders; flesh out the prose + screenshots when ready.

Purpose

A full backup captures everything in your VL Studio library — presets, songs, setlists, chat sessions, preferences, AI configuration — into a single gzipped JSON file. Use it to migrate to a new machine, archive a working configuration before experimenting, restore after a fresh install, or hand a full setup to a bandmate or collaborator.

What's in the file

Top-level field	Contains
format	"vl3-backup-v2" — the current backup format. v1 backups (missing some sections) restore via the same path and gracefully skip absent fields.
backup_type	"snapshot" for the standard create-snapshot path.
presets	Every preset row — name, slot, source, step count, full parameter object, genre tags, description, author.
songs	Every song with its full cue timeline (labels, timestamps, preset references, actions, lyrics, notes, backing-track paths).
setlists	Every setlist with its ordered entries (songs, presets, talk-breaks).
chats	Your AI chat session history — every conversation, with the AI's tool calls included.
user_preferences	Per-user learned preferences (used by the AI for personalization).
generation_history	Recent AI generation prompts and their results — useful for understanding what's been generated and why.
ai_config	Full AI configuration: provider keys, per-task routing, model overrides, custom system prompts, token budgets, disabled tools.
app_prefs	Application preferences — TALK preset slot, recordings folder, voice settings, nav order, advance-cue CC.

How to create one

Settings → Backups → Create Snapshot. VL Studio writes the snapshot as a row in your local backup history. Each backup row shows its creation timestamp, library counts (presets / songs / setlists), and per-row actions (Browse, Download, Restore, Delete).

To get the backup off the machine as a file you can move or share, click Download on the backup row. VL Studio writes it as {name}.vl3x-backup.json.gz.

How to restore

Two ways:

• From a backup row in your local history — click Restore. Destructive: it overwrites your current library wholesale.
• From a file on disk (e.g., a downloaded backup from another machine) — click Import from File in the Backups section, pick the .vl3x-backup.json.gz. You'll get a browse view first so you can see what's inside, with per-section checkboxes for selective restore.

Selective restore

When importing from a file, you can pick exactly which sections come in:

• Want only the songs from another machine? Tick songs, leave the rest unchecked.
• Want to keep your local AI configuration but pull in someone else's preset library? Tick presets, untick ai_config.
• Want a clean preset library but keep your chat history? Tick presets and untick chats.

Selective restore is additive — it merges into your current library rather than wiping it first.

What round-trips cleanly

• Preset linkage on songs — unlike .jsong exports, cue → preset references are preserved through a backup round-trip. This is the lossless way to move songs with their preset attachments intact.
• Setlists with their entries — backups are currently the only way to restore a setlist on another machine.
• Chat history — your AI conversations come along.
• Custom AI system prompts — overrides survive round-trip.
• AI Skills — custom skills you've written are restored along with your AI config.

What does not round-trip

• SysEx data is recreated, not preserved. Each preset's SysEx blob is rebuilt from the stored parameters on restore. For most purposes this is identical to the original — the device behaves the same. If you ever need a true bit-for-bit copy of what's on the device, pull from the device itself rather than relying on a restored backup.
• Backing-track audio files are not included in the backup. Only the path references are. The audio files need to follow separately.
• API keys are stored in ai_config. They round-trip — which means a backup contains your AI provider credentials. Don't share full backups publicly or with anyone you don't trust with your API keys. See "Sharing safely" below.

Cross-machine moves

Backups are designed for cross-machine migration:

• Same OS, same user — Download on machine A, Import from File on machine B. Everything works.
• Different OS — same flow. The format is platform-independent JSON.
• From an older VL Studio version — backwards compatible. Missing sections from a v1 backup are gracefully skipped on restore.

The one catch is backing-track files, which sit outside the backup. If you've used backing tracks heavily, also copy the audio files over and either keep them at the same absolute paths or re-link them on the destination.

Sharing safely

Backups contain your AI provider API keys. Before sharing a backup with someone else:

• Settings → Backups → Reset AI Config on a throwaway machine, then create the snapshot — this clears keys from the snapshot.
• Or open the resulting .vl3x-backup.json.gz (it's gzipped JSON; any archive tool can unpack it), edit out the ai_config.providers[].api_key fields, and re-pack.
• For most sharing use cases, a .jsong per song or a .preset.jsong per preset is friendlier than a full backup — you share only what you mean to share.

See also

• Settings — the Backups section that creates, browses, restores, and imports backups.
• Sharing & Files — overview of all interchange formats.
• Songs (.jsong) — per-song export, lighter than a full backup.
• Presets (.preset.jsong) — per-preset export.
• AI Skills — sharing the markdown files that customize the AI's behaviour.