First commit

TESTING.md

@@ -0,0 +1,218 @@
+# 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