# Historical Project Engineering Directives & Video AI Pipeline

## 1. Hardware Profile & Capabilities
- **GPU**: NVIDIA GeForce GTX 1660 Super (6GB VRAM, Turing NVENC).
- **Encoder**: NVIDIA NVENC `hevc_nvenc` và `h264_nvenc` hỗ trợ xuất video 4K UHD ở tốc độ cao (VBR CQ 19).
- **Python Environment**: `C:\Projects\Historical\venv\Scripts\python.exe`.
- **FFmpeg**: `C:\Projects\Historical\venv\Scripts\ffmpeg.exe`.

## 2. Quy Chuẩn Local 4K PureScale Pipeline (PureVision + SPAN)
- **Mục tiêu**: Xử lý video 720p lên chuẩn 4K UHD sắc nét, khử sạch muỗi nén H.264 mà không làm vỡ hình hay bệt chi tiết.
- **Kiến trúc 2 Tầng (Two-Stage Pipeline)**:
  - **Stage 1 (Pre-Clean & Denoise)**: `models/1x_PureVision.pth` (RRDBNet 23 blocks) chạy CUDA **FP32** (~430ms/frame, ~520MB VRAM). Tuyệt đối không chạy FP16 để tránh tràn số số học (NaN).
  - **Stage 2 (Super-Resolution)**: `models/4xPurePhoto-span.pth` (Kiến trúc Swift Parameter-free Attention - SPAN) chạy CUDA **FP32** (~278ms/frame). Loại bỏ hoàn toàn 32 phép nội suy bicubic cồng kềnh của SAFMN, không cần chia tile.
  - **Stage 3 (Downsample to 4K)**: Thu nhỏ từ $5120 \times 2880$ (5K) về đúng $3840 \times 2160$ (4K UHD) bằng PyTorch CUDA Bicubic (~5ms).
  - **Stage 4 (NVENC Stream)**: Stream trực tiếp từ GPU VRAM vào `stdin` của FFmpeg `hevc_nvenc` (CQ 19, preset p4, `-bf 0 -avoid_negative_ts make_zero`, audio passthrough). Triệt tiêu hoàn toàn B-pyramid packet reordering và lỗi âm DTS gây giật văng trên các trình phát Windows/CapCut.
- **Hiệu năng thực tế trên GTX 1660 Super (6GB VRAM)**:
  - VRAM sử dụng: Đỉnh 3.75 GB / 6.1 GB (an toàn 100%, dư 2.3 GB, zero OOM).
  - Tốc độ: ~0.95 FPS (~1.06s / frame).
  - Thời gian render tập 5 phút (6,960 frames): ~2.05 giờ (nhanh gấp 8.2 lần SAFMN 12.4 giờ).
- **Mã nguồn thực thi**: `purescale_video_upscaler.py`.
- **Command thực thi**:
  ```bash
  venv\Scripts\python.exe purescale_video_upscaler.py --input downloads/ep2.mp4 --output downloads/ep2_4k_span.mp4
  ```

## 3. Quy Chuẩn Tự Động Tạo Shorts Marketing (9:16)
- **Module Thực Thi**: `shorts_maker.py` và `shorts_hook_and_thumbnail_generator.py`.
- **Cơ chế Hook 3s Giữ Chân (Swipe Rate > 78%)**:
  - Tự động gắn biểu ngữ chữ động (Kinetic Text Banner) trong 0.0s -> 3.5s với công thức Paradox / Blunder / Secret Weapon.
  - Font `Impact` kích thước 64-80pt, viền đen dày, box nền tối 65% opacity để chữ nổi bật trên mọi nền khói lửa sa trường.
- **Quy Chuẩn Ảnh Bìa Shorts (First-Frame Cover Stitching)**:
  - Khổ dọc 9:16 ($1080 \times 1920$). Bố cục vùng an toàn 3 tầng (Safe Zones):
    - *Top 35%*: Badge hoàng gia Obsidian viền vàng (`1785 NAVAL WAR`) + Tiêu đề Hook 3 dòng (Trắng - Vàng - Đỏ).
    - *Middle 30%*: Điểm hội tụ nhân vật chính / chiến hạm sa trường.
    - *Bottom 35%*: Vùng an toàn tuyệt đối, tối giản để không bị che bởi giao diện YouTube (tiêu đề, tên kênh, nút like/comment).
  - Tự động nhúng Cover Card vào frame 0.0s của video để YouTube mặc định bắt trúng ảnh bìa đẹp nhất.
