SonicForgeStudio/TESTING.md

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ị)

# 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

# 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

# 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

# List containers
docker compose ps

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

Kiểm tra storage

# 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