SonicForgeStudio/md/api_contract/ws_protocol.md

Hợp đồng realtime FX (WS + worklet) — SonicForgeStudio

Trích từ app/api/v1/plugins.py, app/core/fx_realtime.py, app/static/js/sf-fx-realtime.js, app/static/js/fx-rt-worker.js, app/static/js/app.jsx tại HEAD 7c236d4. Đây là đặc tả để port sang Rust (P1/P4).

1. HTTP (REST)

Method	Path	Body	Trả về
POST	/api/v1/plugins/fx-realtime/start	{fx_chain: [], sample_rate: 44100}	{success, session_id, ws_url, block_size, sample_rate}
POST	/api/v1/plugins/fx-realtime/stop	{session_id}	{success, stopped}
POST	/api/v1/plugins/fx-realtime/set-chain	{session_id, fx_chain}	{success, updated}
GET	/api/v1/plugins/bridge/status	—	trạng thái bridge/SHM
POST	/api/v1/plugins/render	job render offline (VST)	file kết quả
POST	/api/v1/plugins/soundfont-render	job render SF2	WAV

• block_size = 256 mẫu (FXRT_BLOCK trong FxRealtimeIPC.h).
• Auth: Bearer token hoặc ?token=; desktop loopback không token → auto admin.

2. WebSocket audio

GET /api/v1/plugins/ws/fx-realtime/{session_id}?token=...

Hướng	Kiểu frame	Nội dung
client → server	binary	2048 B = 256 frame × 2 kênh float32 interleaved
server → client	binary	như trên, đã qua chain FX
client → server	text JSON	{"cmd":"set_param","slot":n,"key":"...","value":f} · {"cmd":"latency","slot":n,"samples":n} · {"cmd":"flush"}
server → client	text JSON	{"cmd":"latency","slot":n,"samples":n} · {"cmd":"flush_done"}

Server: ws_fx_realtime() (plugins.py ~1344) — vòng lặp receive block → SHM ring → fx_vst_bridge --realtime-fx (hoặc --juce-fx) → SHM → send.

3. Worklet ↔ main thread (MessagePort)

sf-fx-realtime.js (AudioWorkletProcessor sf-fx-realtime).

Hằng số: BLOCK=256, BURST=4 (gom 4 block = 1024 mẫu/frame), FILL=40 (≈213 ms @48k), RESUME_FILL=24, CAP=64 (≈341 ms), FADE=512, HOLD_FADE=4, WRAP_FADE=256.

type	Hướng	Payload
__direct	main → worklet	chuyển MessagePort (worker↔worklet trực tiếp, bỏ main thread)
in	worklet → main/worker	{data: ArrayBuffer} 1024 mẫu stereo interleaved
out	worker → worklet	{l, r: Float32Array} block đã xử lý
started	worklet → main	phát block đầu tiên (đã đủ FILL)
clear_queue	main → worklet	{mode: 'play'|'seek'|'loop'} — wipe queue, hasStarted=false (mode play)
flush	worklet → main	yêu cầu engine xả ring stale
flush_done	worker → worklet	engine đã flush
flush_for_stop	main → worklet	dừng phát (giữ queue)
set_param	worklet → main	forward nguyên văn tới WS
latency	main → worklet	{samples} — latency chain thật
stats	worklet → main	{underruns, holds, fades, silences, capDrops, fadeIns, queueLen} (≈2 s/lần)
dbg	worklet → main	{tag, t, ...}: fx_in_first, fx_out_first, fx_play_first, fx_seek_first, fx_loop_clear, fx_seek_clear, fx_wrap_xfade
dbg_state	main → worklet	yêu cầu snapshot trạng thái nội bộ
dbg_state_r	worklet → main	{k, t, q, playing, hasStarted, silenced, flushPending, stopped, wrapMode, wrapFadeBlocks, latencySamples, resumeFill, inCount, outPos, fadeLeft, holdFadeLeft}

4. Đồng bộ playhead / PDC (phía UI, app.jsx)

• FX_RT_WET_LAG_SAMPLES = 10240 (= FILL 40 × 256) — độ trễ nội dung khi vào FX path.
• pdcDelay.delayTime = 10240/sr khi FX active, 0 khi dry (fxRtApplyPdc).
• Crossfade dry↔wet: masterFxDryGain / masterFxGain rampe setTargetAtTime(tc=0.025).
• fxRt.crossfade(token) bất biến: dryGain + fxGain = 1.
• Warm bypass: giữ session/node/ws khi PWR OFF giữa lúc play (fxRtWarmPlayHold).

5. Ghi chú cho bản Rust (P4)

Hợp đồng tối thiểu cần giữ để frontend không phải sửa:

1. POST /fx-realtime/start → session_id + ws_url, block_size=256.
2. WS binary 2048 B/bản tin, text JSON 3 lệnh (set_param, latency, flush) + 2 phản hồi (latency, flush_done).
3. Thay hop Python bằng Rust: worklet → Tauri IPC/Rust → SHM, giữ nguyên SHM layout với fx_vst_bridge.