Kế Hoạch Triển Khai Kỹ Thuật: Dockerized Music Processing Server & SonicForge Studio

Kế hoạch này đặc tả lộ trình triển khai, kiểm thử và đồng bộ hóa hai lõi động cơ: Động cơ Web Audio Client-side (nghe thử thời gian thực, tương tác đồ họa) và Động cơ Python Docker Server-side (xử lý VST/VSTi, render chất lượng cao, quản lý phân quyền và hạn mức lưu trữ Quota).

1. GIAI ĐOẠN 1: ĐỒNG BỘ ĐỒ HỌA & XỬ LÝ SÓNG ÂM KHÔNG TRỄ

Mục tiêu là đưa mảng nhị phân thô (Float32Array) vào bộ nhớ RAM của Client để vẽ đồ thị siêu thu phóng mượt mà và thực thi bắt sự kiện bôi đen vùng chọn.

1.1. Các Tác Vụ Phía Frontend (HTML5/React)

[ ] Vẽ Sóng Đa Thang Đo (Multi-Scale Waveform):
Tích hợp thuật toán hoán đổi đồ họa trong index.html.
Khi zoom xa (Z < 500 px/s): Vẽ dải bao đỉnh (Peak Waveform).
Khi siêu thu phóng (Z \ge 500 px/s): Vẽ đường cong hình sin đơn tuyến (Continuous Polyline) và các chấm mẫu tròn (Sample Nodes, bán kính r = 2\text{ px}) tại các tọa độ mẫu chính xác.
[ ] Vẽ Lưới Trục Decibel: Dựng rõ rệt các vạch lưới ngang màu tối phân chia mốc biên độ: vạch dương +6.0 dB, vạch trung tâm -Inf. dB (Zero-Line), và vạch biên âm -6.0 dB.
[ ] Khóa Điểm Neo Shift+Click:
Triển khai React Ref độc lập localSelectionAnchorRef để khóa điểm nhấp chuột đầu tiên.
Khi người dùng nhấp Shift+Click lần 2, tính toán dải phủ màu cục bộ trên duy nhất track đang hoạt động trong khoảng [\min(T_{\text{anchor}}, T_{\text{end}}), \max(T_{\text{anchor}}, T_{\text{end}})].
Chặn đứng sự kiện click playhead hoặc kéo clip khi có phím Shift được nhấn.
[ ] Hủy Vòng Lặp (Escape Loop): Hỗ trợ tổ hợp Ctrl + Click chuột vào vùng trống ngoài dải chọn để hủy mốc neo, nhấn Spacebar phát nhạc tuyến tính vượt quá mốc lặp cũ.

1.2. Các Tác Vụ Phía Backend (Python / NumPy)

[ ] Port Thuật Toán Dò Zero-Crossing: Viết hàm dò tìm điểm đổi dấu vật lý trong tệp app/core/dsp_utils.py bằng toán tử NumPy vector hóa để tối ưu hóa tốc độ:

x[i] \cdot x[i+1] \le 0

2. GIAI ĐOẠN 2: CHỈNH SỬA PHI TUYẾN TRÊN SUB-TAB CÔ LẬP

Thiết lập môi trường làm việc cô lập (Sandbox) cho phép người dùng click đúp vào Clip để mở một Tab phụ biên tập chi tiết không ảnh hưởng đến bản phối chính.

2.1. Quy Trình Trích Xuất & Thước Đo

[ ] Sandbox Splicing: Khi double-click vào Clip, Frontend trích xuất mảng mẫu phụ (Sub-segment Buffer) và tạo một tab biên tập độc lập. Đặt lại thước đo thời gian Ruler của Tab này chạy từ t = 0.0\text{ s}.
[ ] Tương Tác Slider Thước Đo: Dựng 4 thanh kéo ngang điều hướng:
Normalize Ceiling: Trần chuẩn hóa từ -12\text{ dBFS} đến 0\text{ dBFS}.
Gain (dB) & Pitch Shift (Semitones): Khuếch đại biên độ và dịch giọng.
Speed Stretch (%): Co giãn thời lượng clip trực quan bằng cách nhấn giữ Alt rồi kéo biên phải của Clip. Hiển thị nhãn màu vàng Speed: 75.0%.
[ ] Bút Vẽ Volume (Pencil Tool): Kích hoạt cây bút vẽ để hiển thị đường thẳng lục sáng mốc 0\text{ dB}. Cho phép người dùng nhấp tạo các nút thắt điều khiển (Control Nodes) và kéo tăng (+3\text{ dB}) hoặc kéo giảm (-30\text{ dB}).

2.2. Hòa Mạng Apply & Merge Back Phía Server

[ ] Bộ Lọc Micro-Crossfade: Khi người dùng nhấn Apply, dữ liệu đã chỉnh sửa được đồng bộ ngược lại dòng phối chính. FastAPI Server chạy Celery task áp dụng bộ lọc mờ biên Micro-crossfade có độ rộng w = 10\text{ ms} tại hai đầu điểm ráp nối để triệt tiêu tiếng click/pop.

3. GIAI ĐOẠN 3: ĐỊNH TUYẾN MIDI, PLUGIN VST/VSTI & MIXER

Tích hợp bộ soạn thảo MIDI Piano Roll, nạp nhạc cụ ảo, hiệu ứng và điều phối âm lượng đa kênh.

3.1. MIDI Items & Piano Roll Editor

[ ] Piano Roll Canvas: Thiết lập giao diện lưới nốt nhạc có trục đứng Y biểu diễn cao độ từ 0 \rightarrow 127 (phím piano) và trục ngang X biểu diễn lưới phách (Beats) đồng bộ với Tempo.
[ ] Thao Tác Lưới: Cho phép nhấp chuột để thêm nốt nhạc, click chuột phải/nhấp đúp để xóa nốt, kéo hai đầu để thay đổi độ dài (duration_beats).

