SonicForge Studio

Professional Web-based Audio Editor with Dockerized DSP Engine

SonicForge Studio là một hệ thống xử lý âm thanh chuyên nghiệp kết hợp giao diện Web Audio API phía client với công cụ DSP/AI mạnh mẽ trên server (Python/Celery).

🎯 Tính Năng Chính

Client-side (Web Audio API)

• ✅ Multi-track playback và mixing thời gian thực
• ✅ Trực quan hóa waveform động trên HTML5 Canvas
• ✅ Zero-crossing detection để cắt âm thanh không bị "click/pop"
• ✅ WAV encoder hỗ trợ 8/16/24-bit PCM
• ✅ Offline rendering với OfflineAudioContext
• ✅ Volume control, Mute, Solo cho từng track

Server-side (Python/FastAPI/Celery)

• ✅ Phân tích BPM và Beat tracking với Librosa
• ✅ Cắt, ghép, loop audio với độ chính xác cao
• ✅ Zero-crossing alignment server-side
• ✅ Fade-in/Fade-out và micro-fading tự động
• ✅ Batch processing với Celery workers
• ✅ Volume normalization và format conversion

🏗️ Kiến Trúc

┌─────────────────────────────────────┐
│   Browser (React + Web Audio API)  │
│   - Waveform visualization          │
│   - Real-time playback              │
│   - Client-side DSP                 │
└──────────────┬──────────────────────┘
               │ REST API
┌──────────────▼──────────────────────┐
│   FastAPI Gateway (Port 8000)       │
│   - Serve static files              │
│   - API endpoints                   │
│   - Task management                 │
└──────────────┬──────────────────────┘
               │
        ┌──────┴──────┐
        ▼             ▼
┌──────────────┐ ┌──────────────┐
│    Redis     │ │Celery Workers│
│   (Broker)   │ │ - Audio DSP  │
└──────────────┘ │ - Analysis   │
                 └──────────────┘

🚀 Cài Đặt và Chạy

Yêu Cầu

• Docker & Docker Compose
• 4GB RAM trở lên
• FFmpeg (đã tích hợp trong Docker image)

Khởi Động

# Clone repository
git clone <repo-url>
cd SonicForgeStudio

# Build và khởi động tất cả services
docker-compose up --build

# Hoặc chạy ở chế độ nền
docker-compose up -d --build

Truy Cập

Mở trình duyệt và truy cập: http://localhost:8000

📦 Portable Install — thư mục install/

install/ là bản portable chạy thẳng (không cần cài đặt): install/sonicforge-daw.exe.

Thành phần	Vai trò	Trạng thái
daw_vst_bridge.exe	Native host bridge (C++, nối DAW ↔ VSTi qua shared memory)	commit sẵn (~1.4MB)
libfluidsynth-3.dll	FluidSynth runtime (SF2/SF3)	commit sẵn (~0.5MB)
sonicforge-daw.exe	Tauri app shell	commit sẵn (~10MB)
daw_engine/	Python engine (PyInstaller onedir) — ~1.8GB (tensorflow/torch/cv2)	KHÔNG commit — tự build

3 binary C++/Tauri commit sẵn để người pull không cần toolchain (VS + vcpkg + vst3sdk submodule + sfizz-src). Phần daw_engine/ quá nặng cho git — build bằng script có sẵn:

powershell -ExecutionPolicy Bypass -File build_install.ps1

Script build frontend (node build.mjs) + engine (pyinstaller engine.spec) rồi copy vào install/daw_engine/. Muốn build lại cả bridge/app từ source: powershell -ExecutionPolicy Bypass -File build_windows.ps1 (ra installer NSIS/MSI, không phải portable).

📁 Cấu Trúc Dự Án

SonicForgeStudio/
├── app/
│   ├── main.py              # FastAPI entry point
│   ├── config.py            # Configuration
│   ├── api/
│   │   └── v1/
│   │       ├── audio.py     # Audio upload/download endpoints
│   │       └── tasks.py     # Task status endpoints
│   ├── core/
│   │   ├── analyzer.py      # BPM/Beat analysis (Librosa)
│   │   ├── dsp_utils.py     # Zero-crossing, fade utilities
│   │   └── audio_editor.py  # Audio editing operations
│   ├── tasks/
│   │   └── worker.py        # Celery worker tasks
│   ├── templates/
│   │   └── index.html       # Frontend UI
│   └── storage/
│       ├── uploads/         # User uploaded files
│       └── processed/       # Server processed files
├── Dockerfile
├── docker-compose.yml
├── requirements.txt
└── DEVELOP_PLAN.md         # Detailed technical specification

🎵 API Endpoints

Method	Endpoint	Mô tả
GET	/	Giao diện Web Editor
POST	/api/v1/audio/upload	Upload audio file
GET	/api/v1/audio/tasks/{task_id}	Kiểm tra trạng thái task
POST	/api/v1/audio/edit	Thực hiện edit audio
GET	/api/v1/audio/download/{file_id}	Download file đã xử lý

🔬 Thuật Toán DSP

Zero-Crossing Detection

Tìm điểm mà biên độ sóng âm chuyển từ dương sang âm (hoặc ngược lại):

x[i] · x[i+1] ≤ 0

Micro-Fading

Tự động thêm fade 50ms tại điểm cắt để loại bỏ click/pop noise.

Beat Tracking

Sử dụng Dynamic Programming của Librosa để phát hiện nhịp chính xác.

🛠️ Công Nghệ Sử Dụng

Frontend:

• Web Audio API
• HTML5 Canvas
• Tailwind CSS
• Lucide Icons

Backend:

• Python 3.11+
• FastAPI
• Celery
• Redis
• Librosa (Audio analysis)
• Pydub + FFmpeg (Audio processing)
• NumPy + SciPy (DSP algorithms)

📊 Định Dạng Xuất

• WAV 8-bit PCM - Lo-Fi (unsigned integer)
• WAV 16-bit PCM - CD Quality (standard)
• WAV 24-bit PCM - HD Audio (professional)

🔧 Development

Chạy local không dùng Docker

# Cài đặt dependencies
pip install -r requirements.txt

# Khởi động Redis
redis-server

# Terminal 1: FastAPI
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# Terminal 2: Celery Worker
celery -A app.tasks.worker.celery_app worker --loglevel=info

Testing

Upload một file audio (MP3/WAV), thử các chức năng:

1. Playback và volume control
2. Visualize waveform
3. Add markers và snap to zero-crossing
4. Server analysis (BPM detection)
5. Apply edits (cut, loop, fade)
6. Export WAV với bit depth khác nhau

📝 Roadmap

• Tuần 1: Docker setup & static serving
• Tuần 2: Web Audio Engine & waveform visualization
• Tuần 3: Core DSP backend (Librosa + Pydub)
• Tuần 4: Client-Server integration & Celery
• Tuần 5: Testing & optimization
  • Stress testing với file lớn
  • Memory optimization
  • Audio glitch testing
  • Performance benchmarking

🤝 Contributing

Contributions are welcome! Please read DEVELOP_PLAN.md for technical details.

📄 License

MIT License - See LICENSE file for details

👨💻 Author

Developed with ❤️ by SonicForge Team

---

Note: Đây là phiên bản MVP (Minimum Viable Product). Các tính năng nâng cao như Demucs vocal separation, multi-user support, và cloud storage sẽ được bổ sung trong các phiên bản tiếp theo.