# Project: Thập Ngũ Niên (The Fifteen Springs) — EP01 Restructuring & Universal Standards

## Architecture
The project follows an AI-driven cinematic production architecture consisting of five decoupled layers:
1. **Narrative & Screenplay Layer (`01_Scripts_And_Episodes/`, `FilmMaker/`)**: Screenplay with Hollywood format, 3-Act pacing, scene and shot listings, dialogue and character actions.
2. **Visual & Prompt Engineering Layer (`00_Project_Bible/`, `02_AI_Prompts/`)**: Character/Environment Bibles, Universal Acting Directives (Anti-Male-Tears, Lip-Sync Guard), and JSON registries for Gemini Banana (Start Frames) and Muse.ai (I2V Motion Prompts).
3. **Asset & Keyframe Layer (`04_Assets/`)**: Character portraits, 720p contextual start frames, Muse.ai rendered video clips (10s per shot), audio SFX stems, and master export archives.
4. **Production Pipeline & Audio Engine (`05_Production_Pipeline/`)**: Automation runners (`run_shot.py`, `production_orchestrator.py`), Audio Continuity Engine (`audio_continuity_engine.py` - 4 stems, crossfade stitching, EBU R128 -14 LUFS), and Feature Assembler (`assemble_ep01_feature.py`).
5. **Remote Review & QA Layer (`web_review/`)**: Web Review Studio running on port 1515 (accessible via Tailscale `http://100.121.197.18:1515`), providing instant status, video playback, prompt inspection, and review workflows.

```
[Screenplay & Beats (FilmMaker/)]
              │
              ▼
[AI Prompt Registry (02_AI_Prompts/)] ◄── [Project Bible & Directives (00_Project_Bible/)]
              │
              ├── Step 1: Gemini Banana Contextual Start Frame (720p)
              └── Step 2: Muse.ai Video Generation (agent-browser --session muse)
              │
              ▼
[Video Clips (04_Assets/videos/)] ──► [Audio Continuity Engine & 4-Stem Mixer] ──► [Scene Masters & Grand Feature (06_Exports/)]
                                                                                              │
                                                                                              ▼
                                                                             [Web Review Studio (Port 1515)]
```

## Feature Inventory
| # | Feature | Description | Milestone | Source |
|---|---------|-------------|-----------|--------|
| F1 | EP01 Screenplay & Pacing Expansion | Expand EP01 to 25-30 minutes (188 shots = 29m40s) with 3-Act classical cinema pacing | M1 | ORIGINAL_REQUEST §R1 |
| F2 | Đạm Tiên Grave 3-Beat Sequence | Reconstruct Scene 05 into C05-A (Stroll 8 shots), C05-B (Inquiry 7 shots), C05-C (Grief & Footprints 12 shots) | M1 | ORIGINAL_REQUEST §R2 |
| F3 | Anti-Male-Tears Script Purge | Eliminate male crying lines (Kim Trọng, Vương Quan) in favor of feudal stoicism (jaw clench, heavy gaze, compressed breath) | M1 | ORIGINAL_REQUEST §R4 |
| F4 | Universal Acting Directives Documentation | Codify Anti-Male-Tears, elevated female/crowd micro-expressions, and feudal composure in Project Bible | M2 | ORIGINAL_REQUEST §R4 |
| F5 | 2-Step Sweet-Spot Start Frame Protocol | Codify Gemini Banana -> Muse.ai 720p workflow, eliminate raw indoor studio portraits in outdoor scenes, zero reverse physics | M2 | ORIGINAL_REQUEST §R3 |
| F6 | Lip-Sync & Off-Screen Dialogue Guard | Codify mandatory closed-lips directive for off-screen calls and distant dialogue across all prompts | M2 | ORIGINAL_REQUEST §R5 |
| F7 | EP01 188-Shot AI Prompt Registry | Update `gemini_banana_prompts.json` and `muse_ai_video_prompts.json` with all 188 shots enforcing R3, R4, R5, and audio guards | M2 | ORIGINAL_REQUEST §R3, §R4, §R5 |
| F8 | Audio Continuity & Crossfade Concat | Upgrade `audio_continuity_engine.py` and `production_orchestrator.py` with default audio crossfades and RMS volume staging | M3 | ORIGINAL_REQUEST §R6 |
| F9 | Continuous Stem 2 Festival Ambience | Generate/integrate continuous crowd ambience bed track across festival and transition scenes | M3 | ORIGINAL_REQUEST §R6 |
| F10 | EBU R128 -14 LUFS Two-Pass Normalization | Implement two-pass linear EBU R128 loudness normalization for YouTube Green Dollar compliance | M3 | ORIGINAL_REQUEST §R6 |
| F11 | Web Review Studio Port 1515 Synchronization | Upgrade `web_review/server.py` to sync with `run_shot.py` generation protocol and display full 188-shot EP01 breakdown | M4 | ORIGINAL_REQUEST §R7 |
| F12 | Automated Production Runner & Concat | Ensure headless CLI and Web Studio seamlessly trigger render, tail-frame extraction, and master concatenation | M4 | ORIGINAL_REQUEST §R7 |
| F13 | E2E Acceptance Testing & Master Verification | Execute full Tiers 1-4 test suite, Tier 5 adversarial hardening, and assemble EP01 Grand Feature Master | M5 | Acceptance Criteria |

