88 lines
6.0 KiB
Markdown
88 lines
6.0 KiB
Markdown
# 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):**
|
|
1. **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).
|
|
2. **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"] }`.
|
|
3. **API:** thêm endpoint `POST /api/v1/plugins/soundfonts/dirs` (đăng ký folder) + `GET .../dirs` (liệt kê) — scanner reload.
|
|
4. **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`).
|
|
5. **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
|