# QUY TRÌNH SẢN XUẤT ĐIỆN ẢNH AI TỰ ĐỘNG HÓA (AI CINEMA PRODUCTION PIPELINE)
## THẬP NGŨ NIÊN: ĐOẠN TRƯỜNG KÝ (THE FIFTEEN SPRINGS)

> **Cỗ máy sản xuất**: Kết hợp giữa Trí tuệ Nhân tạo thế hệ mới (Gemini Banana + Muse2API Gateway `http://127.0.0.1:18610/v1` & Gradio LTX-Video) và Hệ thống xử lý video cục bộ (NVIDIA GeForce GTX 1660 Super NVENC / PureScale 4K / FFmpeg EBU R128).

---

## 1. KIẾN TRÚC VẬN HÀNH 6 BƯỚC (6-STAGE PIPELINE)

```
[01_Scripts_And_Episodes / FilmMaker] (Kịch bản phân cảnh 6 tập)
                  │
                  ▼
[Bước 1: Gemini Banana] ──────────► Sinh Start Frame / Keyframe chuẩn 720p (1280x720)
                  │                 Lưu trữ tại: 04_Assets/characters/ & keyframes/
                  ▼
[Bước 2: Production Orchestrator] ─► Nạp Start Frame (Base64) vào Muse2API Gateway (http://127.0.0.1:18610/v1)
                  │                 Gửi Motion Prompt kèm Audio Guard (Foley/Ambience only)
                  ▼
[Bước 3: Head-Tail Chaining] ─────► Tải video trực tiếp về 04_Assets/videos/<shot_id>_10s_v<N>.mp4
                  │                 Trích xuất Frame cuối (Tail Frame 239) -> Start Frame cho Shot kế tiếp
                  ▼
[Bước 4: Visual & Audio Audit] ───► Kiểm tra continuity (continuity_checker.py)
                  │                 Phân tích loudness & continuity (audio_continuity_engine.py)
                  ▼
[Bước 5: Audio-Preserving Concat] ─► Ghép toàn cảnh bằng FFmpeg filter_complex concat ([v][a])
                  │                 Bảo toàn 100% âm thanh AAC 48kHz từ Muse.ai
                  ▼
[Bước 6: Mastering & Export] ─────┬─► Master âm thanh EBU R128 (-14 LUFS) + BGM Suno AI
                                  ├─► Xuất bản phẩm tại 06_Exports/
                                  └─► Tùy chọn PureScale 4K UHD (3840x2160)
```

---

## 2. BỘ CÔNG CỤ ĐIỀU PHỐI SẢN XUẤT (CLI TOOLS & RUNBOOK)

### 2.0. Cổng Render Trực Tiếp Muse2API Gateway (`muse_api_client.py`)

Giao thức REST API chính thức giao tiếp trực tiếp với cổng `Muse2API Gateway` (`http://127.0.0.1:18610/v1`), hỗ trợ cả Text-to-Video và Image-to-Video (mã hóa Base64 Data URI) với cơ chế đa tài khoản tự động:

```bash
# 1. Kiểm tra trạng thái cổng dịch vụ và số lượng tài khoản khả dụng
python "05_Production_Pipeline\muse_api_client.py" --health

# 2. Render 1 shot đơn lẻ qua API (tự động resolve Start Frame, polling và trích Tail Frame)
python "05_Production_Pipeline\muse_api_client.py" --shot ep01_scene02_shot04

# 3. Render kèm tùy chọn thời lượng và đảo ngược chuyển động
python "05_Production_Pipeline\muse_api_client.py" --shot ep01_scene02_shot04 --duration 5 --reverse
```

### 2.1. Cỗ Máy Điều Phối Sản Xuất Chính (`production_orchestrator.py`)

Đây là công cụ trung tâm điều khiển toàn bộ chu trình sản xuất từ Shot đơn lẻ đến toàn bộ Tập phim:

```bash
# 1. Kiểm tra trạng thái sản xuất toàn bộ các tập/cảnh
python "05_Production_Pipeline\production_orchestrator.py" --status

# 2. Liệt kê danh mục shot của một cảnh cụ thể (hoặc toàn bộ nếu bỏ trống tham số)
python "05_Production_Pipeline\production_orchestrator.py" --list-shots ep01_scene02

# 3. Render 1 shot đơn lẻ (Tự động tìm Start Frame từ shot trước hoặc Character Asset)
python "05_Production_Pipeline\production_orchestrator.py" --render-shot ep01_scene02_shot04

# 4. Render tự động toàn bộ 1 Cảnh theo chuỗi Head-Tail liên hoàn và tự động ghép Master
python "05_Production_Pipeline\production_orchestrator.py" --batch-scene ep01_scene02

# 5. Ghép nối các shot đã render thành Scene Master (bảo toàn 100% âm thanh)
python "05_Production_Pipeline\production_orchestrator.py" --concat-scene ep01_scene02

# 6. Master âm thanh chuẩn YouTube Green Dollar (-14 LUFS) kết hợp nhạc nền BGM
python "05_Production_Pipeline\production_orchestrator.py" --master-audio ep01_scene02 --bgm "04_Assets/audio_sfx/scene01_bgm.m4a"
```

