Library
Status: draft. Concrete reference content + structural placeholders; flesh out the prose + screenshots when ready.
Purpose
Your local preset library — the source of truth for every preset VL Studio knows about. On a fresh install the library is empty: there's no bundled factory baseline. Your VL3X is the source of truth; you populate the library by clicking Pull All to read every preset slot off the device.
Once populated, the Library is where you search, sort, edit metadata, push back to the device, pull updates from the device, export, import, bulk-delete, duplicate, and open presets for editing. It's also where the AI's preset-related tools read from and write to.
VL Studio difference — unlimited library
The VL3X has memory for 500 presets, and the only on-device "list" is a flat scroll filtered by Genre or Favorites. Naming, organizing, and finding presets all happen one at a time through the Control Knob and a tiny LCD.
VL Studio's library has no preset count limit. Search by name, sort by columns, filter, bulk-select, bulk-delete, bulk-rename, bulk-tag, AI-describe-all, ZIP-export-all, duplicate — all things the device simply can't do. The device's 500 slots become a working set you push to and pull from; your full collection lives on disk.
Walk-through
First-launch flow
- Connect the VL3X over USB. Check the Device page for the connected indicator.
- Pull All — large button at the top of the Library page. Reads all 500 slots from the device into the library. Takes roughly 3–8 minutes depending on how many slots have multi-step presets — a 4-step preset takes about 4× as long as a 1-step preset. Empty slots are skipped. Progress shows in a green banner as a running tally; errors are reported with their first few details.
- After Pull All, the library row count should match the populated slots on your device.
Day-to-day workflow
After the first pull, your typical workflow:
- Edit on the device → click Pull Active to bring just the currently-loaded preset back into your library.
- Edit in VL Studio → use the per-row VocalShaper, GuitarShaper, or Open (Preset Editor) button. Changes save to the library row immediately; click Push to send back to the device.
- Reorganize → use the Meta button to rename, tag, and describe presets; use Dup to clone before experimenting.
- Share or back up → use the per-row Exp to write a single
.preset.jsong, or the header's Export All (ZIP) to bundle everything.
The page layout
The Library is a single-page table with header actions above and a row per preset below.
Header actions
| Button | What it does |
|---|---|
| + New Preset | Creates a blank preset (prompts for a name) and opens it in the Preset Editor. |
| Pull All | Reads every populated slot (1–500) from the device into the library. ~3–8 minutes. Shows a green progress banner with running totals. |
| Pull Active | Reads only the currently-active preset from the device. Prompts for a name. Use this when you've edited on the device hardware and want just that one preset captured. |
| Reconcile | Probes the device for every slot your library claims a preset is in. Clears the slot field on rows whose slot is actually empty on the device. See Reconcile internals. |
| Import JSON | File picker for .preset.jsong, .jsong, .json, and .vl3x.json. Imports as a new library row with source = import. |
| Export All (ZIP) | Bundles every preset in your library as individual .json files inside a timestamp-named ZIP, written to your downloads folder. |
| AI Describe All | Sends each preset missing a description to the AI for a written description. Presets with existing descriptions are skipped (so you don't overwrite your edits). Shows a violet progress banner with X/Y count and error tally. |
| Refresh | Re-reads the library DB. Use after an external write (e.g., a backup restore) to pick up new rows. |
| Delete Selected | Appears only when one or more rows are checked. Bulk-deletes the selection from the library. Confirmation required. |
| Clear All | Deletes every preset in the library. Library-only — the device isn't touched. Confirmation required. |
Per-row actions
Each preset row has its own action set:
| Button | What it does |
|---|---|
| Open | Opens the Preset Editor — visual block-by-block editing. |
| VocalShaper | Opens VocalShaper in PRESET mode against this preset. |
| GuitarShaper | Opens GuitarShaper in PRESET mode against this preset. |
| Push | Sends the preset back to its device slot. If the preset has no slot assigned, VL Studio auto-allocates the first unused slot. |
| Meta | Opens a modal to edit the preset's name (15-char max), genre focus (VOX / GTR / VOX+GTR), custom tags, and description. |
| Dup | Duplicates the preset under a new name. Opens the duplicate in the editor. |
| Exp | Exports this single preset to a .preset.jsong file. See Presets format. |
| Dev Del | Deletes from the device slot only — your library copy stays, with the slot field cleared. Confirmation required. Useful for freeing a device slot without losing the preset. |
Selection and bulk operations
Each row has a checkbox in the leftmost column; a Select All checkbox sits in the header. When at least one row is checked, the header's Delete Selected button appears.
Search, sort, and filter
Search
A single text box at the top of the table performs a case-insensitive substring match across three fields simultaneously:
- Name
- Genre tags
- Description
Type "warm" and you'll match every preset whose name, tags, or description contains "warm." Type "slot 42" and you'll match presets with "42" in any of those fields.
Sort columns
Click any column header to sort by that field; click again to flip ascending/descending. An arrow indicator shows the current direction.
| Column | What it sorts by |
|---|---|
| Slot | Device slot number (rows without a slot sort separately). |
| Name | Alphabetical by preset name. |
| Source | The source tag — see Source tags. |
| Uses | The use_count field — see Use count. |
Filter
The Source / Genre dropdown filters described in earlier docs are not currently shipped — search-by-substring covers both for now. To narrow to AI-generated presets, search for generated; to narrow to a genre, search the genre name.
Visual badges
Per-row badges surface at-a-glance information that doesn't fit in the column layout:
| Badge | Meaning |
|---|---|
| GTR (amber) | Guitar-focused preset (genre_tags starts with guitar) |
| VOX+GTR (purple) | Hybrid preset — both vocal and guitar content |
| BT (cyan) | Backing track attached. Tooltip shows "Detected" (auto-detected by VL Studio at pull time) or the named track path. |
Presets without a focus badge are vocal-focused (the default).
Multi-step presets (1–4 steps per slot) are handled silently — they take longer to pull but aren't visually marked.
Source tags
The Source column shows the raw source tag from the database. Possible values:
| Source value | Meaning |
|---|---|
| device | Pulled from the device — the most common source after Pull All. |
| factory | Legacy tag from older builds; still used in some code paths. Treated equivalently to device for most purposes. |
| generated | Created by the AI via generate_preset. |
| import | Imported from a .preset.jsong file (regardless of where the file originally came from). The original attribution lives inside the file as the top-level source and meta.source fields. |
Individual presets export to .preset.jsong files for sharing across machines or with bandmates. For the format details and round-trip behaviour, see Presets (.preset.jsong).
Reference
Reconcile internals
The Reconcile button sends a Header request to the device for every slot your library claims a preset is in. For each response:
- Header returned → the slot has a preset on the device; the library row is correct.
- Notification "preset not found" → the slot is empty on the device; VL Studio clears the slot field on the library row, leaving the row itself intact.
- No response (timeout) → counted as "unresponsive"; the slot field is left alone for that row (so a momentary device hiccup doesn't wipe your slot assignments).
Reconcile reports a summary banner: Reconciled N claimed slots — M orphans cleared / K unresponsive. Useful after a factory reset on the device, manual on-device deletes, or restoring an old backup whose slot assignments have drifted.
Use count — what counts as a "use"?
The use_count field increments on every Push operation — pushing a preset to the device (whether from the per-row Push button or via AI Chat) bumps the count. Other events (loading the preset in Performer Mode, opening it in an editor, exporting it) do not count.
Use Count is therefore best read as "how often have I deployed this preset to the device," not "how often have I used this preset live." If you want to know your most-played presets for setlist building, the Songs and Setlists pages are the source of truth.
Multi-step preset behavior
A slot can hold a 1–4 step preset. Multi-step presets take proportionally longer to pull — a 4-step preset is roughly 4× a 1-step. The progress indicator updates per slot, not per step, so it can look like Pull All is paused when it's just working through a heavy slot.
VL Studio handles multi-step presets transparently end-to-end: pull captures all steps, push restores all steps, the Preset Editor and VocalShaper / GuitarShaper let you cycle between steps for editing. There's currently no visual indicator on the Library row that a preset is multi-step — open it in the editor to see.
Slot indexing
Slots are 1-indexed in the UI (1–500), matching how the device presents them. Internally, some backend code paths use 0-indexed values (program changes are sent as slot - 1), but you never need to think about that from the Library page.
Pull All — what's actually happening
Pull All walks slots 1–500 one at a time, with a per-slot timeout. For each slot:
- If the slot is populated, all message blocks for that preset (1× per step) are collected and stored.
- If the slot is empty, the device responds with a "not found" notification; VL Studio counts it as skipped.
- If the slot times out, an error is logged with the first few error strings shown in the progress banner.
The operation can't currently be cancelled mid-run. The header's progress banner shows the running tally (Pulled: X / Skipped: Y / Errors: Z) and the final summary on completion.
Backing track field
Each preset row has an optional backing_track_path. The field is read-only on the Library page — it shows as a BT badge with a tooltip. Edits happen via the Preset Editor (or via the cue editor in Songs for per-cue tracks).
The path is absolute, so it isn't portable across machines without a shared folder layout or a manual relink after moving.
AI Describe All — what it does
For every preset missing a description, the AI Chat's describe_preset tool runs in batch — the AI reads the preset's parameters and writes a short musician-facing description. Presets with existing descriptions are skipped, so running Describe All multiple times only fills in the gaps. The progress banner shows count and error tally; click Dismiss to clear the banner when done.
Empty state
On a fresh install or after Clear All, the table shows: "No presets in library. Use 'Pull All' to import from device." Once you've populated the library, an empty result from search/filter shows: "No matches."
Status banners
The Library page uses four banner colors to communicate operation state:
| Color | Meaning |
|---|---|
| Blue | Short status messages (auto-dismiss after 4 seconds) — e.g., "Pushed preset to slot 12." |
| Green | Pull All / Reconcile / Describe All progress and result summaries. |
| Indigo | Export All (ZIP) result — dismissible. |
| Violet | AI Describe All progress — dismissible. |
Troubleshooting
| Symptom | Fix |
|---|---|
| Pull All seems stuck on slot N | Multi-step preset — wait. If it's still stuck after a half-minute on the same slot, click the Mixer's Reconnect button. |
| Pull All produces fewer rows than expected | Empty slots on the device aren't pulled. The row count only includes slots that actually have a preset. Use Reconcile if your slot accounting feels off. |
| Library shows a preset at slot N but the device says slot N is empty | Click Reconcile. It probes the device and clears stale slot assignments without deleting your library row. |
| Bulk delete leaves some presets behind | Failed deletions are tallied in the status banner. Most often the preset is referenced by a song cue or a setlist entry — VL Studio clears those references first, so try again; if the same row keeps refusing to delete, file a bug. |
| I pushed a preset and it went to a different slot than I expected | If the preset's slot field was empty, VL Studio auto-allocates the first unused slot. To target a specific slot, set it via Meta first, or use Pull Active to capture a slot you've already loaded on the device. |
| Dev Del removed the preset from the device but it's still in my library | That's the design — Dev Del clears the device slot only. Your library copy is preserved. To remove the library row too, use the row's checkbox + Delete Selected, or Clear All. |
| AI Describe All didn't update one of my presets | The batch skips presets that already have a description (so it doesn't overwrite your edits). Clear the description field via Meta and run again. |
| Export All (ZIP) wrote nothing visible | The ZIP is written to your OS downloads folder with a timestamp-keyed name. Check there. The indigo status banner shows the exact path. |
| Source column shows "device" but I expected "pulled" | The raw source tag for device-pulled presets is device. Legacy presets may show as factory; both mean "originated from the device." pulled is not a current value. |
| Cleared All by accident | If you have a backup snapshot (Settings → Backups), restore from there. Otherwise re-run Pull All to repopulate from the device. The library doesn't have an undo for Clear All. |
| Reconcile said "K unresponsive" — what does that mean? | The device didn't respond to the Header request for those K slots within the timeout. VL Studio leaves those slot fields unchanged (conservative — a transient hiccup shouldn't wipe your slot assignments). Try running Reconcile again. |
| BT badge says "Detected" but the cue doesn't auto-play it | The backing track was detected at pull time as a reference inside the preset's parameter set, but the actual audio file may not be on this machine. Set the backing-track path manually via the cue editor in Songs. |
| Search doesn't find a preset I know is there | Search matches name, genre tags, and description (case-insensitive substring). If the term isn't in any of those, it won't match. Edit the preset's Meta to add searchable tags. |
See also
- Preset Editor — visual block-by-block editing on a single preset.
- VocalShaper / GuitarShaper — full tabbed editors for the vocal / guitar signal chain.
- Presets (.preset.jsong) — per-preset export format with full round-trip behaviour.
- Full backups — bulk preset backup as part of a whole-library snapshot.
- Sharing & Files — overview of all interchange formats.
- AI Chat — generate, describe, suggest, and inspect presets via natural language.
- Device — the live MIDI surface that Push and Pull operations speak to.