- **Tăng tốc xuất file**: Tận dụng GPU NVENC (`h264_nvenc` / `hevc_nvenc`), preset `p6`, CQ 19, `-bf 0 -avoid_negative_ts make_zero`.

## 4. Runpod Cloud 4K AI Upscaling Pipeline (TensorRT PureVision + SPAN Engine)
- **Hardware**: NVIDIA GeForce RTX 4090 (24GB/48GB VRAM, 16 vCPU) trên Runpod Secure Cloud ($0.74/hr).
- **Architecture**: End-to-End TensorRT 11.3 FP16 Engine (`purescale_4k.engine`, 1.91 GB) kết hợp 3 tầng trong 1 đồ thị:
  - Tầng 1: `1x_PureVision.pth` (RRDBNet Denoise khử muỗi nén H.264).
  - Tầng 2: `4xPurePhoto-span.pth` (Swift Parameter-free Attention - SPAN Super-Resolution).
  - Tầng 3: PyTorch Bicubic Downsampling trực tiếp về chuẩn 4K UHD ($3840 \times 2160$).
- **Hiệu Năng & Chi Phí Thực Tế**:
  - Độ trễ: **69.9 ms / frame** (~13.5 FPS) — nhanh gấp 14.2 lần GPU 1660 Super cục bộ.
  - Thời gian render: ~7.3 – 8.0 phút / tập 5 phút (~6,500 frames).
  - Chi phí: ~$0.09 / tập 4K UHD (~$0.58 cho toàn bộ 6 tập EP3-EP8).
- **Encoder Triệt Tiêu Lỗi Giật Khung Hình**:
  - Stream DMA Zero-copy Pinned Memory vào FFmpeg `hevc_nvenc` với cờ bắt buộc:
    `-bf 0 -avoid_negative_ts make_zero -preset p4 -cq 19`
  - Loại bỏ hoàn toàn B-pyramid packet reordering và lỗi âm DTS.
- **Cơ Chế Bảo Vệ Chi Phí (Auto-Termination Watchdog)**:
  - `watchdog_runpod.py` chạy ngầm tại máy local giám sát `/workspace/progress.json`.
  - Tự động kéo video 4K về `content/videos_4k` ngay khi xong mỗi tập.
  - Tự động gọi API hủy Pod (`runpod.terminate_pod`) ngay khi tải xong tập cuối cùng hoặc khi phát hiện tiến trình dừng, đảm bảo không phát sinh cước thừa.
