Skip to content

[P0] First-launch real editable mixer + device-independent FX/WIRE/session (remove fake startup gate) #490

Open

Description

@masarray

Milestone B verified triage — 2026-11-17: P0 / mixer / defect / needs-repro. Classification ≠ completion of product feature or physical FAT.

Scope / release boundary: Core first-launch offline logical edit UX; current-build proof needed.

Exit criteria:

  • On fresh alpha.26 with no audio device connected, create/rename tracks, configure FX/WIRE/session, Save/Open .smix without a fake locked reference GUI.
  • After device binding/restart, reconcile exactly one logical→physical graph with truthful ACK/metering and no implicit hardware IN/ARM gate.

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


Owner-observed P0 regression (9 Nov 2026)

  1. On first opening the installed Windows application, an apparently complete fake/reference mixer appears but cannot be operated. Users assume the installed product is broken.
  2. Even after Audio I/O setup, FX insert requires hardware IN patched to at least one channel. Users cannot design FX/WIRE/channel sessions without a physical input. They must also be able to work with only the internal player.

Source-grounded audit baseline

main@381c140200d2f4ecb965183a2da1ba1e46d5d9c2; no code fix in this issue yet.

  • Native GUI assembly derives from the interactive reference Pages model in site/preview-v2/index.html (see demo state and initialization around lines 184,211,2838) and injects web/approved-native-bridge.js at the end of body via scripts/build_approved_native_gui.py:250-260. Any visible pre-native reference state must not masquerade as operative Windows controls. Note: legacy web/app.js is another demo source but not the approved native GUI assembled by this script.
  • src/Main.cpp:225-229 accepts arMixGuiReady and marks WebView as loaded; web/approved-native-bridge.js:3148-3161 sends visualReady:true,audioReady:false before native device/graph admission. Main.cpp:4619-4645 starts audio only after this handshake. GUI-ready is not session-edit-ready.
  • web/approved-native-bridge.js:1457-1474 defines deviceReady() requiring at least 1 enabled capture input, 2 outputs and accepted graph or M4. :927-939 blocks Add Track otherwise. :2934-2976 makes insert require admitted ChannelId graph or verified legacy M4 FX lease; :3120-3132 hides standalone Add FX.
  • web/approved-native-contract.js:333-335 rejects editing intents without a PCM-admitted graph. src/LiveDryRoutingLab.h:79-97 rejects a device with zero inputs, :141-148 rejects a silent session without verified physical masks, :1260-1277 requires active ChannelId PCM for insert, and :1607-1621 requires active PCM for Add Channel. src/LiveAudioEngine.h:846-855 requires an attached authorized DIRECT device for legacy VST3 edit.
  • tests/approved_native_cold_start_smoke.py:197-215 expects Add Track disabled in NEEDS_REMAP, so test coverage currently locks in the wrong product behavior for offline editing.
  • Related: dynamic channel issue P0 dynamic mixer — qualify add/delete/reorder, native FX/routing and Show persistence #192, approved GUI/native issue P0 approved /preview/ — qualify native GUI parity and authoritative PCM readback #389, draft Player PR feat(player): native virtual PCM source, first-sound routing and lock-free stereo ring #486. Preserve other draft features / release branch independently. Do not merge feat(player): native virtual PCM source, first-sound routing and lock-free stereo ring #486 as an alleged fix of device-independent authoring.

Product contract (inspired by Gig Performer virtual channels + Chameleon, Mixxx independent decks/effect chains)

Separate logical session editing from device binding and PCM playback.

  • WorkspaceReady: UI is the real editable native-backed session. From first launch, no fake FX/stored scene, no fake live meter. Channel/FX/WIRE/bus editing, Save/Open, FX catalog, internal virtual sources must work with 0 hardware inputs and even no audio device. Pending operations have real model ACK and persisted logical revision, not invented audio DSP ACK.
  • DeviceBound: physical I/O identity, available pins, sample rate, buffer, permissions are attached independently. Input assignment is optional per channel. Empty input means SILENCE, not a disabled mixer.
  • RenderReady: the single JUCE callback has compiled and installed the same logical session into an immutable native graph with prepared FX and verified channel/WIRE state. Only this level can claim real PCM, meters, monitoring and sound. Compilation can fail without discarding the user's editable session.
  • OutputAudible: requires an actual safe output path, no feedback loop, and genuinely accepted renderer; do not auto-redirect devices or unmute unsafe routes.

