280 lines
16 KiB
Markdown
280 lines
16 KiB
Markdown
# Kế Hoạch Chi Tiết: Dockerized Music Processing Server & SonicForge Studio
|
|
|
|
Tài liệu này trình bày giải pháp kiến trúc tổng thể, lựa chọn công nghệ, thuật toán xử lý tín hiệu số (DSP/AI) ở cả phía Client (Web Audio API) và Server (Python/Celery), thiết kế API, cấu trúc thư mục hợp nhất, cấu hình Docker và lộ trình triển khai hoàn chỉnh.
|
|
|
|
---
|
|
|
|
## 1. Kiến Trúc Hệ Thống Tổng Thể (System Architecture)
|
|
|
|
Hệ thống được thiết kế theo mô hình **Lai (Hybrid Client-Server)**:
|
|
|
|
* **Client-side (SonicForge Studio):** Đảm nhận các tác vụ tương tác thời gian thực, trực quan hóa sóng âm, nghe thử đa kênh (multi-track playback), tính toán điểm dừng mềm (micro-fades), mô phỏng điểm Zero-crossing gần nhất và xuất bản trực tiếp định dạng WAV nhẹ.
|
|
* **Server-side (FastAPI Gateway & Celery Workers):** Đảm nhận các tác vụ phân tích cấu trúc phức tạp (AI Beat tracking, tách nguồn Vocal/Instrumental bằng Demucs) và các phiên xử lý hàng loạt khối lượng lớn (Batch-editing/Rendering) tệp tin âm thanh độ phân giải cao.
|
|
|
|
```text
|
|
[ TRÌNH DUYỆT NGƯỜI DÙNG (CLIENT-SIDE) ]
|
|
┌──────────────────────────────────────────────────────────────────────┐
|
|
│ React UI - SonicForge Studio │
|
|
│ ┌────────────────────────┐ ┌────────────────────────┐ │
|
|
│ │ Web Audio Engine │ │ Client-side DSP Engine│ │
|
|
│ │ (Multi-track Playback, │ │ - Zero-Crossing Snap │ │
|
|
│ │ Gain Control, Fades) │ │ - Offline Mixdown WAV │ │
|
|
│ └───────────▲────────────┘ └───────────▲────────────┘ │
|
|
└──────────────┼───────────────────────────────────────┼───────────────┘
|
|
│ (Upload Audio / Trả kết quả) │ (JSON API Config)
|
|
▼ ▼
|
|
┌──────────────────────────────────────────────────────────────────────┐
|
|
│ MÁY CHỦ BẢN TIN (SERVER-SIDE DOCKER) │
|
|
│ │
|
|
│ [FastAPI Gateway] <──(Check Task Status)── [Redis Broker / Backend] │
|
|
│ │ ▲ │
|
|
│ ├─► (Đẩy tác vụ nặng) │ │
|
|
│ ▼ │ │
|
|
│ [Celery Workers (Audio DSP & AI Engine)] ─────────┘ │
|
|
│ │ (Đọc/Ghi dữ liệu) │
|
|
│ ▼ │
|
|
│ [Shared Volume (Audio Files / Storage)] │
|
|
└──────────────────────────────────────────────────────────────────────┘
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 2. Đề Xuất Công Nghệ & Thư Viện
|
|
|
|
### 2.1. Phía Giao Diện (Frontend & Client-side DSP)
|
|
|
|
* **Thư viện lõi:** React 18 (UI quản lý trạng thái, Track, Clip và Marker), Tailwind CSS (Giao diện đáp ứng tối ưu hóa không gian tối), Lucide Icons (Biểu tượng chức năng).
|
|
* **Công cụ xử lý âm thanh:** Web Audio API (Giải mã `AudioBuffer` trực tiếp, quản lý luồng định tuyến âm thanh thông qua `AudioContext`, `GainNode`, `AnalyserNode`).
|
|
* **Offline Processing:** `OfflineAudioContext` (Hòa âm đa kênh tốc độ cao ngay trên bộ nhớ trình duyệt để kết xuất không trễ).
|
|
* **Visualization:** HTML5 Canvas API (Vẽ đồ thị sóng âm waveform động cho từng clip dựa theo tọa độ thời gian thực và phổ tần số âm thanh Master Output).
|
|
|
|
### 2.2. Phía Máy Chủ (Backend & Server-side DSP)
|
|
|
|
* **Ngôn ngữ chính:** Python 3.11+ kết hợp FastAPI phục vụ static files và APIs.
|
|
* **Thư viện phân tích & xử lý:**
|
|
* `librosa`: Phân tích Tempo (BPM), Beat-tracking chính xác, xác định cấu trúc nhịp ($Bars$).
|
|
* `pydub` & `FFmpeg`: Cắt ghép tệp gốc ở tầng nhị phân, thay đổi cao độ, âm lượng ($dB$), tạo dải chuyển tiếp fade-in/fade-out chuyên nghiệp.
|
|
* `scipy` / `numpy`: Phân tích mảng số (array processing) trên đồ thị sóng âm gốc để đồng bộ điểm Zero-crossing tinh chỉnh.
|
|
|
|
|
|
|
|
---
|
|
|
|
## 3. Giải Pháp Kỹ Thuật & Thuật Toán Đồng Bộ
|
|
|
|
### 3.1. Phân Tích Nhịp & Đồng Bộ Nhịp Client-Server
|
|
|
|
Máy chủ chạy thuật toán Dynamic Programming của `librosa` để trích xuất mốc nhịp gốc. Kết quả trả về cấu trúc JSON chứa danh sách các điểm phách (beats) và khuôn nhạc ($bars$).
|
|
|
|
Giao diện Client tiếp nhận JSON này, chuyển dịch sang hệ tọa độ Pixels dựa trên tỷ lệ thu phóng (Zoom Level):
|
|
|
|
|
|
$$\text{X Position (px)} = \text{Time (seconds)} \times \text{Zoom Level (px/sec)}$$
|
|
|
|
### 3.2. Thuật Toán Tìm Điểm Zero-Crossing (Không Tiếng "Click" Âm Thanh)
|
|
|
|
Để triệt tiêu các xung âm đột ngột gây ra tiếng "click/pop" khi ghép nối hoặc lặp (loop) âm thanh, cả Client và Server đều áp dụng cơ chế căn lề Zero-Crossing.
|
|
|
|
**Thuật toán toán học:** Tìm vị trí mẫu $i$ sao cho tích của hai mẫu liên tiếp nhỏ hơn hoặc bằng $0$ (biên độ đổi dấu từ dương sang âm hoặc ngược lại):
|
|
|
|
|
|
$$x[i] \cdot x[i+1] \le 0$$
|
|
|
|
* **Tại Client:** Để tối ưu hiệu năng kéo thả Marker cắt ngay trên trình duyệt, Client-side JS quét mảng kênh 0 (`Float32Array` từ `AudioBuffer`) trong dải thời gian lân cận điểm kéo thả khoảng $\pm 50\text{ms}$:
|
|
|
|
$$\text{Vùng quét (mẫu)} = [\text{Target Sample} - (0.05 \times \text{Sample Rate}), \text{Target Sample} + (0.05 \times \text{Sample Rate})]$$
|
|
|
|
|
|
|
|
Marker sẽ tự động được dính ("snap") vào điểm Zero-Crossing gần nhất.
|
|
* **Tại Server:** Khi nhận request API cắt ghép từ Client dưới dạng giây (seconds), module Python `dsp_utils.py` sử dụng `numpy` thực hiện phép dò tương tự trên tệp audio gốc chất lượng cao trước khi ghi đĩa.
|
|
|
|
### 3.3. Giải Thuật Fade Nhẹ Tự Động (Micro-Fading)
|
|
|
|
Khi thực hiện thao tác Cắt (Split) hoặc Ghép (Merge) đa đoạn trên một Track, hệ thống tự động chèn dải Micro-Fade thời lượng cực ngắn ($50\text{ms}$) tại điểm cắt để triệt tiêu vĩnh viễn nhiễu sóng tần số cao.
|
|
|
|
---
|
|
|
|
## 4. Thiết Kế RESTful API Endpoints Hợp Nhất
|
|
|
|
| Method | Endpoint | Description | Request/Response |
|
|
| --- | --- | --- | --- |
|
|
| **GET** | `/` | Trả về giao diện Web Editor (Tệp tin tệp tĩnh `index.html`). | HTML Response |
|
|
| **POST** | `/api/v1/audio/upload` | Người dùng upload tệp tin nhạc lên máy chủ. Trả về `file_id`. | `file: UploadFile` |
|
|
| **GET** | `/api/v1/audio/tasks/{task_id}` | Kiểm tra trạng thái phân tích nhịp từ Celery (BPM, Beats, Bars). | JSON |
|
|
| **POST** | `/api/v1/audio/edit` | Thực hiện cắt ghép nâng cao và lưu kết quả trên server. | JSON Payload |
|
|
| **GET** | `/api/v1/audio/download/{file_id}` | Tải tệp tin kết quả cuối cùng từ Server. | Binary Stream |
|
|
|
|
#### Cấu trúc JSON Request cho Endpoint `/api/v1/audio/edit` (Đồng bộ hóa trực tiếp từ Client):
|
|
|
|
```json
|
|
{
|
|
"file_id": "original_uuid_1234.wav",
|
|
"cut_start_ms": 12000,
|
|
"cut_end_ms": 24000,
|
|
"zero_crossing_align": true,
|
|
"loop_count": 4,
|
|
"fade_in_ms": 1000,
|
|
"fade_out_ms": 1500,
|
|
"volume_change_db": 3.5
|
|
}
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Cấu Trúc Thư Mục Dự Án Toàn Diện
|
|
|
|
```text
|
|
music-processing-server/
|
|
│
|
|
├── docker-compose.yml
|
|
├── Dockerfile
|
|
├── requirements.txt
|
|
│
|
|
├── app/
|
|
│ ├── __init__.py
|
|
│ ├── main.py # FastAPI Gateway (Chạy API & Phục vụ index.html)
|
|
│ ├── config.py # Biến môi trường & cấu hình hệ thống
|
|
│ │
|
|
│ ├── templates/ # Thư mục lưu trữ mã nguồn giao diện
|
|
│ │ └── index.html # File Giao diện SonicForge Studio React/Web Audio API
|
|
│ │
|
|
│ ├── api/ # Quản lý Router và Endpoints
|
|
│ │ ├── __init__.py
|
|
│ │ └── v1/
|
|
│ │ ├── audio.py # API tải lên/phục vụ tệp tĩnh âm thanh
|
|
│ │ └── tasks.py # Trạng thái tác vụ bất đồng bộ
|
|
│ │
|
|
│ ├── core/ # Các module xử lý lõi (DSP)
|
|
│ │ ├── __init__.py
|
|
│ │ ├── analyzer.py # Phân tích BPM, Beats, Bars (Librosa)
|
|
│ │ ├── dsp_utils.py # Thuật toán Zero-crossing, Fade nâng cao
|
|
│ │ └── audio_editor.py # Cắt, ghép, loop, volume (Pydub)
|
|
│ │
|
|
│ ├── tasks/ # Celery worker tasks
|
|
│ │ ├── __init__.py
|
|
│ │ └── worker.py # Định nghĩa tác vụ nền
|
|
│ │
|
|
│ └── storage/ # Thư mục lưu trữ volume chung
|
|
│ ├── uploads/ # Nhạc gốc tải lên
|
|
│ └── processed/ # Nhạc đầu ra sau kết xuất
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 6. Cấu Hình Docker & Docker Compose Phục Vụ Cả Frontend & Backend
|
|
|
|
### 6.1. File Dockerfile
|
|
|
|
Sử dụng base-image `python-slim`, tích hợp đầy đủ thư viện đồ họa và xử lý âm thanh `FFmpeg` và `libsndfile1`.
|
|
|
|
```dockerfile
|
|
FROM python:3.11-slim
|
|
|
|
# Thiết lập thư mục làm việc
|
|
WORKDIR /app
|
|
|
|
# Cài đặt các thư viện hệ thống cần thiết (FFmpeg, libsndfile)
|
|
RUN apt-get update && apt-get install -y --no-install-recommends \
|
|
ffmpeg \
|
|
libsndfile1 \
|
|
build-essential \
|
|
&& rm -rf /var/lib/apt/lists/*
|
|
|
|
# Sao chép và cài đặt Python dependencies
|
|
COPY requirements.txt .
|
|
RUN pip install --no-cache-dir -r requirements.txt
|
|
|
|
# Sao chép mã nguồn bao gồm cả thư mục templates chứa index.html
|
|
COPY . .
|
|
|
|
# Tạo thư mục chứa file nhạc và cấp quyền ghi
|
|
RUN mkdir -p /app/storage/uploads /app/storage/processed && chmod -R 777 /app/storage
|
|
|
|
# Mặc định mở port 8000 cho FastAPI
|
|
EXPOSE 8000
|
|
|
|
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]
|
|
|
|
```
|
|
|
|
### 6.2. Phục Vụ Giao Diện Từ `app/main.py`
|
|
|
|
Để tránh lỗi phân tách nguồn gốc tên miền (CORS) khi chạy riêng lẻ, FastAPI sẽ đóng vai trò phục vụ trực tiếp tệp giao diện tĩnh:
|
|
|
|
```python
|
|
from fastapi import FastAPI
|
|
from fastapi.responses import HTMLResponse
|
|
from fastapi.staticfiles import StaticFiles
|
|
import os
|
|
|
|
app = FastAPI(title="SonicForge API Engine")
|
|
|
|
# Mount thư mục lưu trữ nhạc để Client có thể stream trực tiếp
|
|
app.mount("/static/audio", StaticFiles(directory="app/storage"), name="audio")
|
|
|
|
@app.get("/", response_class=HTMLResponse)
|
|
async def get_index():
|
|
index_path = os.path.join("app", "templates", "index.html")
|
|
with open(index_path, "r", encoding="utf-8") as file:
|
|
return HTMLResponse(content=file.read(), status_code=200)
|
|
|
|
```
|
|
|
|
---
|
|
|
|
## 7. Giải Thuật Kết Xuất WAV Đa Định Dạng (WAV Encoder 8/16/24-bit)
|
|
|
|
Khi người dùng thực hiện xuất bản nhạc trực tiếp ở giao diện Frontend, họ có thể lựa chọn xuất tệp WAV với độ sâu bit và tần số lấy mẫu chỉ định. Mã nguồn Frontend mã hóa trực tiếp thông qua lớp ghi nhị phân RIFF WAVE:
|
|
|
|
* **8-bit PCM (Lo-Fi):** Biểu diễn dạng số nguyên không dấu (Unsigned Integer), dải giá trị $[0, 255]$.
|
|
|
|
$$\text{Sample}_{8\text{-bit}} = \text{round}((\text{FloatSample} + 1.0) \times 127.5)$$
|
|
|
|
|
|
* **16-bit PCM (Chuẩn CD):** Biểu diễn dạng số nguyên có dấu (Signed Integer), dải giá trị $[-32768, 32767]$.
|
|
|
|
$$\text{Sample}_{16\text{-bit}} = \text{round}(\text{FloatSample} \times 32767)$$
|
|
|
|
|
|
* **24-bit PCM (HD Audio):** Biểu diễn dạng số nguyên có dấu, 3 bytes dữ liệu $[-8388608, 8388607]$.
|
|
|
|
$$\text{Sample}_{24\text{-bit}} = \text{round}(\text{FloatSample} \times 8388607)$$
|
|
|
|
|
|
|
|
---
|
|
|
|
## 8. Kế Hoạch Triển Khai Chi Tiết (5-Week Roadmap)
|
|
|
|
### Tuần 1: Khởi Tạo Môi Trường Docker & Giao Diện Tĩnh (Static Serving)
|
|
|
|
* [ ] Thiết lập cấu trúc thư mục dự án thống nhất.
|
|
* [ ] Viết file `Dockerfile` và `docker-compose.yml` để liên kết FastAPI, Redis và Celery.
|
|
* [ ] Đưa tệp `index.html` của trình biên tập SonicForge Studio vào thư mục `app/templates` và cấu hình Endpoint `/` để kiểm tra khả năng phục vụ giao diện và tải file kéo thả.
|
|
|
|
### Tuần 2: Xây Dựng Audio Engine Tại Client (Web Audio API)
|
|
|
|
* [ ] Hoàn thiện cơ chế vẽ đồ thị sóng âm động dựa trên canvas cho các tệp âm thanh tải lên tự do từ máy người dùng.
|
|
* [ ] Kiểm thử cơ chế tính toán điểm Zero-crossing trực tiếp bằng Javascript để gán Marker thông minh (Snap-to-zero).
|
|
* [ ] Hiện thực hóa các nút điều khiển: volume của từng track độc lập, tắt tiếng (Mute), solo, dải Fade-in/Fade-out cho từng clip.
|
|
|
|
### Tuần 3: Hoàn Thiện Core DSP Phía Backend (Python Processing)
|
|
|
|
* [ ] Hiện thực hóa thuật toán phân tích nhịp bằng librosa (`analyzer.py`), trả về danh sách phách ($beats$) và khuôn nhạc ($bars$) định dạng JSON.
|
|
* [ ] Phát triển công cụ chỉnh sửa `audio_editor.py` phía máy chủ để thực thi việc cắt, ghép, loop với độ dài lớn, chuyển đổi cao độ và xuất tệp tin chất lượng cao bằng pydub.
|
|
|
|
### Tuần 4: Tích Hợp Bất Đồng Bộ (Client-Server Sync)
|
|
|
|
* [ ] Liên kết các nút điều khiển trên Frontend để sinh mã cấu hình JSON API động gửi tới máy chủ FastAPI.
|
|
* [ ] Cài đặt Celery worker xử lý tác vụ nặng ở background và trả về tiến độ trực tiếp cho Frontend hiển thị thông qua trạng thái tác vụ của Redis Result Backend.
|
|
* [ ] Tích hợp tính năng Gộp Track (Merge) sử dụng `OfflineAudioContext` của Client kết hợp với API Render đa kênh của Server.
|
|
|
|
### Tuần 5: Kiểm Thử Âm Học & Tối Ưu Hóa (Testing & Optimization)
|
|
|
|
* [ ] Kiểm thử hiện tượng giật/trễ tiếng (Audio Glitch / Pop) bằng cách ghép nối ngẫu nhiên các đoạn nhạc và kiểm thử hiệu năng tối ưu của cả hai tầng Zero-Crossing (Web Audio vs FFmpeg/Pydub).
|
|
* [ ] Tối ưu hóa bộ nhớ đệm RAM trong Docker khi xử lý song song các tệp âm thanh có dung lượng lớn.
|
|
* [ ] Đóng gói và nghiệm thu dự án. |