- **Trạng thái**: Hoàn tất 100% toàn bộ 8 tập (`EP1` đến `EP8`) tại `content/videos_4k/`.
## 5. Kieu Story - Medieval Literature AI Cinema Pipeline (Standalone Project)
- **Tác phẩm**: Kiệt tác *Truyện Kiều* (Đoạn Trường Tân Thanh của Nguyễn Du, văn học trung cổ public domain).
- **Thư mục dự án độc lập**: `C:\Projects\KieuStory\`.
- **Cấu trúc thời lượng 3 Giờ**:
  - 6 Tập dài 30 Phút (`01_Scripts_And_Episodes/EPISODE_GUIDE_30MIN.md`) với cấu trúc 3 hồi và Cliffhanger cao trào ở cuối mỗi tập.
  - 12 Tập ngắn 5 Phút (`01_Scripts_And_Episodes/SHORTS_STRUCTURE_5M_AND_1M.md`) tập trung vào từng vòng cung kịch tính (Climax Arcs).
  - Chuỗi Shorts 1 Phút (9:16 dọc) thiết kế tối ưu tỉ lệ giữ chân (3s Hook, 45s Climax, 10s Cliffhanger CTA).
- **AI Toolchain**:
  - Concept & Character Consistency: **Gemini Banana (Google Imagen 3)** với bộ prompt chuẩn hóa tại `02_AI_Prompts/gemini_banana_prompts.json`.
  - Motion Video Engine: **Muse.ai** (Image-to-Video & Text-to-Video) với bộ prompt chuyển động camera tại `02_AI_Prompts/muse_ai_video_prompts.json`.
- **Tuân thủ chính sách nền tảng & Giữ icon xanh kiếm tiền (YouTube Green Dollar)**:
  - Khử toàn bộ bạo lực đồ họa, máu me, thương tổn thể xác, cảnh đồi trụy.
  - Sử dụng nghệ thuật Chiaroscuro (ánh sáng tương phản / đổ bóng vách tre), biểu tượng ẩn dụ (cành hoa lê dập nát, sợi dây đàn đứt bật máu ngón tay), góc máy tâm lý (reaction shots) và tượng đồng sa trường.
## 6. Quy Chuẩn Ghép Nối 4K Hoàn Chỉnh (Cinema Omnibus Pipeline)
- **Module Thực Thi**: `concat_4k_movie.py`.
- **Thách thức kỹ thuật & Nguyên nhân lỗi Bitstream Corrupt tại 4:41**:
  - Khi render độc lập trên Runpod RTX 4090 và Local GTX 1660 Super, mỗi tập phim sinh ra bộ thông số Parameter Sets (VPS, SPS, PPS) riêng biệt (QP deltas, CTU context, profile metadata khác nhau).
  - MP4 container mặc định bóc tách SPS/PPS đưa lên header toàn cục (`hvcC`). Khi dùng FFmpeg Concat Demuxer ghép các file MP4 (`-c copy`), FFmpeg chỉ giữ lại SPS/PPS của EP1.
  - Khi phát đến EP2 (từ 04:40 - 04:41 trở đi), decoder (YouTube, VLC, Browser) cố giải mã bitstream EP2 bằng SPS/PPS của EP1 -> Lỗi nghiêm trọng: `cu_qp_delta out of range`, `Could not find ref with POC -1`, video bị đóng băng khung hình EP1 và xuất hiện nhiễu macroblock / màn hình xanh xé hình.
  - Ngoài ra: EP1-EP7 chạy audio AAC mono 24000Hz, EP8 stereo 48000Hz; EP7 có timescale 115200 (khác 12288).
- **Giải Pháp Chuẩn Hóa MPEG-TS Annex B (Zero Quality Loss & 100% Sạch Lỗi)**:
  - **Bước 1 (Chuẩn Hóa sang MPEG-TS với `hevc_mp4toannexb`)**: Stream copy 100% video stream (`-c:v copy`), chèn bộ lọc `-bsf:v hevc_mp4toannexb` để ép chèn đầy đủ in-band VPS/SPS/PPS trước mỗi keyframe/IRAP. Re-encode audio sang AAC Stereo 48,000 Hz 192kbps. Timebase tự động đồng bộ về chuẩn 90kHz tự nhiên của MPEG-TS (triệt tiêu lệch timescale ở EP7).
  - **Bước 2 (Ghép nối bitstream trực tiếp & Nhúng Metadata Chapters)**: Ghép các luồng TS và nhúng metadata `[CHAPTER]` trực tiếp vào MP4 (`-c copy -movflags +faststart`) trong ~30 giây, zero re-encode.
  - **Bước 3 (Hàng rào kiểm thử chất lượng tự động - Autonomous Quality Gate)**: Tự động chạy lệnh decode thử nghiệm tại từng điểm giao tập (start + 2s), cam kết 0 lỗi decode trước khi xuất bản.
- **Command Thực Thi**:
  ```bash
  venv\Scripts\python.exe concat_4k_movie.py
  # Kiểm tra trước mốc thời gian:
  venv\Scripts\python.exe concat_4k_movie.py --dry-run
  ```

## 7. YouTube Studio Chrome Extension & Antigravity SDK Bridge Tunnel
- **Chrome Extension (Manifest V3)**: `extension/` (v2.1)
  - Tự động điền 1-click (Tiêu đề, Mô tả kèm mốc Chapters, Tags 500 ký tự, Không dành cho trẻ em, đường dẫn Thumbnail và Video 4K) trực tiếp trên `studio.youtube.com`.
  - **Deep Shadow DOM Piercing**: Thuật toán quét đệ quy xuyên thấu các Web Components của YouTube Studio.
  - **Tự động gắn Thumbnail trực tiếp**: Nạp file JPEG qua DataTransfer API vào input upload của Studio không cần mở file dialog.
  - **Shorts Studio (9:16)**: Cắt Shorts tự động theo yêu cầu bằng GPU NVENC và quản lý kho 16 Shorts tiếp thị.
- **Antigravity SDK Bridge Service (Port 8766)**: `antigravity_bridge_service.py` (v2.1)
  - Máy chủ FastAPI chạy ngầm kết nối trực tiếp Chrome Extension với Google Antigravity Python SDK (`google.antigravity.Agent`).
  - Tích hợp endpoint `/api/shorts/create` (cắt clip 9:16 với blurred background bằng GPU NVENC) và `/api/shorts/list` (kho 16 Shorts).
  - Tối ưu hóa tiêu đề Shorts kèm hashtag `#Shorts` và liên kết kéo traffic về bản Full Movie (`c8Akru2j7ok`).
