fix: Bug 1 keyboard preview cam lan 2+ — token race: stale check != token -> > token (claim-then-compare) trong _sfWasmFallbackNote + API path (T1)

2026-08-11 15:31:56 +07:00
parent cadb5402a3
commit aa06d40b98
4 changed files with 246 additions and 4 deletions
@@ -0,0 +1,66 @@
+# PLAN — Standalone playback 100% client-side WASM (no Carla dependency)
+
+Goal: fix "mastering fx chain không xử lí" + "vsti không qua main out" bằng cách
+chuyển live playback/preview của VSTi sang WASM (autosampled SF2 qua FluidSynth
+WASM → track sfEntry → FX chain → masterBus mastering → main out). Export WAV
+giữ nguyên backend Python (pedalboard VST3 + FluidSynth C++).
+
+## 1. Server — autosample endpoint (VSTi → SF2)
+- `tools/autosample_vsti.py`: tách core thành `autosample_sf2(...)` callable
+  (giữ `main()` argparse cho CLI).
+- `app/api/v1/plugins.py`: `AutosampleRequest` + `POST /autosample` — render
+  preset qua từng note bằng pedalboard (đúng plugin+preset như export) → SF2
+  16-bit mono vào `app/storage/soundfonts/{uuid}.sf2` + `.meta` → trả `sf_id`.
+- Chỉ SF2 (không SF3): client WASM load SF2 trực tiếp, endpoint download ưu
+  tiên SF2 sẵn có. 30-60 note ≈ 10-20MB — chấp nhận, IndexedDB cache.
+  ponytail: SF3 (OGG nhỏ hơn) khi cần size nhỏ — thêm `--sf3` vào endpoint.
+
+## 2. Server — mastering FX chain trong render_project
+- `app/core/mastering_engine.py` (mới): `apply_mastering(buffer, settings, fs)`
+  tái hiện chain WebAudio client (initMasterBus + applyMasteringSettings):
+  - `eq` (lowshelf 100 / peaking 822 Q0.7 / peaking 3200 Q1.2 / highshelf 10k)
+  - `imager` (M/S width 4 band: 20-100 / 100-1k / 1k-6k / 6k-20k)
+  - `maximizer` (boost → softclip atan → +upward comp → ceiling hard clip)
+  - `compressor` (threshold/ratio/knee/makeup)
+  - `limiter` (tanh soft clip)
+  - `exciter` (hp 2k + saturator, dry/wet)
+  - `rebalance` (M/S gains qua L/R crossfeed)
+  - chain order từ `settings['chain']`, gate `masterConnected && !isBypassed`.
+- `app/core/render_engine.py`: `render_project` đọc `project_json['mastering_settings']`
+  → áp lên master_buffer trước `sf.write`; khi có mastering → clip [-1,1]
+  (giống WAV encoder client), không mastering → normalize như cũ.
+
+## 3. Client — VSTi live playback qua WASM autosample
+- `app/static/js/services/api.js`: thêm `autosampleVsti(payload)`.
+- `app/static/js/services/vstiAutosample.js` (mới): `SonicVstiAutosample` —
+  `ensure(synthEngine)` POST autosample 1 lần, cache map plugin_id+preset →
+  sf_id (localStorage), `sfIdFor` sync lookup.
+- `app/static/js/services/soundfontPlayer.js`: `_playNoteFluid` +
+  `applyAITrackInstrument` fallback `synthEngine.autosampled_sf_id` khi thiếu
+  `soundfont_id`; VSTi chưa sample → ensure rồi defer note (pendingNoteOns có sẵn).
+- `app/static/js/services/runtime.js`: `SonicCarlaMidi.shouldRoute` /
+  `shouldRoutePlayback` trả false trừ khi `window.__enableCarlaLivePlayback`
+  (mặc định off) — playback không phụ thuộc Carla nữa.
+- `app/static/js/app.jsx`:
+  - `shouldRouteCarla` → false (VSTi đi qua SonicSF → masterBus → main out).
+  - chọn instrument VSTi (applyTrackInstrument) → fire-and-forget
+    `SonicVstiAutosample.ensure(synth_engine)`.
+  - timeline/local-loop/ghost/preview: VSTi đã chạy nhánh `SonicSF.playNote`
+    sẵn (isSfTrackEngine false → else-if); autosampled_sf_id làm nó kêu đúng âm.
+  - `ensureMidiCapture` đã capture `node.sfEntry` → VSTi vào midiCache →
+    clientSideExport (offline mix qua track FX + mastering) hoạt động cho VSTi.
+- `app/templates/index.html`: script tag `vstiAutosample.js`.
+- Build: `npm run build` (app.jsx → app.precompiled.js).
+
+## 4. Verify
+- pytest `tests/` (kỳ vọng 108 pass / 1 skip / 1 env-specific fail như cũ).
+- Test mastering: render project JSON có mastering_settings (chain eq+imager+
+  maximizer) → assert output peak ≤ ceiling & khác bản không mastering.
+- Test autosample: gọi `autosample_sf2` với VSTi (Nexus.vst3) → sf2utils parse
+  sạch; endpoint return sf_id + file tồn tại.
+- Manual (browser): track VSTi → Preview/Play → âm qua masterBus (VU master
+  nhảy), Export WAV server ra file có mastering.
+
+## 5. Commit/push
+- Commit trên branch `standalone`. Push vẫn chờ user cấu hình git auth
+  (credential.helper / token URL) — không retry khi chưa có.