# ĐẶC TẢ KIẾN TRÚC PHẦN MỀM: AUTONOMOUS AI CINEMA ENGINE (SHOWRUNNER OS)
> **Tài liệu quy hoạch dự án phần mềm độc lập (Dự kiến triển khai sau khi hoàn thành "Thập Ngũ Niên")**  
> **Tác giả & Kiến trúc sư**: Nguyễn Sĩ Sơn  
> **Công nghệ nền tảng**: Google Antigravity SDK (`google.antigravity`) + Meta Muse.ai Browser Automation + FFmpeg 4-Stem Audio  

---

## 1. TỔNG QUAN DỰ ÁN & SỨ MỆNH
- **Tên dự án dự kiến**: **Showrunner AI / Autonomous Cinema Engine (ACE)**.
- **Sứ mệnh**: Tự động hóa toàn diện chu trình sản xuất phim điện ảnh và video bom tấn. Người dùng chỉ cần cung cấp ý tưởng thô và trả lời 3-5 câu hỏi phỏng vấn tương tác, hệ thống sẽ tự hành 100%:
  1. Viết kịch bản chuẩn Hollywood 3 Hồi.
  2. Phân rã cấu trúc: Episode (Tập) ➔ Scene (Phân cảnh) ➔ Shot (Cỡ cảnh 5-10s).
  3. Xây dựng Character DNA & Bối cảnh nhất quán (Consistency Guard).
  4. Nạp I2V và render liên hoàn pixel-perfect qua Muse.ai (Head-Tail Chaining).
  5. Tự động kiểm duyệt an toàn YouTube (Green Dollar Gate) bằng Chiaroscuro và Nature Metaphor.
  6. Xử lý âm thanh 4-Stem (BGM, Ambience, Foley, Thoại) đạt chuẩn EBU R128 (-14 LUFS).

> **Chiến lược thực thi**: Tác phẩm điện ảnh **"Thập Ngũ Niên" (The Fifteen Springs - 180 phút)** tại repository `C:\Projects\KieuStory` đóng vai trò là **Sản phẩm mẫu (Proof of Concept - PoC)** đầu tay. Toàn bộ bài học xương máu, mã nguồn pipeline, prompt engineering và quy chuẩn YouTube của "Thập Ngũ Niên" sẽ được đóng gói thành sản phẩm phần mềm thương mại này.

---

## 2. KIẾN TRÚC ĐA ĐẶC VỤ PHÂN CẤP (HIERARCHICAL MULTI-AGENT ARCHITECTURE)

```
[ Ý TƯỞNG THÔ ]
       │
       ▼
┌─────────────────────────────────────────────────────────────┐
│ 1. THE SHOWRUNNER AGENT (Onboarding & Worldbuilding)        │
│    - Phỏng vấn 3 câu sắc bén: Logline, Mood, Visual Style   │
│    - Xuất Project Bible & Character DNA Sheet               │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. SCREENPLAY & BREAKDOWN AGENT (Hollywood Script Engine)   │
│    - Phân rã cấu trúc 3 hồi (Acts, Sequences, Beats)        │
│    - Sinh Scene Plan & Shot Plan (10s Muse-Optimized)       │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. MULTIMODAL PROMPT DECONSTRUCTOR AGENT                    │
│    - Motion Prompts: 24fps cinematic, safe headroom         │
│    - Audio Guard: Negative prompt cấm nhạc rác Muse.ai      │
│    - Start Frame Generator: Imagen 3 / Gemini Banana 720p   │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. YOUTUBE GREEN DOLLAR SENTINEL (Kiểm duyệt & An toàn)     │
│    - Chiaroscuro: Chuyển bạo lực thành bóng đổ vách tre     │
│    - Nature Metaphor: Cảnh nhạy cảm ➔ Giông bão hoa rơi     │
│    - Giám sát độ giật, lỗi hình, và nhịp cắt retention      │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 5. MUSE.AI HEAD-TAIL CHAINING WORKER                        │
│    - Persistent browser session (agent-browser muse)        │
│    - FFmpeg Tail Frame Extraction (frame 239 ➔ next start)   │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ 6. MASTERING & 4-STEM CONCAT ENGINE                         │
│    - Concat bảo toàn âm thanh (Cấm OpenCV VideoWriter)      │
│    - Sidechain Ducking BGM (-14dB) ➔ EBU R128 (-14 LUFS)    │
└─────────────────────────────┬───────────────────────────────┘
                              │
                              ▼
              [ VIDEO BOM TẤN XUẤT BẢN THÀNH PHẨM ]
```

---

## 3. CẤU TRÚC DỮ LIỆU ĐẶC TẢ (PYDANTIC SCHEMAS)