- **Chrome Tester Tunnel (Port 9222)**: `start_tester_tunnel.ps1` & `tunnel_ctl.ps1`
  - Mở cổng Remote Debugging 9222, định vị Profile `Default` (`mirsixabcf2@gmail.com`) và tự động nạp tiện ích mở rộng qua `--load-extension="C:\Projects\Historical\extension"`.

## 8. Quy Chuẩn Nhãn 4K UHD Thumbnail & Đồng Bộ Đa Định Dạng
- **Mã nguồn thực thi**: `add_4k_badge.py` và `create_full_movie_thumbnail.py`.
- **Thiết kế nhãn chuẩn**:
  - Phong cách: **Obsidian Glass Capsule** kết hợp viền **Hoàng gia Gold** (`radius=32`, outline width 6px).
  - Độ tương phản: Chữ **4K** màu vàng ánh kim (`#FFD700`) + **UHD** màu trắng tinh khiết (`#FFFFFF`), font `arialbd.ttf` (size 105 trên 4K).
  - Đổ bóng: Outer Drop Shadow (`(0, 0, 0, 180)` offset 8px) chống chìm trên mọi cảnh trời hoặc khói lửa.
  - Tọa độ chuẩn: Góc trên bên phải (`x: 3143..3703`, `y: 105..317` trên bản 3840x2160), cân bằng hoàn hảo với nhãn đỏ bên trái (`EPISODE XX` / `FULL DOCUMENTARY`).
- **Tuân thủ quy chuẩn YouTube (< 2.0 MB)**:
  - Tự động nén thông minh (Dynamic Quality 92-94) giữ file JPG 4K UHD luôn ở mức 1.15MB - 1.72MB, tránh 100% lỗi bị YouTube Studio từ chối do vượt dung lượng 2MB.
  - Lưu trữ song song bản 4K PNG lossless (9-11MB) để lưu trữ gốc.
- **Quy Chuẩn Ngôn Ngữ Quốc Tế 100% Tiếng Anh (English Standardization)**:
  - Tất cả Thumbnail của toàn bộ 8 tập (`EP1` đến `EP8`) và `Full Movie Omnibus` bắt buộc sử dụng 100% tiếng Anh đồng bộ:
    - Góc trên trái: Badge đỏ hoàng gia `EPISODE 01` đến `EPISODE 08` (hoặc `FULL DOCUMENTARY`).
    - Dưới đáy: Tiêu đề súc tích chữ vàng đồng `#FFD700` (`PRINCE IN EXILE`, `50,000 INVADERS`, `LAND IN FLAMES`, `THE COUNTERATTACK`, `THE RIVER AMBUSH`, `THE FIRE BOATS`, `THE FLEET DESTROYED`, `LESSONS OF WAR`).
    - Góc trên phải: Nhãn `4K UHD` chuẩn Obsidian Gold Capsule.
  - Tuyệt đối không dùng tiếng Việt trên Thumbnail để giữ chuẩn điện ảnh quốc tế.
- **Đồng bộ 2 tầng thư mục**:
  - `content/thumbnails_4k/`: Đầy đủ bản 4K UHD (3840x2160) JPG & PNG cho EP1 đến EP8 và Full Movie.
  - `content/thumbnails/`: Đồng bộ tự động phiên bản 1080p/720p phục vụ API Bridge Service (`/api/thumbnail/{key}`) và Chrome Extension 1-click upload.

## 9. Bộ Quản Trị Tự Hành YouTube Studio (Playwright Stealth & invisible_playwright)
- **Mục tiêu**: Giải phóng hoàn toàn sức lao động thủ công của Creator để tập trung 100% vào sáng tạo nội dung; Agent tự động đảm nhiệm khâu đăng tải, điền thông tin và tối ưu hóa kênh.
- **Mã nguồn thực thi**: `youtube_studio_manager.py`.
- **Cơ chế Kiến Trúc Đa Động Cơ (Dual-Engine Architecture)**:
  - **Động cơ 1 (Chrome Stealth + Extension Tự Làm - Khuyên dùng mặc định)**:
    - Chạy Playwright Chromium targeting Google Chrome với các cờ chống phát hiện tự động hóa: `ignore_default_args=["--enable-automation"]`, `--disable-blink-features=AutomationControlled`, `--exclude-switches=enable-automation`, `--disable-infobars`, `--disable-features=IsolateOrigins,site-per-process`, kết hợp script `page.add_init_script` triệt tiêu dấu vết `navigator.webdriver`.
    - Nạp trực tiếp Extension Manifest V3 (`extension/`) để kích hoạt 1-click Autofill, inject Thumbnail và quản lý Shorts.
    - Lưu trữ Profile riêng biệt tại `content/browser_profiles/chrome_mirsixabcf2/` (tránh hoàn toàn rào cản SingletonLock và bảo vệ mã hóa App-Bound Encryption của Windows 11).
  - **Động cơ 2 (invisible_playwright - Firefox C++ Engine)**:
    - Sử dụng lõi Camoufox C++ đã qua mặt 100% các bài kiểm tra Bot/Fingerprint (Sannysoft/Cloudflare).
    - Lưu Profile riêng tại `content/browser_profiles/invisible_firefox/`.
    - Tự động hóa qua Playwright Shadow DOM locators trực tiếp, không phụ thuộc vào Chrome Extension.