---

### 2.2. Bộ Hỗ Trợ Quản Lý Tài Nguyên (`pipeline_helper.py`)

```bash
# Xem danh mục 32 nhân vật & bối cảnh
python "05_Production_Pipeline\pipeline_helper.py" --list

# Xuất toàn bộ file text prompt phân cấp (nạp vào Gemini Banana / Muse.ai)
python "05_Production_Pipeline\pipeline_helper.py" --export-prompts

# Kiểm tra tính toàn vẹn thư mục tài nguyên dự án
python "05_Production_Pipeline\pipeline_helper.py" --status

# Tự động cắt Shorts 9:16 dọc từ video hoàn thiện (NVIDIA NVENC)
python "05_Production_Pipeline\pipeline_helper.py" --make-short --input "04_Assets/videos/thap_ngu_nien_ep01_intro_prologue_scene01_110s.mp4" --output "06_Exports/shorts_1m_9x16/ep01_short01.mp4" --start 00:00:20 --duration 58
```

---

### 2.3. Kiểm Tra Tính Liên Tục Thị Giác (`continuity_checker.py`)

So sánh độ khớp Histogram màu sắc HSV và sai khác cấu trúc giữa Frame cuối của Shot trước và Frame đầu của Shot sau:

```bash
python "05_Production_Pipeline\continuity_checker.py" --shot-a "04_Assets/videos/ep01_scene01_shot01_10s.mp4" --shot-b "04_Assets/videos/ep01_scene01_shot02_10s.mp4"
```

---

### 2.4. Động Cơ Xử Lý Âm Thanh Điện Ảnh (`audio_continuity_engine.py`)

Kiểm toán âm lượng, crossfade nối shot, và chuẩn hóa -14 LUFS theo EBU R128:

```bash
# Kiểm toán âm lượng giữa các shot
python "05_Production_Pipeline\audio_continuity_engine.py" --inspect "04_Assets/videos/ep01_scene01_shot01_10s.mp4" "04_Assets/videos/ep01_scene01_shot02_10s.mp4"

# Nối 2 video với Equal-Power Audio Crossfade 1.0s (qsin)
python "05_Production_Pipeline\audio_continuity_engine.py" --crossfade "shot1.mp4" "shot2.mp4" --duration 1.0 --output "joined.mp4"

# Chuẩn hóa âm lượng video Master về -14 LUFS
python "05_Production_Pipeline\audio_continuity_engine.py" --normalize "04_Assets/videos/ep01_scene01_master_50s.mp4" --lufs -14.0 --output "04_Assets/videos/ep01_scene01_master_norm.mp4"
```

---

## 3. CÁC NGUYÊN TẮC KỸ THUẬT BẮT BUỘC (MANDATORY DIRECTIVES)

1. **Chuẩn Start Frame I2V**: 720p (1280x720 cho 16:9 ngang / 720x1280 cho 9:16 dọc), định dạng PNG lossless, cỡ cảnh Medium Close-Up từ ngực trở lên, headroom thoáng để chuyển động camera không cắt lẹm vào đỉnh đầu hay trâm cài.
2. **Audio Guard Trong Prompt Muse.ai**: BẮT BUỘC kèm câu lệnh cấm nhạc rác:
   `Âm thanh: Chỉ sinh âm thanh môi trường tự nhiên (foley, ambience) và thoại nhân vật chân thực. 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.`
3. **Cấm dùng OpenCV Ghép Master**: TUYỆT ĐỐI KHÔNG dùng OpenCV (`cv2.VideoWriter`) để concat video vì sẽ làm mất 100% âm thanh AAC. Luôn dùng FFmpeg `filter_complex concat`.
4. **Lưu Trữ Bằng Chứng Sở Hữu Trí Tuệ**: Mọi bản render thử nghiệm, bản nháp, bản loại bỏ KHÔNG ĐƯỢC XÓA mà chuyển vào `04_Assets/archive/` để làm bằng chứng đăng ký bản quyền.