SonicForgeStudio/PLAN_REPLACE_PEDALBOARD_NATIVE_BRIDGE.md

PLAN: thay pedalboard (GPL-3.0) bằng native_bridge — render VSTi offline

Ngày: 2026-08-15 Trạng thái: HOÀN THÀNH — Phase 0-4 xong; Phase 5 xong (RENDER_ENGINE mặc định bridge; gỡ pedalboard khỏi requirements.txt + source (vst_engine/render_engine/plugins/runtime); midi_events_to_messages giữ làm utility thuần; LICENSE.md + THIRD_PARTY_LICENSES.md bỏ cảnh báo GPL-3.0; tests 114 pass, 0 skip). Docker image build chưa test được (máy không có docker) — recipe verify qua WSL.

1. Mục tiêu

Xóa dependency GPL-3.0 (pedalboard) khỏi cả 2 môi trường, chuyển toàn bộ render VSTi offline (preview quick_render, /midi-render, export session) sang host native_bridge (MIT) — GIỮ NGUYÊN luồng nghiệp vụ + play âm thanh:

• Docker: client play = FluidSynthWASM (không đổi); server preview/export = native_bridge Linux (thay pedalboard).
• Standalone: realtime play = Tauri + bridge SHM (không đổi); Python sidecar preview/export = native_bridge Windows (thay pedalboard).

Realtime play KHÔNG dùng pedalboard hôm nay → không bị đụng.

2. Hiện trạng dùng pedalboard (cần thay)

Chỗ	Chức năng	Đường
app/api/v1/plugins.py:878-953 _render_midi_notes_pedalboard	preview quick_render + /midi-render: MIDI clip → WAV	VST3Plugin(midi_messages, duration)
app/core/render_engine.py:215-271	export session track VSTi	vst(midi_messages, duration) + apply_preset_to_plugin
app/core/render_engine.py:383-404	track FX chorus/reverb	Pedalboard([Chorus/Reverb]) — đã có fallback scipy
app/core/vst_engine.py:516+ DecentSamplerManager	Pianobook .dspreset	create_decent_sampler_instance
app/core/vst_engine.py:482-503 midi_events_to_messages	note events → raw MIDI bytes	dùng pedalboard.midi_utils (chỉ format bytes — bridge đã hiểu 0x90/0x80/0xB0/0xC0)
engine.spec:92-97	bundle pedalboard vào desktop	PyInstaller

app/core/runtime.py:377 — feature flag preview_mode=quick_render dựa trên find_spec("pedalboard").

3. Kiến trúc đích

3.1. Bridge thêm offline render mode (C++, daw_vst_bridge)

Mode realtime (SHM, Tauri) GIỮ NGUYÊN. Thêm entrypoint CLI:

daw_vst_bridge(.exe) --render <job.json> --out <clip.wav>

job.json: { instrument_type, plugin_path, preset (path|base64), sample_rate, block_size, notes: [{pitch, velocity, start_beat, duration_beats}], bpm, soundfont_bank/program (SF2/SFZ) }

Luồng:

1. Parse job → tạo instrument qua NativeInstrumentEngine::create_instrument (VST3 / SF2 / SFZ — không phụ thuộc GUI).
2. Preset: .vstpreset → giải mã base64 state blob → loadSerializedState (state container VST3 chuẩn, cùng cơ chế serializeState đã có).
3. MIDI: chuyển note events → noteOn/noteOff/controlChange/programChange với sampleOffset (đã hỗ trợ) — offline, không realtime.
4. Loop processAudioBlock hết duration → gom buffer → ghi WAV (thêm WAV writer đơn giản, stdlib).
5. Exit 0/1 + log lỗi rõ (thay cho fail im lặng hiện tại).

3.2. Python client (mới, MIT)

app/core/native_render.py — spawn bridge --render, trả (out_path, duration). API giống _render_midi_notes_pedalboard để 2 endpoint + render_engine thay thế trực tiếp. Không import pedalboard. Plugin path resolve bằng logic scan có sẵn (vst_engine.py).

3.3. Chorus/Reverb (FX track)

Chuyển hẳn sang fallback scipy/numpy ĐÃ CÓ SẴN trong render_engine.py (LFO delay chorus + noise-IR reverb) — 0 code mới, MIT. Chất lượng thấp hơn pedalboard; ghi rõ ở doc, upgrade sau nếu cần (native DSP C++ riêng).

3.4. DecentSampler (.dspreset)

.dspreset là format riêng, không phải VST3 state. Lộ trình:

