Skip to content

[P1][BACKLOG] Portable VST Vault — user-owned state and fast session reopen #85

Open

Description

@masarray

Milestone B verified triage — 2026-11-17: P1 / vst3-host / feature / backlog. Classification ≠ completion of product feature or physical FAT.

Scope / release boundary: User-owned VST3 state vault; privacy and safe restore.

Exit criteria:

  • Define per-user ownership/versioning and bounded cache invalidation without storing unauthorized plugin binaries or licenses.
  • Measure session reopen speed and safety under missing/outdated vendors; preserve .smix FX identity and deterministic fallback.

Canonical issue ledger. Preserve historical evidence below; no speculative merging or rewriting approved audio.


FACTORY FX / SIX FIRST-PARTY VST3 (2026-10-30): Factory FX ADR · Factory FX PRD · manifest schema · merged architecture PR #187 · epic #185. Six original bundled VST3 targets: ArSonEQ, ArSonComp, ArSonVerb, ArSonHarmony, ArSonColor, ArSonKuPik Enhancer. NO binary FactoryFX modules are currently shipped by this docs change; first qualify ASKPVST public v0.5.26 + ArSonEQ feature branch artifacts and obtain product/AGPL/JUCE/EULA approval; ArSonVerb license and Comp/Harmony/Color DSP are later gates. ASKPVST #60, EQ #6, Verb #4. G5A #178 and MS1 #184 are already MERGED. Factory immutable VST3 modules must use existing native FX graph while USER vault remains separate; protect L2 #176, PDC #95, actual hardware #15. Do NOT mark a plugin loadable from a roadmap card.

Canonical product requirement — ONE ArSonMix for EVERYONE

Owner correction (2026-10-27): supersedes any previous "Public edition versus Personal Studio edition", "only owner may bundle plugins", or feature-restricted distribution proposal. ArSonMix must behave like an open, highly configurable performance host in the spirit of VSTHost and OBS. Any user can assemble their own VST setup, store plugin files and state inside their ArSonMix workspace, then launch directly ready for a performance without rescanning every installed VST on every startup.

