209 lines
6.4 KiB
Markdown
209 lines
6.4 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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**
|
|
|
|
## 📁 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
- [x] **Tuần 1:** Docker setup & static serving
|
|
- [x] **Tuần 2:** Web Audio Engine & waveform visualization
|
|
- [x] **Tuần 3:** Core DSP backend (Librosa + Pydub)
|
|
- [x] **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.
|