## Milestones
| # | Name | Scope | Dependencies | Status |
|---|------|-------|-------------|--------|
| M1 | Screenplay & Pacing Expansion | Reconstruct EP01 screenplay to 25-30m (188 shots), 3-beat Đạm Tiên sequence (C05-A, B, C), purge male crying | none | DONE |
| M2 | Universal Standards & Prompt Registry | Create Universal Acting Directives, update Gemini Banana & Muse.ai prompt registries with 188 shots (R3, R4, R5, Director Directives) | M1 | DONE |
| M3 | 4-Stem Audio Engine & Ambience Continuity | Audio crossfade concat, continuous festival ambience, 2-pass EBU R128 -14 LUFS normalization | M1 | DONE |
| M4 | Web Review Studio Sync & Production Integration | Upgrade `web_review/server.py`, sync generation schema with `run_shot.py`, verify live display on port 1515 | M2, M3 | DONE |
| M5 | Final Milestone: 100% E2E Pass & Master Assembly | Pass Tiers 1-4 test suite, Tier 5 adversarial verification, assemble EP01 Master cut, Web Studio validation | M1, M2, M3, M4 | IN_PROGRESS |

## Parallel Track: E2E Testing Track
- Governed by `TEST_INFRA.md`.
- Generates automated verification test cases covering all 13 features across Tiers 1-4.
- Publishes `TEST_READY.md`.

## Interface Contracts

### M1 (Screenplay) ↔ M2 (Prompts)
- Screenplay defines Shot IDs: `ep01_scene<XX>_shot<YY>`, duration: `10s`, camera framing, character actions, and dialogue.
- Prompt Registry keys MUST match exact Shot IDs defined in `FilmMaker/TAP_01_XUAN_SAC_THE_NGUYEN_VA_GIONG_BAO_DOAN_TRUONG.md`.

### M2 (Prompts) ↔ M3/M4 (Pipeline & Web Studio)
- `gemini_banana_prompts.json` schema: `{"ep01_sceneXX_shotYY": {"character_anchor": "...", "environment_anchor": "...", "prompt": "...", "resolution": "1280x720"}}`.
- `muse_ai_video_prompts.json` schema: `{"motion_prompts": {"ep01_sceneXX_shotYY": "..."}}`.
- Every motion prompt MUST conclude with: `Âm thanh: [Foley/Ambience]. 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.`
- If dialogue is off-screen or distant, prompt MUST contain: `[KHÓA KHẨU HÌNH BẮT BUỘC]: Đôi môi nhân vật trong khung hình khép chặt tự nhiên, không mấp máy.`

### M3 (Audio Engine) ↔ Video Outputs
- Audio input: Video clips with AAC audio.
- Normalization target: EBU R128 Integrated `-14.0 LUFS` (±0.5), True Peak `-1.0 dBTP`, LRA `9-11 LU`.
- Concat method: FFmpeg filter_complex with acrossfade or linear concat preserving AAC stereo 48kHz.

### M4 (Web Review Studio) ↔ Filesystem
- Server host: `0.0.0.0:1515`.
- Scans `04_Assets/videos/` and `06_Exports/` dynamically.
- Generation endpoint POST `/api/generate` invokes `run_shot.py` with `--shot <shot_id>`.

## Code Layout
- `00_Project_Bible/`: Bible documents and Universal Acting Directives
- `01_Scripts_And_Episodes/`: Original poetry and episode guides
- `FilmMaker/`: Screenplay files (`TAP_01_*.md`, `INDEX_VA_DANH_MUC_CANH_QUAY.md`)
- `02_AI_Prompts/`: JSON prompt registries (`gemini_banana_prompts.json`, `muse_ai_video_prompts.json`)
- `04_Assets/`: Media assets (`characters/`, `keyframes/`, `videos/`, `audio_sfx/`, `archive/`)
- `05_Production_Pipeline/`: Core python scripts (`production_orchestrator.py`, `run_shot.py`, `audio_continuity_engine.py`, `assemble_ep01_feature.py`)
- `web_review/`: Web Studio server (`server.py`, `templates/index.html`)
- `tests/`: Automated test suite for E2E testing track