NON-NEGOTIABLE product principles

  1. One app, identical feature set for all: public download, installed mode, portable USB mode, user's own custom-made bundle all run the SAME EXE and have access to the SAME plugin-import, copy, preset/snapshot/session and export capabilities. There is no personal/private code edition, no privileged user flag or paywalled bundling path.
  2. Empty by default, not limited by default: official public installers/ZIPs have no user's proprietary VST files or personal presets, but fully functional Import, Plugin Vault, Snapshot, Scene/Session, Export Studio, and Performance Quick Load are available to everyone. This is packaging data separation, not feature separation.
  3. User decides which plugins: importing just 1, 3, or 300 VST files into a library must NEVER require scanning the entire PC. Offer native file picker, folder import, direct path, drag/drop and selective per-plugin scan; no blanket auto-scan at startup. Do not invent arbitrary publisher/vendor/genre whitelists or arbitrary size/count caps for the user's catalog. Real-time simultaneous instance capacity is bounded by tested graph/resources and must be exposed honestly, not confused with library collection capacity.
  4. Two import choices, accessible to all: Load in Place (reference user's current VST location) and Copy to Workspace (keep original VST3 whole bundle/file + its resources under Studio/Plugins/VST3). A user with only 3 plugins should be able to add exactly those 3, save performance, and subsequently start without discovery of other system plugins. Import failures provide actionable technical diagnostics; no preemptive exclusion solely based on vendor identity or arbitrary catalogue policies.
  5. Fast known-performance start: persist a compact metadata index of explicitly imported plugins (plugin format, stable processor/class UID + variant, original path, logical workspace-relative path, SHA256/fingerprint/size, last good scan, usage); on startup read index, resolve only plugin IDs referenced by the last chosen Performance, instantiate needed plugins once in a prepared non-RT phase; re-inspect binary only when fingerprint changes or the user invokes Refresh. No global rescan, no reenumerating thousands of installed VSTs, no scan in audio callback, no load of unused plugins.
  6. Truly relocatable workspace: root-relative manifest references, not absolute C:\Program Files... or flash-drive letter, for locally bundled assets. Moving USB folder between D: and F: preserves plugin resolution, presets, snapshots, selected FX order, bypass, mixer controls and compatible states. Portable marker is an opt-in storage location choice only, not another application edition. Multiple self-contained workspaces/profiles can coexist. Device backend/ASIO-specific settings are machine-local preferences and require an explicit safe route check.
  7. Session = performance set, not just saved UI: named scenes, chained FX states, VST vendor state blobs (JUCE getStateInformation/setStateInformation), parameter/bypass/mixer gain/PAN/master/mute/mono state, and snapshots stored transactionally inside Workspace. v2 manifests migrate existing .armix v1 without silent data loss. Mark missing plugins clearly, preserve non-destructive partial recovery, and never substitute a random plugin just because its display name matches.
  8. Open extensibility: Current implemented host format is Windows x64 VST3; its importing/copying is the first implementation, not the product's permanent format ceiling. Define a format adapter boundary so VST2 (if an SDK/legacy host arrangement is legally and technically available), CLAP, instruments, multi-I/O and other supported plugin formats can be added without rewriting Workspace/Performance. Don't falsely advertise formats or MIDI/instrument/multi-channel routing the current engine cannot execute.
  9. Be transparent, not paternalistic: A plugin may depend on separate runtime, library, activation or sample library on the destination PC. Display 'Requires Setup' or 'Missing Dependency' and let the user fix paths/install dependencies; copying a plugin is not a license bypass or guarantee of cross-PC activation. No automatic uploading of user plugins, vendor license files or activation credentials. The application does NOT impose arbitrary licensure filters on its generic import functionality.
  10. OBS-like workflow: manage scene/performance libraries, move between preset states and plugin chains easily, allow save/copy/export/import via UI. During performance, don't scan, copy, hash, archive, open filesystem or instantiate third-party plugins on the real-time callback. Use bounded non-RT load phases and safe graph swapping. Small setups should start quickly, user chooses scan/refresh explicitly.

Audited native baseline on current main (2026-10-27)

  • src/PluginCatalog.h: importVst3(file) scans metadata for a selected .vst3 but does not copy its contents to the application. Catalog plugin-catalog.json persists absolute source paths and custom scanning folders.
  • src/NativePresetArchive.h: .armix ZIP with real VST3 binary state+hash, but v1 manifest stores fx.path as absolute path; this breaks relocating USB workspaces.
  • src/LiveAudioEngine.h: restoreSnapshot currently checks juce::File(fx.path).exists() and instantiates from the same absolute path; the runtime has only one actual native channel with up to 8 FX in present implementation, while 10 strips appear in user-approved GUI.
  • src/Main.cpp: catalog, presets, diagnostics and audio setup are under Windows AppData, and WebView2 runtime cache separately under AppData.
  • web/app.js: some cosmetic/UI snapshots use browser localStorage, so durable portable settings must be controlled by native workspace storage; no requirement that one browser profile follows a copied USB directory.

This is architecture and acceptance specification, NOT an implementation claim. Avoid bulk code changes or GUI redesign without a focused PR and tests.

Recommended component boundaries

  • WorkspaceLocator: installed/portable storage roots (same feature set); native data dir resolver; no cross-device absolute paths; read-only/corruption fallback.
  • PluginVault: import selected plugin file/folder, atomic staging/copy, recursive bundle resources, optional hash/dedupe, integrity, multiple versions, explicit no-global-scan startup; safe control-plane ops. Support "Load in Place" as first-class too.
  • PluginIndex/Resolver: indexed format/class/plugin identity/fingerprint, drive-letter-independent path, app-local preferred when explicitly saved, no arbitrary plugin count limit, missing-dependency UI.
  • PerformanceStore: user-named Performance/Scenes, .armix v2 manifests + migrations, snapshots, FX chain/vendor state, save-before-travel and direct open.
  • PerformanceLoader: selective fast load of only plugin IDs needed by performance; staged instantiation/graph plan with generation fences, no RT scan, safe route check.
  • StudioExporter: everyone can export their own app+workspace and later move it, while public GitHub Actions always packages the SAME executable with a blank workspace (no user files, no personal VST state).
  • PluginFormatAdapter: VST3 first and extensibility points for other plugin formats. Do not hardcode VST3 forever into the workspace schema.

Testable acceptance gates

  • Clean install, 3 manual VST3 imports, 3 presets, app exit and relaunch => NO full disk/system VST3 scan; only 3 specifically needed plugins resolved/loaded.
  • Move workspace from drive D: to F:, re-open exact selected performance => plugin path is resolved relative to workspace and state returns, without rescanning PC or manual file picker.
  • Two separately configured users get exactly the same feature set; new public distribution has empty vault/presets, but can import, copy and export everything.
  • Performance referencing a missing/changed plugin shows controlled actionable error, does not delete existing preset, does not crash or silently swap a plugin.
  • Whole Windows .vst3 folder bundle and single-file .vst3 supported; plugin cache fingerprint validation and optional refresh; no vendor whitelist / artificial catalog cap.
  • No scanning/copy/hash/IO/COM/third-party plugin construction on audio callback, and no new extra FIFO on DIRECT ASIO.
  • Portability across different PCs is conditional on third-party plugin runtime/activation and target device driver: show 'Requires Setup' when necessary; no false fully portable claim.
  • Performance state files and user personal binary data are never committed to public GitHub releases automatically.
  • Execute Windows MSVC+CTest+Chromium gates, isolated plugin scan crash tests, real plugin load/state roundtrip and physical live FAT before declaring deployment ready.

External source rationale

Sequencing

P1 Native Workspace root + opt-in portable marker + backward-compatible storage; P2 manual VST copy/load-in-place + narrow index; P3 selective instant reopen; P4 state portability/migration/scene manager; P5 all-user portable exporter and public-clean packaging; P6 physical FAT. All phases preserve parity of app features for every user.

Activity

  1. masarray commented on Oct 27, 2026

    @masarray
    OwnerAuthor

    Added acceptance contract: full PC-loss disaster recovery from user's USB backup (2026-10-27)

    Product owner confirms the PRIMARY goal is backup ArSonMix to a flashdisk, replace a broken/old computer, and restore their VST collection and complete performance without having to configure it from zero. This is a requirement for every user of the same public ArSonMix app, not an owner-only/premium edition.

    Target experience: On PC A, users import/copy selected VST3 bundles into the portable workspace, save full vendor plugin state, rack ordering, bypass, mixer sessions, snapshots, logical audio routing, and plugin identity index; use BACKUP STUDIO to produce a recoverable, verifiable folder/archive on USB. On clean PC B, open RESTORE STUDIO (or launch portable executable), relocate workspace to any drive letter, verify manifest/checksums, resolve locally bundled VSTs without global scanning, stage just the required plugin instances, restore all state with a safe output gate, and let user validate the physical audio interface selection. Missing/corrupted files or plugins requiring separate runtime/activation must be explicitly listed with repair steps; NEVER silently discard saved settings or pretend third-party activation is transferable.

    Engineering acceptance: (1) end-to-end cold PC test with no original AppData, registry catalog, absolute plugin paths or WebView2 localStorage; (2) D: -> F: drive relocation; (3) restore after erasing computer-local app state; (4) assert plugin index paths are workspace-relative and only selected plugins load, no whole-machine rescans; (5) full vendor VST binary states, mixer settings, snapshots and sessions roundtrip; (6) atomic snapshot and backup with manifests, checksums, schema migrations, safe rollback/recovery from interrupted USB copies; (7) new machine ASIO/WASAPI route is selected safely without enabling wrong outputs; (8) clear reports for plugins needing Windows dependencies, activation, extra sample libraries, or unavailable plugins; (9) same import, copy, backup, restore and portable bundle UX for every public user; (10) separate clean official release excludes user-proprietary VST/state.

    Important status: this is a product acceptance contract, not a claim that backup/restore is already implemented. Current PluginCatalog.h and .armix v1 rely on absolute paths; Main.cpp uses AppData and web/app.js uses localStorage. Follow workspace/PluginVault/performance and non-RT loading milestones with deterministic tests and real clean-PC FAT.

  2. masarray commented on Oct 28, 2026

    @masarray
    OwnerAuthor

    2026-10-28 P3 verified native Studio backup MERGED

    Merged PR #116 -> main@bed6fc78596c6c3925a80b39c27263af69b2ba2d on top of latest P1A–P1D 10-channel routing/mono-stereo/send contracts, current Orbit controls and lean CI. No audio callback / ASIO DIRECT DSP changes.

    Delivered for every public ArSonMix user: MY SOUNDS -> mute output -> BACKUP STUDIO TO USB / FOLDER. A non-audio worker copies real EXE + portable marker + native Studio/plugin Vault VST3 bundles and resources + cached catalog + .armix vendor-state presets + user assets into a new versioned USB folder. The folder is staged invisibly, files source-vs-copy hashed SHA256, entire folder independently reverified against manifest for paths, sizes, duplicate/unmanifested files, corruption and Windows reparse points; only then same-volume commit. Previous backups are never overwritten. Block backup while an import/FX graph transition is underway or output is active, to protect live audio from USB I/O. Users choosing LOAD IN PLACE get explicit count of nonportable external catalog plugin references.

    Exact head CI: Windows 40605311929 87/87 Node contracts, 37/37 native CTest incl VerifiedPortableStudioBackup, FAT_RELEASE_ACCEPTED for authentic x64 GUI release ZIP; Chromium 40605312353 PASS; reviews clean.

    Honest constraints / NOT yet done: GUI-only browser localStorage scenes and snapshots are not captured in this native backup; users should save a native .armix before backing up. Full native GUI/session/snapshot v2 migration is P4. Non-destructive GUI RESTORE with preflight, rollback and selective plugin dependency handling is P5. Third-party VST license activation/external sample libraries and target ASIO drivers can still need setup; backing up binaries is not an activation bypass. The actual ten-channel DSP runtime and physical hardware crackle FAT have not been certified by this backup milestone. Do not claim complete no-configuration cross-PC recovery yet.

    Next work: P4 authoritative native persistence of all mixer sessions/scenes/snapshots (away from browser localStorage), P5 RESTORE STUDIO with dry-run/checksums/rollback and safe device selection, then Windows cross-PC real VST FAT. Maintain same app features for all users and no full system startup VST scan.

  3. masarray commented on Oct 30, 2026

    @masarray
    OwnerAuthor

    G5E — native VST3 Show SAVE/RECALL implementation, 2026-10-30

    PR #197 HEAD 56348ff92fbdd525c040395684ae88b50b2eb64c (draft pending native validation).

    New functional vertical slice for existing native 10 input + 4 stereo AUX mixer graph, not a second DSP engine:

    • Exact native device/route epoch+revision/MUTE fencing, real per-VST3 getStateInformation on CONTROL with the same nonblocking processing flag used by RT. Fail-closed at first busy/missing vendor instance. Preserves slot order/bypass and exact catalog UID; SHA256 dedup + immutable Studio/Shows commit with complete readback.
    • Native IO worker loads and revalidates every referenced binary SHA-256, checks generation HEAD stability, transfers bytes through one shared result rather than copying 128MB via JUCE callback.
    • RECALL checks physical sparse ports and catalog UID; prepares new VST3 instances and loads vendor state before publishing via existing RealtimeRoutePublisher. No setStateInformation on audible old processors. Any failure leaves old graph unchanged; output never auto-unmutes. State byte arrays are borrowed for the synchronous APPLY to avoid a second 128MB copy.
    • UI SHOW SAVE/BROWSE/RECALL now accepts routed VST3 (but not legacy CH1 separate host); removed accidental duplicate SAVE click/ACK handlers. No heavy DOM effects or second audio callback.
    • Native regression tests: mock JUCE get/set vendor state, SHA binary readback, missing blobs rejection, FX-bearing Show control decode and positive/negative safeguards. Exact-head Chromium run 41049578950 SUCCESS; Windows MSVC/CTest 41049579022 currently building, NOT YET MERGED.

    Limits/release gates: legacy CH1 rack remains a separate FX architecture, dynamic channel DYN0 roster not yet DYN1 native PCM CH11+, no PDC/nonzero VST latency, no automatic third-party binary bundling (user VST Vault separate), no qualified vendor hardware or crackle FAT #15. Real vendor acceptance of JUCE setStateInformation requires empirical tests. Do not claim overall Studio One parity or release readiness on CI alone.

  4. changed the title [-]PRODUCT CONTRACT: one unrestricted ArSonMix for every user — personal VST vault + instant portable performance[/-] [+]Portable VST Vault — one unrestricted app, saved plugin state and fast session reopen[/+] on Nov 8, 2026
  5. masarray commented on Nov 8, 2026

    @masarray
    OwnerAuthor

    Reconciled 2026-11-08 (main b0cea49). The one-unrestricted-app policy is already settled, not an unfinished decision about public/private editions. #446 integrated FactoryFX intake; #459 delivered tri-OS native packages. Remaining deliverable here is user-owned portable VST Vault, portable plugin/state path migration, quick session reopen without a broad rescan, clean public packaging and persisted show/session recovery. Factory plugin packaging/identity and licensing is tracked in #185, scoped Show/Scene recall in #180. Leave this as a concrete residual capability tracker, not a reopening of the settled product contract.

  6. changed the title [-]Portable VST Vault — one unrestricted app, saved plugin state and fast session reopen[/-] [+][P1][BACKLOG] Portable VST Vault — user-owned state and fast session reopen[/+] on Nov 10, 2026
  7. masarray commented on Nov 10, 2026

    @masarray
    OwnerAuthor

    2026-11-10 backlog scope

    The one-unrestricted-app decision is settled. Remaining work is a non-release-blocking P1 enhancement: user-owned portable plugin binary/state paths, migration, fast session reopen without broad rescans, explicit failure reporting and recovery. Keep this issue OPEN for acceptance, but it must not block core mixer startup, WIRE, ASIO, session Save/Open or hardware reliability fixes. Distinct from optional FactoryFX intake #185 and scoped Show/Scene recall #180. Classification recorded in merged #524.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions