DESKTOP INSTALL PLAN — SonicForge Studio (bản cài trực tiếp trên OS)

Mô hình: server chạy nền trên máy người dùng (localhost), client mở bằng browser. Không cần Electron — tận dụng stack hiện có (FastAPI + static JS precompiled). Soundfonts do người dùng tự tải vào thư mục riêng và khai báo cho ứng dụng.

1. KIẾN TRÚC

┌─────────────────────────── NGƯỜI DÙNG (1 máy) ───────────────────────────┐
│  Browser ──http://127.0.0.1:8000──▶ FastAPI (uvicorn, chạy NỀN)          │
│                                        │                                 │
│  ~/SonicForgeStudio/                    ├─ data/    (DB, uploads, cache) │
│   ├─ data/sonicforge.db                 ├─ soundfonts/ (user tự bỏ .sf2) │
│   ├─ soundfonts/*.sf2/.sf3              └─ quét nền 30s (scanner có sẵn) │
│   └─ config.json  ← khai báo folder soundfont                            │
└──────────────────────────────────────────────────────────────────────────┘

2. ĐÓNG GÓI CÀI ĐẶT (per-OS) — server nền + browser client

Thành phần đóng gói

Thành phần	Vai trò
Python backend (`app/`, `requirements.txt`)	Server — PyInstaller `--onedir` → binary (không cần Python trên máy user; bảo vệ source tốt hơn so với chạy .py)
`app/static/` (precompiled.js + css + vendor)	Client — đóng vào package, server phục vụ
VST3 plugins (`vst_plugins/`)	Copy theo platform (win .dll / mac .vst3 / linux .so)
Service wrapper	Tự khởi động server nền + mở browser khi login

Cài đặt + service nền theo OS

OS	Installer	Service nền	Auto-open browser
Windows	Inno Setup (`.exe`)	Windows Service qua `NSSM`/`WinSW` hoặc Task Scheduler (logon)	`start http://127.0.0.1:8000`
macOS	`.dmg` + `.app` (PyInstaller)	`launchd` LaunchAgent (`~/Library/LaunchAgents`)	`open http://127.0.0.1:8000`
Linux	`.deb` / `.AppImage`	systemd user service (`~/.config/systemd/user/`)	`xdg-open http://127.0.0.1:8000`

Server bind 127.0.0.1 (không lộ mạng), port mặc định 8000 (config được).
App gồm 2 tiến trình nhỏ: web (uvicorn) + worker (celery) — hoặc gộp worker vào web ở chế độ desktop (đơn giản: --pool=solo, chạy celery trong tiến trình riêng nếu cần render nặng).

3. THƯ MỤC DỮ LIỆU NGƯỜI DÙNG

~/SonicForgeStudio/
├── data/            # DB, uploads, processed (thay app/storage khi chạy desktop)
├── soundfonts/      # USER tự tải .sf2/.sf3 vào đây (mặc định được quét)
└── config.json      # cấu hình: soundfont_dirs, port, autostart...

config.py: thêm DATA_DIR (env SFDATA_DIR, mặc định ~/SonicForgeStudio/data), SOUNDFONT_DIRS.

4. SOUNDFONT DO NGƯỜI DÙNG QUẢN LÝ (tải + khai báo)

Cơ chế hiện có (tận dụng): app/core/soundfont_scanner.py — SoundFontAutoScanner quét nền 30s /opt/daw_engine/soundfonts + storage/soundfonts → catalog → API list qua app/api/v1/plugins.py.

Việc cần làm (mở rộng):

Scanner nhận folder người dùng: constructor nhận thêm user_dirs (từ SOUNDFONT_DIRS env + config.json) — merge vào catalog (ưu tiên: user > system).
Khai báo folder — 2 cách:
- UI (chính): Settings → "Soundfonts" → nút Add folder… (chọn thư mục chứa .sf2) → lưu vào config.json → gọi scanner rescan.
- config.json (thủ công): { "soundfont_dirs": ["D:/SF", "/Users/me/sf"] }.
API: thêm endpoint POST /api/v1/plugins/soundfonts/dirs (đăng ký folder) + GET .../dirs (liệt kê) — scanner reload.
UI danh sách: hiển thị catalog (tên SF, kích thước, folder nguồn) — chọn = load vào FluidSynth (luồng có sẵn qua SonicSF.selectInstrument).
Số hóa: không upload file — server đọc trực tiếp từ đường dẫn user khai báo (không nhân đôi dữ liệu).

5. BUILD + PHÁT HÀNH

code → build.mjs (precompiled + ?v=) → PyInstaller (server binary) → đóng installer theo OS
→ ký số (tùy chọn) → phát hành (GitHub Releases / trang riêng)

GitHub Actions matrix (windows-latest / macos-latest / ubuntu-latest): test → build → installer artifact.
Installer gồm: binary server, static/, VST plugins nền tảng, script tạo service + mở browser, mặc định tạo ~/SonicForgeStudio/ lần chạy đầu.

6. CẬP NHẬT

Version check: khi mở app, gọi endpoint version (file version.json đóng kèm + so sánh remote) → thông báo bản mới + link tải installer.
Cập nhật = chạy installer mới (ghi đè, GIỮ NGUYÊN ~/SonicForgeStudio/ — data + soundfonts không đụng).
?v= cache-bust JS mỗi bản (cơ chế đã có) — browser không dính cache cũ.

7. CHECKLIST CODE CẦN LÀM

config.py: DATA_DIR, SOUNDFONT_DIRS (env + config.json)
soundfont_scanner.py: nhận user_dirs, merge catalog, ưu tiên user
API: POST/GET .../soundfonts/dirs (đăng ký/liệt kê folder) + rescan
UI Settings → Soundfonts (Add folder, Browse, list, load)
soundfontStorage.js: chuyển hướng sang catalog folder-scan (giữ upload path cho dự án cũ)
PyInstaller spec: bundle static/ + vendor (libfluidsynth wasm, vst), bind 127.0.0.1
Service wrappers: Windows (NSSM/WinSW), macOS (launchd), Linux (systemd user) + auto-open browser
Installer scripts: Inno Setup (.exe), dmg (macOS), deb/AppImage (Linux)
CI matrix build 3 OS + release artifacts
version.json + in-app update check

6.0 KiB Raw Blame History