SonicForgeStudio/README.md

# 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).

![SonicForge Studio UI](./app/images/SonicForgeUI.png)

## 🎯 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.