165 lines
9.8 KiB
Markdown
165 lines
9.8 KiB
Markdown
# PLAN — Phương án A: Engine xử lý toàn chain (chuẩn DAW)
|
|
|
|
Repo: C:/Users/locpham/SonicForgeStudio (branch standalone-shm-bridge, HEAD 5ad2c68)
|
|
|
|
## 0. Chuẩn DAW phải tuân thủ (KHÔNG bỏ qua)
|
|
1. **Track insert chain serial đúng thứ tự UI**: builtin + VST3 xen kẽ đúng vị trí
|
|
người dùng kéo; slot bypass chỉ bỏ qua slot đó, không đổi thứ tự phần còn lại.
|
|
2. **Track gain/pan sau track chain**, trước khi sum vào master bus.
|
|
3. **Master insert chain serial đúng thứ tự UI**, chạy trên mix tổng.
|
|
4. **Master fader là gain cuối cùng** trước metering/hardware out (sau master chain).
|
|
5. **Live = Export**: cùng 1 engine, cùng 1 chain descriptor, cùng 1 code DSP.
|
|
6. **PDC (Plugin Delay Compensation)**: plugin khai latency → track được align
|
|
(đã có sườn `_track_latency_samples` render_engine.py:286; live chưa có).
|
|
7. **Gain staging rõ**: track input → chain → gain/pan → sum → master chain → fader.
|
|
8. **Mono/Stereo**: SF/mono track được pad thành stereo tại input engine; mọi xử
|
|
lý stereo 2ch (bridge hiện đã stereo).
|
|
|
|
## 1. Kiến trúc đích
|
|
WebAudio chỉ còn I/O shim; mọi DSP (builtin + VST3) chạy trong `fx_vst_bridge`:
|
|
|
|
```
|
|
track instrument (SF/audio-clip) ─► [worklet track: capture raw]
|
|
│ WS/SHM
|
|
▼
|
|
fx_vst_bridge: TRACK CHAIN (builtin DSP C++ + VST3, đúng thứ tự) + PDC
|
|
│ WS/SHM
|
|
▼
|
|
WebAudio: track gain/pan ─► masterBus.input (sum)
|
|
│ [worklet master: capture sum]
|
|
│ WS/SHM
|
|
▼
|
|
fx_vst_bridge: MASTER CHAIN (builtin DSP C++ + VST3, đúng thứ tự)
|
|
│ WS/SHM
|
|
▼
|
|
WebAudio: master fader ─► analyser ─► ctx.destination
|
|
```
|
|
|
|
- Chain descriptor DUY NHẤT `{type, path?, preset_b64?, params?, bypass}` cho cả
|
|
track lẫn master, live lẫn offline.
|
|
- Engine dùng chung 1 code path: realtime loop (SHM) và `--render-fx` (WAV)
|
|
cùng `BuiltinFxChain` + `RealtimeFxChain`.
|
|
|
|
## 2. Hiện trạng (đã xác minh)
|
|
- Bridge realtime `RealtimeFxChain` (RenderFxJob.cpp:1051-1190) CHỈ VST3,
|
|
in-place, SEH-guarded, worker thread swap chain. Không builtin DSP.
|
|
- `--render-fx` slots chỉ nhận `vst3` + `builtin`(gain/normalize) — native_render.py:219-234.
|
|
- Frontend master: builtin chain chạy WebAudio (MASTER_MODULE_IO graph,
|
|
app.jsx:1261-1310, rebuildMasteringGraph:1839); VST gom cuối qua fxRtStart:1682,
|
|
worklet sau fader (output→worklet→analyser) — SAI: VST sau fader + order cố định.
|
|
- Frontend track: builtin FX WebAudio (createFXModule:1450-1520, fxMods/sfMods
|
|
app.jsx:23058-23104), VST splice SAU builtin (fxRtTrackSplice:23250-23270) —
|
|
order cố định, bỏ qua vị trí UI.
|
|
- Offline render_engine.py: track `fx_chain`(Python DSP eq/eqpro/comp/lim/exciter/
|
|
rebalance — KHÔNG có imager/maximizer) → `vst_fx_chain`(bridge); master chỉ
|
|
`master.fx_chain` = vstFxChain từ app.jsx:11409 → **builtin master chain
|
|
imager/maximizer KHÔNG áp dụng offline** → live ≠ export.
|
|
- Worklet sf-fx-realtime.js: gom 128→256 block, WS round-trip, outQueue drop >32.
|
|
- Python builtin DSP: `_apply_builtin_fx_chain` (render_engine.py:228-260) —
|
|
6 loại; JS WebAudio: 8 loại (MODULE_META app.jsx:13457-13468).
|
|
- PDC: chỉ offline skeleton, plugin chưa báo latency (0).
|
|
|
|
## 3. Các bước
|
|
|
|
### Phase 1 — Chain descriptor + protocol hợp nhất
|
|
- Đặc tả JSON: slot = `{type: vst3|eq|eqpro|imager|maximizer|compressor|limiter|
|
|
exciter|rebalance, path?, preset_b64?, params?, bypass, active}`. `active:false`
|
|
= tắt hẳn (UI), `bypass` = bỏ qua slot giữ nguyên order.
|
|
- job.json realtime + render-fx nhận chain hợp nhất (thay `fx_chain` cũ).
|
|
- Thêm protocol: `SET_PARAM {slot, key, value}` (realtime builtin automation),
|
|
`REPORT_LATENCY {slot, samples}` → engine track align (PDC).
|
|
- Update `_chain_json_for_bridge` fx_realtime.py:33 + native_render.py:230 + job.
|
|
|
|
#### Chain slot JSON (đặc tả chính thức — chuẩn cho live + offline)
|
|
```json
|
|
{
|
|
"type": "vst3|eq|eqpro|imager|maximizer|compressor|limiter|exciter|rebalance",
|
|
"path": "C:/.../plugin.vst3", // bắt buộc khi type=vst3
|
|
"preset_b64": "", // vst3: preset nội bộ (base64)
|
|
"params": { }, // builtin: tham số DSP (xem bảng dưới)
|
|
"bypass": false, // bỏ qua slot khi process, GIỮ vị trí
|
|
"active": true // false = slot bị tắt hẳn (UI xóa khỏi
|
|
// chain payload trước khi gửi engine)
|
|
}
|
|
```
|
|
Tham số builtin (khớp Python `_apply_*` + JS `MASTER_MODULE_IO`):
|
|
| type | params |
|
|
|---|---|
|
|
| eq | `g1..g4` dB (lowshelf100/peaking800/peaking3200/highshelf10000) |
|
|
| eqpro | `amount` 0-200, `bands[]` {type,freq,q,gain,active} (RBJ) |
|
|
| imager | `w1..w4` width 4-band (JS gainLL/RL/LR/RR) |
|
|
| maximizer | `boost_db`, `ceiling_db`, `soft_clip` bool |
|
|
| compressor | `threshold` -60..0, `ratio` 1..20, `makeup` 0..12 |
|
|
| limiter | `threshold` -24..0, `ceiling` |
|
|
| exciter | `wet` 0..100, `hp_hz` |
|
|
| rebalance | `g1..g4` dB 4-band (M/S) |
|
|
|
|
Control protocol (qua WS text frame, cùng socket audio):
|
|
- Client → engine: `{"cmd":"set_param","slot":<idx>,"key":"threshold","value":-18.0}`
|
|
- Bridge → engine → client: `{"cmd":"latency","slot":<idx>,"samples":1024}`
|
|
- Engine giữ `pending_params[slot][key]` + `latencies[slot]` per-session; C++
|
|
consume ở Phase 2.8 (SHM control ring).
|
|
|
|
### Phase 2 — Bridge C++: BuiltinFxChain (8 DSP)
|
|
- File mới `native_bridge/src/BuiltinFxChain.cpp` + header, port từ Python
|
|
numpy (`_apply_eq4/_apply_eqpro/_apply_compressor/_apply_limiter/_apply_exciter/
|
|
_apply_rebalance`) VÀ JS WebAudio (imager/maximizer — MASTER_MODULE_IO graph
|
|
app.jsx:1261-1310 + applyMasteringSettings:816-935) sang C++ stereo float.
|
|
Khớp tham số: eq g1..g4 dB; eqpro bands(8, RBJ); compressor threshold/ratio/
|
|
makeup; limiter threshold/ceiling; exciter wet/hp; rebalance 4-band gains;
|
|
imager 4-band width; maximizer boost/ceiling/soft-clip.
|
|
- `RealtimeFxChain::buildChain` + `RenderFxJob` slots: nhận builtin → chạy
|
|
BuiltinFxChain trước VST3 theo đúng thứ tự array.
|
|
- SEH-guard chung; bypass giữ vị trí.
|
|
- Test golden: `native_bridge/tests/` — input WAV → C++ chain vs Python
|
|
`_apply_builtin_fx_chain` same params → so SNR (mục tiêu > 60dB hoặc
|
|
diff < 1e-4; biquad RMS khác nhau do floating — chấp nhận ngưỡng).
|
|
Thêm case: chain xen kẽ builtin→vst3→builtin verify thứ tự (vst3 dummy delay).
|
|
|
|
### Phase 3 — Engine Python: render + realtime dùng chain hợp nhất
|
|
- `render_engine.py`: track/master đọc chain hợp nhất từ session payload;
|
|
`_apply_builtin_fx_chain` Python chỉ giữ làm fallback khi RENDER_ENGINE≠bridge
|
|
(ponytail: xóa hẳn khi bridge bắt buộc). Bỏ bất đối xứng imager/maximizer.
|
|
- `fx_realtime.py`: session nhận chain hợp nhất, chuyển SET_PARAM/REPORT_LATENCY;
|
|
master + track session chung protocol.
|
|
- PDC offline: đọc `latency_samples` từ slot → align (render_engine.py:333 đã có
|
|
pre-scan — nối với REPORT_LATENCY).
|
|
|
|
### Phase 4 — Frontend: WebAudio chỉ I/O
|
|
- Chain model: 1 mảng duy nhất `chain` (builtin + vst3 theo UI order). Bỏ tách
|
|
`vstFxChain`/`vstBypass`/`vst_fx_bypass` (giữ backward: project cũ có
|
|
vstFxChain → merge vào chain theo vị trí cũ: builtin → vst, đánh dấu migration).
|
|
- Master: xóa MASTER_MODULE_IO graph + rebuildMasteringGraph node-web; thay 1
|
|
worklet master (`masterBus.output` → worklet → fader gain → analyser → dest).
|
|
Fader (masterBus.output) chuyển SAU worklet — đúng chuẩn #4. applyMastering
|
|
param thay bằng SET_PARAM push.
|
|
- Track: `rebuildTrackFxGraph` bỏ fxMods/sfMods WebAudio builtin (giữ
|
|
gain/panner/analyser); 1 worklet track ở chain input, engine trả chain output
|
|
→ legacy chorus/reverb (nếu còn) → gain/pan → masterBus.input.
|
|
- `fxRtChain()`/`fxRtTrackChain()` đọc chain hợp nhất; `chainKey` so toàn chain
|
|
(không chỉ VST) → restart session khi đổi thứ tự/param builtin.
|
|
- Worklet: thêm `SET_PARAM` forward + queue drop → adaptive (ponytail), giữ cap.
|
|
|
|
### Phase 5 — Verify (chuẩn DAW checklist)
|
|
1. Build frontend `node build.mjs` OK.
|
|
2. pytest tests/ (render_engine golden so bridge; plugin_api; fx_realtime).
|
|
3. Golden: export WAV offline vs live capture (record masterBus) — diff < ngưỡng
|
|
(live=export, chuẩn #5). Có test g2_bridge_smoke mẫu.
|
|
4. Order test: chain [eq, vst3-delay, limiter] — verify delay chỉ áp sau EQ
|
|
(impulse response), không gom cuối.
|
|
5. Fader test: master chain active, fader -6dB → đỉnh giảm đúng, chain input
|
|
không đổi (chuẩn #4).
|
|
6. PDC: plugin latency 1024 samples → track bù, xuyên pha biến mất.
|
|
7. Smoke: server + /capabilities + 1 render thật (master chain imager+maximizer
|
|
+ vst3) — trước đây offline thiếu → giờ có.
|
|
8. Commit + push standalone-shm-bridge.
|
|
|
|
## 4. Rủi ro / quyết định
|
|
- **Latency live**: +1 round-trip track + 1 master (~2-4 block mỗi hop). Chấp
|
|
nhận (bản chất bridge); giữ queue cap, giảm blockMs.
|
|
- **Param automation realtime cho VST3** (preset thay đổi qua GUI): hiện chỉ
|
|
preset_b64 lúc start — giữ nguyên phase này (ponytail: MIDI CC→param sau).
|
|
- **Migration project cũ**: schema vẫn nhận vstFxChain (đọc cũ) nhưng ghi chain
|
|
hợp nhất; không phá project cũ.
|
|
- **Không bỏ**: bypass giữ order, PDC, fader cuối, live=export, gain staging.
|