First commit
This commit is contained in:
@@ -0,0 +1,206 @@
|
||||
# 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.
|
||||
|
||||
Reference in New Issue
Block a user