• Test: DS VST3 load state chứa preset (user mở DS GUI → save .vstpreset) → đường loadSerializedState xử lý được.
• Nếu không: chặn Pianobook trên nền không có pedalboard + hướng dẫn convert .dspreset → .vstpreset. KHÔNG giữ pedalboard vì 1 tính năng phụ.

4. Các phase

Phase 0 — Offline render mode C++ (Windows + Linux)

• native_bridge: thêm --render CLI + job parser + WAV writer + offline loop; unit test native_bridge/tests/ (render 1 note VST3 + 1 SFZ, assert WAV non-silent, duration đúng).
• CMake: đảm bảo build Linux (chạy thử trên máy này).
• Kiểm chứng: --render ra WAV đúng pitch/duration với plugin test.

Phase 1 — Preset .vstpreset import

• Parser base64 state → loadSerializedState; test với .vstpreset do Carla/ pedalboard export sẵn (golden file).

Phase 2 — Python client + thay preview

• app/core/native_render.py; đổi plugins.py quick_render + /midi-render sang client mới (giữ response shape cũ — UI không đổi).
• Feature flag SF_RENDER_ENGINE=bridge|pedalboard (mặc định pedalboard trong giai đoạn chuyển; đảo sang bridge sau phase 4).

Phase 3 — Export session (render_engine)

• Track VSTi: vst(midi_messages) → native_render render từng track.
• FX: bật hẳn fallback scipy (bỏ nhánh HAS_PEDALBOARD).
• Giữ nguyên kết quả WAV export + mixdown (test so sánh trước/sau).

Phase 4 — DecentSampler + Docker + bundle

• Dockerfile: build native_bridge Linux (CMake) vào image; chạy --render dưới Xvfb :99 (đã có). Không cần GUI plugin editor.
• engine.spec: gỡ pedalboard/pedalboard.midi_utils khỏi bundle.
• DecentSampler theo mục 3.4.

Phase 5 — Đảo flag + xóa pedalboard

• Mặc định SF_RENDER_ENGINE=bridge; test toàn diện 2 môi trường.
• Gỡ pedalboard khỏi requirements.txt, bỏ nhánh chết, cập nhật LICENSE.md/THIRD_PARTY_LICENSES.md (xóa dòng GPL-3.0 warning).
• Xóa file thừa (nếu có) + doc.

5. File thay đổi (dự kiến)

• Thêm: native_bridge/src/RenderJob.{h,cpp} (parse job + offline loop), native_bridge/src/WavWriter.cpp, app/core/native_render.py, native_bridge/tests/test_offline_render.py.
• Sửa: native_bridge/src/main.cpp (dispatch --render), native_bridge/CMakeLists.txt (Linux build), app/api/v1/plugins.py, app/core/render_engine.py, app/core/vst_engine.py (midi converter giữ — đã ra bytes thuần, bỏ phụ thuộc pedalboard), app/core/runtime.py (flag), Dockerfile, engine.spec, requirements.txt, LICENSE.md.

6. Giữ nguyên luồng — điểm kiểm chứng

Luồng	Docker	Standalone
Realtime play	FluidSynthWASM — không đổi	Tauri+bridge SHM — không đổi
Preview VSTi	server render WAV → client Audio — cùng shape response	cùng
Export session	cùng pipeline WAV → download	cùng
Soundfont preview	pyfluidsynth — không đổi	pyfluidsynth — không đổi

Mỗi phase: chạy bộ test hiện có (native_bridge/tests/*, API smoke) + golden WAV so sánh pedalboard vs bridge (RMS/tolerance).

7. Rủi ro + rollback

• VST3 plugin cần GUI mới process được: headless fail → log rõ, trả 501 như cũ; không phá luồng.
• .vstpreset state khác format nội bộ: phase 1 spike trước; nếu lệch, map params qua setParamNormalized (đã có đường controlChange).
• DecentSampler: mục 3.4.
• Bridge crash giữa render: subprocess exit non-zero → HTTPException rõ (cải thiện hơn pedalboard fail hiện tại).
• Rollback: SF_RENDER_ENGINE=pedalboard đảo ngược tức thì tới hết phase 4; pedalboard chỉ bị xóa ở phase 5 sau khi bridge ổn định.

8. Tiêu chí hoàn thành

• Không còn pedalboard trong requirements/engine.spec/source.
• Preview + export VSTi 2 môi trường ra WAV đúng (so sánh golden).
• Realtime play 2 môi trường không đổi (regression pass).
• LICENSE.md bỏ cảnh báo GPL-3.0.