# THẬP NGŨ NIÊN (THE FIFTEEN SPRINGS) - CINEMATIC AUDIO PIPELINE & MASTERING SPECIFICATION
## Quy Chuẩn Thiết Kế & Hậu Kỳ Âm Thanh Scene-by-Scene Chuẩn Điện Ảnh Bom Tấn

---

## I. TẦNG KIẾN TRÚC ÂM THANH 4 LỚP ĐỘC LẬP (4-STEM SOUND ARCHITECTURE)

Để biến các thước phim AI (Muse.ai 10s) thành một tác phẩm điện ảnh bom tấn liền mạch, có chiều sâu không gian và rung động cảm xúc, hệ thống âm thanh dự án **Thập Ngũ Niên** được xây dựng trên cấu trúc 4 Stems tách biệt:

```
┌────────────────────────────────────────────────────────────────────────┐
│ STEM 4: DIALOGUE & VOICE-OVER (Thoại & Lời dẫn thơ Kiều - Solo/Ducking) │
├────────────────────────────────────────────────────────────────────────┤
│ STEM 3: FOLEY & ACTION SFX (Tiếng áo lụa, trâm cài, tách trà, đao kiếm) │
├────────────────────────────────────────────────────────────────────────┤
│ STEM 2: AMBIENCE & SOUNDSCAPE (Gió rặng liễu, suối ngọc, chợ kinh kỳ) │
├────────────────────────────────────────────────────────────────────────┤
│ STEM 1: BGM & CINEMATIC SCORE (Dàn dây + Đàn Tỳ Bà / Tranh / Sáo Trúc) │
└────────────────────────────────────────────────────────────────────────┘
```

### 1. Stem 1: BGM & Cinematic Score (Nhạc Nền Cổ Phong Điện Ảnh)
- **Đặc trưng**: Kết hợp giữa giao hưởng điện ảnh Tây phương (Cinematic Strings, Cello trầm đục, D-minor / C-minor bi tráng) với ngũ cung Đại Việt / Đông Á (Tỳ Bà, Tranh, Nguyệt, Nhị, Sáo Trúc, Trống Trận).
- **Quy tắc phối âm**:
  - Trải thảm liên tục (Drone / Pad) theo từng Scene (thời lượng 50s - 180s), **tuyệt đối không cắt vụn BGM theo từng shot 10s** của Muse.ai.
  - EQ Notching: Chủ động khoét tần số vàng từ **800 Hz – 3.500 Hz** (cắt giảm -3dB đến -4.5dB) để nhường không gian cho giọng thoại Kiều và Kim Trọng.

### 2. Stem 2: Ambience & Environmental Soundscape (Âm Cảnh Môi Trường 3D)
- **Đặc trưng**: Tái tạo không gian vật lý chân thực của thời đại:
  - *Vườn Thúy*: Tiếng lá tre rì rào trong gió xuân, tiếng chim chuyền cành, tiếng giọt sương rơi trên búp sen.
  - *Sông Tiền Đường*: Tiếng sóng vỗ mạn thuyền, gió rít qua bãi sậy, tiếng chuông chùa Giác Duyên vọng từ thảo am.
  - *Trại quân Từ Hải*: Tiếng cờ phướn phần phật trong gió biển, tiếng đuốc cháy bập bùng, tiếng rì rầm của vạn quân.
- **Kỹ thuật Spatial Panning**: Phân bổ âm thanh nổi (Stereo Panning) theo tỷ lệ 70-30 hoặc 60-40 tương ứng với vị trí visual của nguồn phát trên khung hình.

### 3. Stem 3: Foley & Spot SFX (Âm Thanh Tác Động Cơ Học Sắc Nét)
- **Micro-Foley (Âm thanh vi mô)**:
  - Tiếng sột soạt tơ tằm của áo Giao Lĩnh khi nhân vật cử động.
  - Tiếng va chạm lách cách tinh tế của trâm ngọc, vòng ngọc bích.
  - Tiếng đặt chén trà sứ xuống bàn gỗ lim, tiếng lật trang sách giấy dó.
- **Macro-Impact SFX (Âm thanh vĩ mô kịch tính)**:
  - Tiếng vó ngựa dồn dập, gươm giáo chạm gông cùm trong biến cố gia đình họ Vương.
  - Tiếng gãy cụt của dây đàn tỳ bà trong đêm gặp Đạm Tiên (Báo hiệu điềm gở đứt gánh tương tư).
  - Tiếng sấm chớp rền vang qua vách liếp tre (Kỹ thuật Chiaroscuro âm thanh).

### 4. Stem 4: Dialogue & Studio Voice-Over (Thoại & Lời Bình Dẫn Truyện)
- **Xử lý Vocal Chain**:
  - De-Esser (khử rít âm x/s tần số 5.5kHz - 7kHz).
  - Low-cut Filter 80Hz (loại bỏ tiếng ồn nền rung sàn).
  - Warmth EQ: Boost nhẹ dải 150Hz - 250Hz tạo độ ấm sâu của giọng tự sự hoài niệm.
  - High Presence: Boost dải 4.5kHz - 6kHz giúp lời ngâm thơ Kiều sáng rõ, trong trẻo.
- **Dynamic Sidechain Ducking Master**:
  - Mỗi khi có tiếng thoại / ngâm thơ xuất hiện, Stem 1 (BGM) và Stem 2 (Ambience) lập tức tự động hạ **-12 dB đến -18 dB**.
  - Tham số nén: `Attack = 50ms` (hạ êm, không giật cụt), `Release = 300ms` (nâng BGM mượt mà trở lại sau khi hết câu thoại).

---

## II. QUY TRÌNH HẬU KỲ ÂM THANH SCENE-BY-SCENE 6 BƯỚC

```
[Muse.ai Video Shots (10s)]
           │
           ▼
[Bước 1: Audio Continuity & Volume Detect Audit] ──> Quét ffprobe & volumedetect
           │
           ▼
[Bước 2: Equal-Power Micro-Crossfade] ─────────────> acrossfade (qsin) 0.75s-1.0s
           │
           ▼
[Bước 3: Nghệ Thuật Điện Ảnh J-Cut / L-Cut] ───────> Acoustic Distance Filter (lowpass 3500Hz)
           │
           ▼
[Bước 4: Multi-track Layering & Dynamic Ducking] ──> BGM thảm + Foley + Sidechain Ducking
           │
           ▼
[Bước 5: Transition Audio Bridge (Nối Visual 2s)] ─> Bù đắp âm cảnh cho frame morphing
           │
           ▼
[Bước 6: Broadcast Mastering Chuẩn EBU R128] ──────> loudnorm -14 LUFS, TP -1.0, 48kHz AAC
```

### Bước 1: Audio Continuity & Volume Detect Audit (Kiểm Tra Tính Đồng Nhất)
- Trước khi ghép, chạy script `audio_continuity_engine.py --inspect` để phân tích toàn bộ các shot trong scene.
- Đo `max_volume` và `mean_volume`. Nếu delta chênh lệch giữa hai shot liền kề **> 3.0 dB**, hệ thống cảnh báo và tự động cân bằng gain staging trước khi ghép nối.

### Bước 2: Equal-Power Audio Crossfade (Triệt Tiêu Click/Pop Giữa Các Shot)
- Tuyệt đối không dùng hard-cut âm thanh ở ranh giới giữa 2 shot video AI.
- Sử dụng thuật toán chuyển tiếp năng lượng đồng đều (`acrossfade` đường cong `qsin` hoặc `cbrt` từ 0.75s đến 1.0s) để giữ nguyên năng lượng âm thanh không gian.

### Bước 3: Nghệ Thuật Điện Ảnh J-Cut & L-Cut Không Gian (Acoustic Distance Filter)
- **L-Cut (Âm thanh shot trước tràn sang shot sau)**:
  - Tiếng đàn tam thập lục của Thúy Kiều tiếp tục ngân vang sang khung hình của Thúy Vân bên hiên hè.
  - Sử dụng bộ lọc khoảng cách vật lý: `lowpass=f=3500`, giảm âm lượng 30%, kết hợp `adelay` và `reverb` nhẹ giả lập vị trí phòng trong cách một vách ngăn.
- **J-Cut (Âm thanh shot sau đi trước hình ảnh)**:
  - Tiếng gió hú và tiếng sét đánh vang lên trước 1.5s khi hình ảnh chuyển sang cảnh giông tố Đạm Tiên.

### Bước 4: Trải Thảm BGM Độc Lập & Sidechain Audio Ducking
- Thay vì để nhạc nền bị xé vụn thành từng đoạn 10s theo video Muse.ai, BGM được xuất từ Suno AI / DAWs dưới dạng track dài toàn cảnh (Full Scene Stems).
- Ghép bằng lệnh FFmpeg Sidechain Ducking tự động:
  ```bash
  ffmpeg -y -i scene_video_faded.mp4 -i scene_bgm.m4a -i voice_dialogue.wav \
  -filter_complex "[1:a]volume=0.8[bgm];[2:a]volume=1.0[voc];[bgm][voc]sidechaincompress=threshold=0.08:ratio=5:attack=50:release=300[ducked_bgm];[ducked_bgm][voc]amix=inputs=2:duration=first[a_master]" \
  -map 0:v -map "[a_master]" -c:v copy -c:a aac -b:a 192k -ar 48000 master_scene.mp4
  ```

### Bước 5: Transition Audio Bridge (Bù Đắp Âm Cảnh Cho Đoạn Morphing 2 Giây)
- Các đoạn chuyển cảnh visual (Transition 2s tạo bằng Frame Blending / Morpheus giữa các góc máy):
  - BẮT BUỘC chèn audio bridge (tiếng chuông gió, tiếng đàn ngân dài, hoặc tiếng gió thoảng).
  - Không bao giờ để xuất hiện khoảng lặng câm (dead silence) giữa 2 phân cảnh.

### Bước 6: Hollywood / YouTube Green Dollar Mastering (EBU R128 Standard)
- Toàn bộ master scene xuất xưởng phải thỏa mãn các chỉ số kiểm duyệt phát sóng toàn cầu:
  - **Integrated Loudness**: `-14.0 LUFS` (±0.5 LUFS) - Tối ưu 100% cho thuật toán YouTube, không bị nén phạt âm lượng.
  - **True Peak**: `-1.0 dBTP` (Tuyệt đối không clipping / méo âm trên dàn loa rạp chiếu hoặc tai nghe cao cấp).
  - **Loudness Range (LRA)**: `9 – 11 LU` (Đảm bảo dải động điện ảnh, phân biệt rõ đoạn tĩnh lặng thì thầm và đoạn cao trào sấm sét).
  - **Audio Stream**: Codec `AAC-LC`, Bitrate `192kbps - 320kbps`, Sample Rate `48.000 Hz`, Stereo (hoặc 5.1 Surround khi xuất bản chiếu rạp).

---

## III. QUY TẮC CỐT TỬ VỀ BẢO TOÀN ÂM THANH (AUDIO PRESERVATION DIRECTIVE)

1. **TUYỆT ĐỐI CẤM OpenCV trong Concat Video**:
   - `cv2.VideoWriter` chỉ xử lý ma trận pixel hình ảnh, **nuốt chửng và triệt tiêu 100% luồng audio** của Muse.ai. Bất kỳ ai sử dụng OpenCV để ghép shot đều vi phạm nghiêm trọng quy chuẩn kỹ thuật dự án.
2. **BẮT BUỘC FFmpeg Sample-Accurate Concat**:
   - Mọi thao tác ghép nối shot phải sử dụng `filter_complex concat` đồng bộ cả `[v]` và `[a]`:
     `[0:v:0][0:a:0][1:v:0][1:a:0]...concat=n=N:v=1:a=1[v][a]`
3. **Lưu trữ Stems độc lập**:
   - Mọi asset âm thanh hoàn thiện phải được phân loại và lưu trữ tại `04_Assets/audio/` (BGM dài), `04_Assets/audio_sfx/` (Hiệu ứng foley), và `04_Assets/audio_voice/` (Giọng thoại/ngâm thơ).

---

## IV. QUY CHUẨN CHỈ THỊ ÂM THANH CHO MUSE.AI (AUDIO PROMPTING DIRECTIVES)

Nhằm triệt tiêu triệt để tình trạng AI sinh ra **"Audio Rác"** (nhạc nền điện tử ngẫu nhiên, tiếng beat EDM lạc tông, tạp âm xì xào méo tiếng, âm thanh tổng hợp khó chịu) làm hỏng không khí phim cổ phong, mọi prompt gửi sang **Muse.ai** BẮT BUỘC tuân thủ cấu trúc 3 phần:

```
[Chuyển động & Biểu cảm Visual] + [Âm cảnh Môi trường / Thoại cụ thể] + [Chỉ thị Negative Audio]
```

### 1. Nguyên Tắc Cốt Tử: Tách Biệt Nhạc Nền (Zero In-Shot Music)
- **Nhạc nền (BGM & Score)** của phim được dàn dựng riêng ở khâu hậu kỳ bằng Suno AI / DAWs và trải thảm liền mạch theo phân cảnh (50s – 180s).
- **Trong từng shot Muse.ai 10s: TUYỆT ĐỐI KHÔNG để Muse.ai tự sinh nhạc nền**. Bất kỳ bản nhạc nền ngẫu nhiên nào từ AI trong shot đều bị coi là audio rác phá hỏng mạch phim.

### 2. Hai Thành Phần Âm Thanh Được Phép Sinh:
1. **Âm thanh Môi trường & Tác động Cơ học (Ambience & Foley)**:
   - Tiếng gió thổi lay động cành liễu, tiếng nước chảy róc rách, tiếng chim én chao liệng.
   - Tiếng sột soạt của tơ tằm áo Giao Lĩnh khi chuyển động, tiếng gảy đàn tỳ bà mộc mạc, tiếng bước chân trên đá xanh, tiếng đặt chén ngọc.
2. **Thoại & Lời Ngâm Thơ Của Nhân Vật (Character Dialogue / Voice)**:
   - Khớp với khẩu hình và biểu cảm vi mô của nhân vật trong khung hình (như cụ ông ngâm Kiều, Thúy Vân gọi chị, Thúy Kiều trò chuyện).
   - Chất giọng tự nhiên, mộc mạc, truyền cảm, không qua xử lý méo tiếng điện tử.

### 3. Mẫu Câu Lệnh Chỉ Thị Âm Thanh Chuẩn Hóa (Standard Prompt Template):
Mọi prompt nạp vào Muse.ai (qua chat, script `run_shot.py`, hay `send_to_muse.py`) đều phải có đuôi chỉ thị:
> **Tiếng Việt**:
> `Âm thanh: [Mô tả chi tiết tiếng môi trường/foley và câu thoại]. Quy tắc âm thanh: Tuyệt đối KHÔNG sinh nhạc nền (no music/BGM), không âm thanh điện tử, không tạp âm rè nhiễu. Chỉ sinh âm thanh môi trường tự nhiên (foley, ambience) và thoại nhân vật chân thực.`
>
> **Tiếng Anh**:
> `Audio: [Detailed natural ambient foley & dialogue]. Strictly NO background music (no BGM/music), no electronic beats, no synthesized melody, no audio noise or distortion. ONLY natural environmental sound and authentic character voice.`

### 4. Tự Động Hóa Tường Lửa Âm Thanh Trong Pipeline (Automated Audio Guard):
- Script thực thi `05_Production_Pipeline/run_shot.py` được tích hợp bộ lọc tự động: Nếu phát hiện prompt chưa có chỉ thị âm thanh, hệ thống sẽ tự động ghép thêm chuỗi `audio_guard` trước khi gửi lệnh sang ô chat của Muse.ai.