```python
from typing import List, Optional
from pydantic import BaseModel, Field

class CharacterDNA(BaseModel):
    name: str
    age_progression: dict  # Biến chuyển ngoại hình theo năm
    facial_features: str
    costume_palette: List[str]
    personality_traits: str

class ShotPlan(BaseModel):
    shot_id: str
    duration_seconds: int = 10
    camera_movement: str  # Pan, Tilt, Dolly, Drone, Static
    composition: str      # Medium Close-Up, Rule of Thirds
    visual_prompt: str
    audio_foley_ambience: str
    dialogue: Optional[str] = None
    youtube_safety_filter: str  # "CLEAN", "CHIAROSCURO", "METAPHOR"

class ScenePlan(BaseModel):
    scene_id: str
    scene_title: str
    setting_environment: str
    dramatic_conflict: str
    shots: List[ShotPlan]

class EpisodePlan(BaseModel):
    episode_number: int
    title: str
    duration_minutes: int
    cliffhanger: str
    scenes: List[ScenePlan]

class ProjectBible(BaseModel):
    project_id: str
    title: str
    theme: str
    visual_preset: str
    characters: List[CharacterDNA]
    episodes: List[EpisodePlan]
```

---

## 4. BỘ CÔNG CỤ THỰC THI NỀN TẢNG (CORE ENGINE TOOLS)

### 4.1. Tool Điều Khiển Muse.ai Headless & Audio Guard
```python
# Gửi prompt kèm Negative Audio Guard bảo vệ chất lượng âm thanh
full_prompt = (
    f"{visual_prompt}. "
    f"Âm thanh: {audio_foley_ambience}. "
    f"Quy tắc âm thanh: Tuyệt đối KHÔNG sinh nhạc nền (no music/BGM), "
    f"không âm thanh điện tử, không tạp âm rè nhiễu. "
    f"Chỉ sinh âm thanh môi trường tự nhiên (foley, ambience) và thoại nhân vật chân thực."
)
```

### 4.2. Tool Trích Xuất Head-Tail Chaining
```bash
# Trích xuất khung hình cuối cùng (giây 9.9) để làm Start Frame cho shot tiếp theo
ffmpeg -y -sseof -0.1 -i "shot01.mp4" -vframes 1 -q:v 1 "shot02_start.png"
```

### 4.3. Tool Ghép Nối Master Bảo Toàn Âm Thanh
```bash
# Ghép nối đồng bộ luồng video và âm thanh Muse.ai nguyên bản
ffmpeg -y -i s1.mp4 -i s2.mp4 -filter_complex "[0:v:0][0:a:0][1:v:0][1:a:0]concat=n=2:v=1:a=1[v][a]" -map "[v]" -map "[a]" -c:v libx264 -crf 18 -preset slow -c:a aac -b:a 192k -ar 48000 master.mp4
```

### 4.4. Tool Kiểm Chuẩn YouTube Green Dollar
- Tự động thay thế các mô tả có từ khóa nhạy cảm/bạo lực thành kỹ thuật quay nghệ thuật ước lệ (Ánh sáng Chiaroscuro vách tre, tiếng rơi vỡ chén ngọc, hoa lê rơi trong mưa bão).

---

## 5. LỘ TRÌNH PHÁT TRIỂN (ROADMAP)

### Giai đoạn 1: Chứng minh quy trình thực chiến tại "Thập Ngũ Niên" (HIỆN TẠI)
- [x] Chuyển thể kịch bản điện ảnh 6 tập (180 phút, 55 scenes) trong thư mục `FilmMaker/`.
- [x] Xây dựng Project Bible, Character Bible (32 nhân vật), Timeline lão hóa 15 năm.
- [x] Tích hợp automation browser Muse.ai render thành công các shot mở đầu.
- [x] Hoàn thiện giao thức ghép nối FFmpeg bảo toàn âm thanh và Audio Pipeline 4 lớp.
- [ ] Render hoàn tất toàn bộ các cảnh cao trào của Tập 1.
- [ ] Xuất bản bản master Tập 1 và chuỗi Shorts 9:16 trên YouTube để kiểm chứng thực tế chỉ số Green Dollar và tỷ lệ giữ chân (Retention).

### Giai đoạn 2: Tách repository & Đóng gói phần mềm (SAU KHI HOÀN THÀNH PHIM)
- Khởi tạo repo riêng: `AutonomousCinemaEngine`.
- Đóng gói backend: Python SDK `google.antigravity` + FastAPI service.
- Đóng gói worker: Muse.ai browser pool automation + PureScale 4K GPU service.
- Xây dựng UI Studio: Interactive Showrunner Interview Dashboard.
- Cung cấp tính năng 1-Click Export sang YouTube (Meta tags, Green Dollar Pre-check, Shorts auto-cut).