3.2. Động Cơ Định Tuyến VST / VSTi Trên Docker Linux

[ ] Nạp VSTi (Nhạc cụ ảo): Cấu hình thư viện pedalboard ở Python Backend để nạp các tệp tin .vst3 nhạc cụ ảo trên Linux, tiếp nhận sự kiện MIDI từ Piano Roll, tổng hợp âm và xuất ra mảng NumPy Stereo.
[ ] Nạp VST Effects (EQ/Reverb): Hỗ trợ ghim chuỗi hiệu ứng nối tiếp gộp cả Stock WASM và Native VST3.
[ ] Giao Diện Mixer Panel Đa Kênh: Dựng bảng mixer ở đáy màn hình hiển thị Master Bus, Track Audio, Track MIDI và Track FX Send/Return. Mỗi track có thước đo tín hiệu (Level Meter) dao động thời gian thực.

4. GIAI ĐOẠN 4: HỆ THỐNG PHÂN QUYỀN, QUOTA & ADMIN CONTROL

Xây dựng lớp bảo mật bảo vệ tài nguyên ổ đĩa máy chủ, quản lý người dùng và cờ tính năng (Feature Flags).

4.1. Phân Quyền & Quản Lý Quota

[ ] Bắt Buộc Đổi Mật Khẩu Lần Đầu (First-Time Login):
Khi tài khoản Admin/User được khởi tạo với mật khẩu mặc định từ môi trường Docker, hệ thống đặt cờ must_change_password = True trong database SQL.
Middleware của FastAPI sẽ chặn đứng mọi yêu cầu xử lý nhạc, ép người dùng thực hiện đổi mật khẩu ở lần đăng nhập đầu tiên mới mở khóa hệ thống.
[ ] Admin Quotas: Tích hợp bộ kiểm soát hạn mức dung lượng ổ đĩa lưu trữ (S_{\text{limit}}). Python sẽ tính toán tổng kích thước mảng nhị phân trước khi cho phép tải tệp lên:

S_{\text{used}} + S_{\text{new}} \le S_{\text{limit}}

[ ] Feature Flags: Hỗ trợ Admin bật/tắt nóng các tính năng cao cấp (như xuất bản WAV 24-bit, AI generation) thông qua bảng cấu hình DB.

4.2. Cấu Hinh Headless JUCE VST Rendering

[ ] Docker Xvfb Display: Bổ sung cấu hình màn hình ảo Xvfb (X Virtual Framebuffer) vào tệp Dockerfile để container nạp thành công các VST3 nhạc cụ và hiệu ứng biên dịch bằng C++ (JUCE framework) trên Linux mà không bị lỗi crash liên kết X11.

5. KIỂM THỬ XÁC MINH DANH TÍNH

Mô-đun kiểm thử	Phương pháp thực thi	Tiêu chuẩn đạt (KPI)
Kiểm thử Zoom & Sóng	Phóng to tối đa một bài nhạc `44.1\text{ kHz}`.	Nhìn thấy rõ hạt mẫu tròn màu xanh và dải lưới Decibel đối xứng.
Kiểm thử Shift+Click	Bôi chọn cục bộ và Master Loop trên thước Ruler.	Nhấn Spacebar lặp mượt mà, nhấn `Ctrl+Click` để hủy dải chọn.
Kiểm thử Zero-Crossing	Cắt lát nhạc bằng AI Cut ở mốc giây lẻ.	Tệp WAV kết xuất không có bất kỳ tiếng lách tách (click/pop) nào.
Kiểm thử Docker VSTi	Gửi chuỗi MIDI nốt và nạp một Virtual Synth VST3.	Kết xuất thành công tệp WAV Stereo có âm thanh nhạc cụ ảo.
Kiểm thử Bảo Mật Auth	Đăng nhập tài khoản mặc định và gọi API Mix nhạc.	Hệ thống trả về lỗi HTTP 403 Forbidden bắt buộc đổi mật khẩu.
Kiểm thử Quota	Cố tình tải lên tệp âm thanh nặng vượt giới hạn.	Trả về lỗi Dung lượng lưu trữ vượt quá giới hạn Quota của bạn.

Kế hoạch Cấu hình Dockerfile Hợp nhất (Có Xvfb Headless)

Để chuẩn bị môi trường chạy thật cho động cơ xử lý âm thanh bản địa (Native DSP) tích hợp VSTi/VST3 C++ thông qua Python Pedalboard, tệp tin Dockerfile của dự án bắt buộc phải được thiết lập màn hình ảo Xvfb để tránh crash liên kết đồ họa:

# Sử dụng Python 3.11 làm nền tảng
FROM python:3.11-slim

# Cài đặt các gói thư viện đồ hoạ và asound bắt buộc đối với JUCE / VST3 Linux
RUN apt-get update && apt-get install -y \
    libgl1-mesa-glx \
    libglu1-mesa \
    libasound2 \
    libjack-jackd2-0 \
    libfreetype6 \
    libfontconfig1 \
    libx11-6 \
    libxext6 \
    libxinerama1 \
    libxrandr2 \
    libxcursor1 \
    xvfb \
    ffmpeg \
    && rm -rf /var/lib/apt/lists/*

# Thiết lập biến môi trường hiển thị cho X11 ảo
ENV DISPLAY=:99

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

# Khởi chạy Xvfb ảo ở cổng :99 trước khi kích hoạt FastAPI / Celery
CMD ["sh", "-c", "Xvfb :99 -screen 0 1024x768x16 & python app/main.py"]

9.4 KiB Raw Blame History