# Hướng Dẫn Kiểm Thử SonicForge Studio

## ✅ Trạng Thái Hoàn Thành

### Đã Hoàn Thành
- ✅ **Cấu trúc thư mục** - Toàn bộ kiến trúc app/
- ✅ **Docker Configuration** - Dockerfile + docker-compose.yml
- ✅ **FastAPI Gateway** - main.py, config.py, API endpoints
- ✅ **Core DSP Engine** - analyzer.py, dsp_utils.py, audio_editor.py
- ✅ **Celery Workers** - worker.py với task definitions
- ✅ **Frontend UI** - index.html với đầy đủ Web Audio API
- ✅ **Python Syntax** - Tất cả files đã validate

### Tính Năng Đã Triển Khai

#### Frontend (index.html)
- 🌊 Waveform visualization với HTML5 Canvas
- ⏯️ Audio playback controls (Play/Pause/Stop)
- 🔊 Real-time volume control với gain node
- 📍 Marker system với drag & drop
- 🎯 Client-side Zero-Crossing detection
- 💾 WAV Encoder (8/16/24-bit PCM)
- 📤 File upload với progress tracking
- 📊 Real-time status logging

#### Backend API
- `POST /api/v1/audio/upload` - Upload audio files
- `GET /api/v1/audio/tasks/{task_id}` - Check task status
- `POST /api/v1/audio/edit` - Apply server-side editing
- `GET /api/v1/audio/download/{file_id}` - Download processed files

#### Core DSP Modules
- **analyzer.py** - Librosa BPM/Beat tracking với Dynamic Programming
- **dsp_utils.py** - Zero-crossing detection, Micro-fading
- **audio_editor.py** - Cut, Loop, Fade, Volume operations

## 🚀 Cách Chạy Hệ Thống

### Option 1: Docker (Khuyến Nghị)

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

# Chạy ở background
docker compose up -d --build

# Xem logs
docker compose logs -f

# Dừng services
docker compose down
```

Truy cập: **http://localhost:8000**

### Option 2: Local Development

```bash
# 1. Cài đặt Python dependencies
pip install -r requirements.txt

# 2. Khởi động Redis (terminal riêng)
redis-server

# 3. Khởi động FastAPI (terminal riêng)
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 4. Khởi động Celery Worker (terminal riêng)
celery -A app.tasks.worker.celery_app worker --loglevel=info
```

## 🧪 Kịch Bản Kiểm Thử

### Test 1: Basic Audio Loading
1. Mở http://localhost:8000
2. Click "Choose File" và chọn file audio (MP3/WAV)
3. File sẽ load và hiển thị waveform
4. Kiểm tra thời gian hiển thị đúng

### Test 2: Playback Controls
1. Load audio file
2. Click Play - audio phát
3. Click Pause - audio tạm dừng
4. Click Play lại - tiếp tục từ vị trí pause
5. Click Stop - reset về đầu

### Test 3: Volume Control
1. Load và play audio
2. Kéo slider Volume từ -20dB đến +20dB
3. Kiểm tra âm lượng thay đổi real-time

### Test 4: Server Upload & Analysis
1. Load audio file
2. Click "Upload to Server"
3. Đợi upload hoàn tất (hiển thị file_id)
4. Click "Analyze Audio"
5. Kiểm tra kết quả BPM, beats, bars

### Test 5: Zero-Crossing Detection
1. Load audio file với waveform hiển thị
2. Click "Add Marker" (tạo marker tại vị trí current time)
3. Click "Snap to Zero-Crossing"
4. Marker sẽ di chuyển đến điểm zero-crossing gần nhất
5. Kiểm tra status log để xem thời gian chính xác

### Test 6: Server-side Editing
1. Upload file lên server
2. Add 2 markers (start/end cut points)
3. Snap markers to zero-crossing
4. Điều chỉnh:
   - Loop Count: 2
   - Fade In: 500ms
   - Fade Out: 500ms
   - Volume: +3dB
5. Click "Apply Edit (Server)"
6. Đợi processing complete
7. Download file đã edit

### Test 7: WAV Export (Client-side)
1. Load audio file
2. Chọn bit depth (8/16/24-bit)
3. Click "Export WAV (Client)"
4. File sẽ download tự động
5. Mở file bằng audio player để kiểm tra

## 🐛 Known Issues

### Docker Environment
- Module `celery`, `redis`, `librosa`, `pydub`, `soundfile` chưa được cài trong môi trường hiện tại
- **Giải pháp**: Sử dụng Docker để chạy (tất cả dependencies đã có trong Dockerfile)

### Browser Compatibility
- Web Audio API yêu cầu user interaction trước khi play
- Safari có thể cần format audio khác
- **Giải pháp**: Test trên Chrome/Firefox

## 📋 Checklist Kiểm Thử Đầy Đủ

- [ ] Docker build thành công
- [ ] Redis container chạy
- [ ] FastAPI web container chạy
- [ ] Celery worker container chạy
- [ ] Truy cập http://localhost:8000 thành công
- [ ] Load audio file và hiển thị waveform
- [ ] Play/Pause/Stop hoạt động
- [ ] Volume control real-time
- [ ] Upload file lên server
- [ ] Server analysis trả về BPM/beats
- [ ] Zero-crossing detection hoạt động
- [ ] Server editing hoàn tất
- [ ] Download file processed
- [ ] Export WAV client-side
- [ ] Kiểm tra không có audio glitch/pop

## 🔍 Debugging

### Kiểm tra logs
```bash
# Web server logs
docker compose logs web

# Celery worker logs
docker compose logs worker

# Redis logs
docker compose logs redis

# All services
docker compose logs -f
```

### Kiểm tra containers
```bash
# List containers
docker compose ps

# Enter container shell
docker compose exec web bash
docker compose exec worker bash
```

### Kiểm tra storage
```bash
# Uploaded files
ls -la app/storage/uploads/

# Processed files
ls -la app/storage/processed/
```

## 📊 Performance Metrics

### Mục Tiêu
- Upload file 10MB: < 5s
- BPM Analysis: < 10s
- Zero-crossing detection: < 100ms
- Waveform rendering: < 500ms
- Audio playback latency: < 50ms

## 🎯 Next Steps

Sau khi test cơ bản hoạt động:
1. Stress test với file > 100MB
2. Concurrent user testing
3. Memory leak detection
4. Audio quality testing (THD, SNR)
5. Cross-browser compatibility
6. Mobile responsive testing

## 📞 Support

Nếu gặp vấn đề, kiểm tra:
1. Docker daemon đang chạy
2. Port 8000, 6379 không bị chiếm
3. Đủ RAM (tối thiểu 4GB)
4. FFmpeg installed trong container
5. Browser console không có errors