Implementation boundaries

  1. Create/control one authoritative MixerSessionDocument / ChannelId model from cold launch and persist its changes, independent of deviceEpoch. Initial real channel/MAIN graph and SOURCE_NONE inputs are valid without capture pins.
  2. Input and output device binding becomes a separate transition, never a prerequisite for opening plugin browser, inserting/editing FX, BUS or WIRE. Config-only transaction ACK separate from PCM-applied ACK; show precise, quiet status on actual device/FX failures.
  3. When device is bound or changed, control-worker prepares VST3 instance with negotiated rate/buffer, routes, latency compensation, native lease and one atomic publisher handoff. Audio callback must never instantiate, scan, allocate, lock, disk I/O or run browser audio. Missing vendor plugin preserves placeholder + intended state/route, never a fake processing claim.
  4. Native first paint must show genuine non-mock editing state, not preview-demo state. Distinguish GUI rendered, session loaded/editable, PCM admitted, output audible without a blocking wizard/lab mode/approval checkbox. Remove demo event listeners and demo meter motion from native entrypoint.
  5. Player (once feat(player): native virtual PCM source, first-sound routing and lock-free stereo ring #486 qualified) is a typed virtual source into the same ChannelId graph, not another renderer; Play must not require a physical capture pin or hidden ARM/MONITOR step.

Minimum acceptance

  • Fresh install, no device and zero capture pins: immediately add INPUT, GROUP, FX, set sends/WIRE, rename, adjust controls, Save/Open .smix, restart; exact logical state persists. No fake moving meters or dead clickable controls. Editor stays fully usable after unplug.
  • Output-only setup (no capture): add FX, load internal music player, Play → FX → BUS/MAIN → playback; verify real native PCM and meter evidence. No mandatory mic patch.
  • Connect ASIO later: bind real physical IN to any existing channel without replacing channel ID/FX/WIRE/presets; same ASIO output safety; replace device/period/rate and preserve session.
  • Reject missing/bad VST3 or invalid routing with a real actionable error and unchanged good state; lazy background scan, no UI/main/audio callback stall.
  • Cold launch browser smoke + native Windows process FAT for first GUI frame, no-device, output-only, live input and restart; assert edit ACK vs PCM ACK separately and verify actual native plugin effect with PCM. Keep CI selective (fast preflight, then one exact-SHA Windows qualification).

Guardrail

Do not merely set .disabled=false or rewrite errors while the underlying session owner still refuses operations. No second PCM engine, WebAudio fallback, dummy physical capture pin, forced input selection, or mandatory Monitor/ARM/START ritual.

Activity

  1. masarray commented on Nov 9, 2026

    @masarray
    OwnerAuthor

    Deep-audit supplement — 2026-11-09, implementation #491

    Current P0 milestone: draft #491, exact SHA 75e99c63a8ef46d6c361113b33f58e325848361e (fast CI green, exact-SHA Windows CTest dispatched; not certified yet).

    Additional liveness / deadlock risks discovered

    1. Startup/UI liveness is not session readiness: src/Main.cpp:225-229 accepts arMixGuiReady before PCM; timerCallback():4633-4645 calls engine_.start() synchronously on JUCE message thread. Driver scan/open can block WebView events. Its audioEngineStarted_ one-shot is set before successful start, so a failed startup never proactively retries. ConsoleApp dismisses splash on stage 2 even when startupError_ is nonempty, revealing reference mixer when underlying device/native graph is unavailable. Fix by separating startup state and true control-plane session, not by lying about visualReady.
    2. Plugin scanner shutdown can wait forever on vendor code: src/PluginCatalog.h::~PluginCatalog invokes worker_.stopThread(-1) after signalThreadShouldExit(), but scanner uses third-party VST3 metadata discovery which can hang/non-cooperate. Simply adding a finite join timeout and destroying PluginCatalog would risk use-after-free; the robust P0 repair is process-isolated VST scan + bounded process lifetime, keep owner state only on message/control thread, validate metadata and never load arbitrary vendor code on RT.
    3. Vendor VST3 instantiation/prepare may stall UI: src/Main.cpp::handleApprovedNativeControl and LiveAudioEngine::addVst3() can construct/prepare vendor processors on the message thread. A single slow plugin can freeze UI even though audio callback remains RT-safe. Prepare off-RT with validated lifetime and bounded ACK; do not migrate arbitrary vendor operations to the audio callback. When threading is incompatible, use a separate child process or plugin-specific safe fallback.
    4. Logical session remains hardware-bound: src/NativeMixerSessionDocument.h models a saved hardware binding plus graph; web/approved-native-contract.js::intent rejects without installed PCM; LiveDryRoutingLab needs an active device to publish. P0 first-launch: genuine SOURCE NONE ChannelId mixer, zero-capture output-only FX workspace #491's zero-capture output-only startup is not no-device edit support. Full P0 requires one logical ChannelId document that commits offline edits with a distinct model revision and safely compiles once device becomes available.
    5. Incorrect demo first-paint source: native bundle derives from site/preview-v2/index.html, where the embedded reference reducer seeds demo channels, catalog and meters. Native bridge injection near </body> stops demo meters/overrides interaction after its own startup; when no native state arrives, a convincing yet dead mixer remains. Startup must render real model-backed editable controls; until model has loaded, only honest lightweight initialization, no simulated FX/meters or fake authorizations.

    Workstream sequencing (not cosmetic)

    • M1 (P0 first-launch: genuine SOURCE NONE ChannelId mixer, zero-capture output-only FX workspace #491 underway) admit real silent SOURCE NONE graph on verified output-only/duplex callback, native FX/track/WIRE allowed without any microphone patch; control-plane and PCM ACK remain honest. Test zero-IN 2-OUT and untouched output safety.
    • M2 extract device-independent model authority and source-agnostic FX/routing edits; versioned offline SESSION_EDIT_ACK + later PCM_APPLIED_ACK (never conflate). Open/Save and 10→N dynamic ChannelIds must survive no hardware and restart.
    • M3 native first-frame no fake state; connect model to approved /preview/ controls, properly support embedded Player source. No new modes, wizard, manual arm, WebAudio or cloned graph.
    • M4 isolate dangerous vendor scanner/prepare, detect stalls, restart safely with durable LKG state. Hardware FAT: 0-IN, output-only Player→FX→MAIN, ASIO 1-IN, FX chain, device change/disconnect, 100 repeated opens, rapid parameter automation, plugins that fail/cancel/hang, and process shutdown.

    Merge fence: keep #491 Draft until actual Windows CTest + real GUI/PCM qualifications; do not claim #490 resolved by permitting zero physical capture alone. Never sacrifice existing approved GUI or current main release to rush this change.

  2. masarray commented on Nov 10, 2026

    @masarray
    OwnerAuthor

    P0 owner field regression — 10 Nov 2026 — PUBLIC alpha.8 NOT hardware-qualified

    Owner installed published v0.5.0-alpha.8 and reports an unusable/fake-looking reference mixer, plus ASIO/PCM pipeline regression. This supersedes previous CI-green release claims. No new tag until actual mixer startup and audio device FAT pass.

    Source root-cause audit: site/preview-v2 first runs browser reference model; arMixGuiReady was visual-only and LiveAudioEngine::start runs after that. When saved ASIO does not reopen, there is no native ChannelId PCM graph; the reference model stays on screen. #491 SOURCE NONE zero capture is already in main but cannot create a logical mixer without playback. Rebind paths also special-case ASIO4ALL and did not recover a pristine SOURCE NONE session after driver restart.

    Active focused correction: draft PR #511, 6d92bbcc77e595b55ad77dbb3049fc311d0c683a (read/write code, not a cosmetic-only issue):

    • Reversible native-only boot guard hides reference fader/meter/wire until actual callback-backed ChannelId (or verified M4 compatibility) readback; preserves public /preview/ byte-for-byte. Rejects Pages-only GUI-ready event. Native demo labels hidden.
    • Auto ASIO reattach generalized to the exact same registered driver CLSID, with verified MAIN masks/labels/rate; ASIO4ALL-only unique physical speaker recovery does NOT apply to other ASIO drivers; mute/safety fence retained.
    • Reinstalls original pristine SOURCE NONE PCM mixer when a valid same-driver ASIO callback restarts, without destroying authored FX/WIRE graph or arming speaker without verification.
    • Added Chromium first-paint, bundle, generic ASIO and restart policy regressions. Fast CI pending on exact SHA.

    Remain open / release blockers: device-independent logical mixer document editing/save/restore with no playback; native offline edit ACK separate from PCM ACK; successful fresh-install ASIO output; all-channel WIRE/BUS/FX PCM evidence; UI/driver test on affected physical Windows machine. These cannot be called done because CI compiled or reference DOM painted. Do not force hardware remapping or synthesize a fake source/meter/PCM pipeline. Avoid release controller / fat dispatch until the exact candidate passes focused checks.

  3. masarray commented on Nov 10, 2026

    @masarray
    OwnerAuthor

    Forensic correction to prior P0 assessment: Work PR #491 HEAD 3015960b is an ancestor of published alpha.8 ffdf279a; core ASIO reattach/pin policies are byte-identical. The confirmed first-paint regression is commit 0b0e637b deleting Work's native-only guard from scripts/build_approved_native_gui.py, later shipped via #503/#505. Full analysis in PR #511 discussion. Do not reimplement Work or promote draft #511 without hardware qualification.

  4. masarray commented on Nov 10, 2026

    @masarray
    OwnerAuthor

    2026-11-10 — Inherited native GUI acceptance from #389 (consolidated)

    This P0 issue is the authoritative owner for genuine first-frame/native session UX. The single approved public/native /preview/ renderer has been integrated; do not build a new GUI or revive fixed M4 reference startup.

    Acceptance inherited from #389:

    • Installed Windows application opens straight into real native-backed editable channel/FX/WIRE/Save/Open state with 0 physical capture inputs; no reference/demo controls presented as operational or fake moving meters.
    • Distinguish visual DOM ready, accepted logical edit/Save ACK, installed PCM graph and physically audible output. Every button/FX picker/route intent gets matching native ACK or explicit rejection; after acknowledgement confirm same-revision authoritative ChannelId/EdgeId/device-epoch snapshot. No optimistic browser-only graph or stale readback.
    • Verify real native vs Pages screenshot and action parity (approved PNG buttons, controls, FX slot/picker and contexts) at representative 1366×768, 1680×900 and 1920×1080, including first open/reopen, no device, output-only Player, driver loss/recovery, device swap and session restore.
    • Any mismatch is not solved by hiding the GUI or requiring a mandatory Monitor/ARM/START ritual.

    Native audio/physical WIRE and FX evidence stays separately in #412; dynamic channel lifecycle stays in #192. Full cross-issue archive: reconciliation PR #524. This transfer does not mark #490 resolved.

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