- **Quy Trình Thiết Lập Xác Thực 1 Lần Duy Nhất (Native Clean Login - 100% Zero-Bot Flag)**:
  - Khâu đăng nhập nhạy cảm được tách biệt hoàn toàn khỏi Playwright: khởi chạy Chrome chính chủ nguyên bản qua `subprocess` không mang bất kỳ cờ tự động hóa hay CDP pipe nào (`navigator.webdriver` mặc định là `undefined`), triệt tiêu 100% lỗi Google chặn *"This browser or app may not be secure"*.
  - Chạy lệnh: `venv\Scripts\python.exe youtube_studio_manager.py --login`
  - Người dùng đăng nhập tài khoản `mirsixabcf2@gmail.com` một lần duy nhất trên cửa sổ hiển thị và bấm Enter trên console sau khi vào Studio.
  - Hệ thống lưu vĩnh viễn khóa giải mã App-Bound Encryption và session vào Profile.
- **Các Lệnh Vận Hành Tự Hành**:
  - `venv\Scripts\python.exe youtube_studio_manager.py --status`: Quét trạng thái video và chụp ảnh báo cáo.
  - `venv\Scripts\python.exe youtube_studio_manager.py --ep 1`: Tự động nạp Metadata & Thumbnail Tập 1.
  - `venv\Scripts\python.exe youtube_studio_manager.py --upload full`: Tự động upload bản 4K Omnibus 36 phút, nạp đầy đủ tiêu đề tiếng Anh, Chapters, Tags và Thumbnail 4K UHD.
  - Thêm cờ `--headless` khi muốn hệ thống chạy ngầm hoàn toàn trong nền.

## 10. Hệ Thống Quy Chuẩn Pháp Lý & Chính Sách Kiếm Tiền YouTube (`yt-rule/`)
- **Kho tài liệu chuẩn hóa**: Toàn bộ chính sách kiếm tiền và nguyên tắc cộng đồng từ Google Support được lưu tại thư mục `yt-rule/`:
  - `yt-rule/01_chinh_sach_kiem_tien_kenh_youtube.md`: Quy định cốt lõi YPP, chống nội dung không chân thực (Inauthentic/Mass-produced AI) và nội dung sử dụng lại (Reused Content).
  - `yt-rule/02_nguyen_tac_noi_dung_phu_hop_nha_quang_cao.md`: Tiêu chuẩn bật Icon Xanh (Advertiser-Friendly), quy chuẩn xử lý cảnh chiến tranh/bạo lực.
  - `yt-rule/03_dieu_kien_tham_gia_chuong_trinh_doi_tac_ypp.md`: Ngưỡng 1.000 subs + 4.000h xem / 10M view Shorts, thủ tục AdSense.
  - `yt-rule/04_chinh_sach_kiem_tien_youtube_shorts.md`: Quỹ Doanh thu gộp (Creator Pool 45%), bản quyền âm nhạc trên Shorts.
  - `yt-rule/05_cong_bo_su_dung_ai_tao_sinh.md`: Quy định gắn nhãn AI (Altered/Synthetic Content) và các trường hợp miễn trừ.
  - `yt-rule/06_chinh_sach_chuong_trinh_adsense.md`: Chống gian lận click và lưu lượng không hợp lệ.
  - `yt-rule/07_nguyen_tac_cong_dong_va_ban_quyen.md`: 3 gậy bản quyền, Content ID và Fair Use.
  - `yt-rule/08_QUY_CHUAN_SAN_XUAT_NOI_DUNG_KENH_LICH_SU.md`: Sổ tay SOP thực chiến cho kênh Historical (7s đầu tiên, nghệ thuật Chiaroscuro/tượng đồng khử bạo lực, Thumbnail < 2MB đạt chuẩn 4K).