video-creative-planner

name	video-creative-planner
description	Biến yêu cầu video mới (kèm Video Design Specification tùy chọn) thành creative plan, kịch bản, scene intents, overlay text và asset requirements ở mức sẵn sàng đưa vào pipeline video short-form.

Video Creative Planner

Mục tiêu

Chuyển ý tưởng video mới của user thành một creative plan có cấu trúc, để các skill phía sau (voice, asset mapping, render) có thể thực thi được.

Dùng skill này khi user đưa ra chủ đề, brief, ý tưởng sản phẩm, yêu cầu chiến dịch hoặc kịch bản nháp và muốn dựng một video TikTok/Reels/Shorts từ đó.

Quy tắc đầu ra (BẮT BUỘC)

• Mọi nội dung do AI/LLM sinh ra (script, scene_intents, mô tả, mood, overlay text, lý do, summary) bắt buộc viết bằng tiếng Việt CÓ DẤU.
• Cấm asciify (vd KHÔNG được viết "cong truong" thay cho "công trường" trong script, visual_intent, hay mô tả).
• Tags và identifier kebab-case (mood, style_ref, narrative_role) vẫn lowercase ASCII (vd: vat-va, chan-thuc).
• Tên trường, tên CLI flag, file path, tên model, JSON/TOML key giữ nguyên tiếng Anh — không được dịch.
• Nếu user yêu cầu ngôn ngữ khác (vd language = "en" trong metadata), tuân theo yêu cầu đó.

Quy tắc môi trường script

Trước khi chạy bất kỳ script nào trong skill này, đọc file .env ở repo-root trước. File này nằm cạnh jobs/, skills/, và env.example. Chỉ kiểm tra xem các key cần thiết có tồn tại hay không; tuyệt đối không in giá trị secret ra log, terminal, TOML artifact, hay phản hồi. Chỉ dùng --env-file không phải repo-root khi user yêu cầu rõ ràng.

Đầu vào

• Yêu cầu hoặc brief sáng tạo của user.
• VDS tùy chọn từ video-design-spec-builder.
• Tùy chọn: nền tảng đích, thời lượng, ngôn ngữ, ràng buộc thương hiệu, CTA, ghi chú asset có sẵn.
• Tùy chọn: asset-index DB (.asset_index/index.db) — nên truy vấn trước khi soạn scene_intents để biết thực tế đang có footage gì.

Khám phá footage có sẵn trước khi viết scene_intents

Khi watcher asset-index đang chạy, project đã biết sẵn raw asset nào tồn tại và chứa gì. Trước khi tự bịa scene_intents, nên đưa các phương án thật ra trước:

.venv/bin/python -m tools.asset_index.search "<mô tả ngắn cảnh muốn tìm bằng tiếng Việt>" --top 5

Hoặc gọi trong code agent:

from tools.asset_index.search import search_assets
hits = search_assets("cảnh người làm việc tay chân ở quê", k=5, media_type="video")
for h in hits:
    print(h["score"], h["file_path"], h["summary"])

Dùng các summary trả về để bám sát thực tế khi điền visual_intent, preferred_shot_types, asset_requirements. Nếu một visual cần thiết không có match nào ổn (score < ~0.3 toàn bộ), giữ nó dưới dạng entry asset_requirements và nói rõ với user là asset đang thiếu — không bịa.

Đầu ra

Ghi hoặc trả về TOML. Đường dẫn mặc định:

source/creative_plan.toml

Khi đã có video job tồn tại, ghi vào:

jobs/<job_id>/source/creative_plan.toml

Quy trình

1. Xác định đối tượng đích, nền tảng, thời lượng, ngôn ngữ và emotional arc.
2. Nếu có VDS, bảo toàn DNA phong cách, logic timing, text system, motion system và scene blueprint.
3. Viết kịch bản voiceover sao cho đọc tự nhiên được.
4. Dừng để user duyệt voiceover script trước khi handoff sang voice, ảnh, transcript, mapping, render plan hoặc render. Lưu script vào jobs/<job_id>/source/narration.txt nếu đang ở trong job.
5. Sau khi user duyệt rõ ràng, ghi jobs/<job_id>/source/voiceover_approval.toml với approved = true, rồi mới tiếp tục.
6. Chia kịch bản thành scene_intents — không phải lựa chọn asset cuối cùng.
7. Định nghĩa overlay text, hành vi subtitle và CTA.
8. Định nghĩa asset_requirements để asset-semantic-extractor và semantic-asset-mapper biết tìm gì.
9. Giữ identifier, dữ liệu cá nhân, chi tiết riêng tư ở mức trừu tượng trừ khi user xác nhận sở hữu và yêu cầu rõ.

Voiceover Approval Gate (BẮT BUỘC)

• Mọi creative plan có [voiceover].script dùng để sản xuất video phải được user duyệt trước khi chạy các bước downstream.
• Agent phải gửi nguyên văn script cho user và hỏi duyệt/chỉnh.
• Không chạy TTS/voice, không tạo ảnh AI, không transcribe, không map asset, không build render plan, và không render trước khi user xác nhận rõ ràng.
• Nếu user sửa script, cập nhật creative_plan.toml/narration.txt, hỏi duyệt lại, và đánh dấu mọi audio/transcript/render phụ thuộc script cũ là stale.
• Ngoại lệ duy nhất: user nói rõ muốn bỏ qua bước duyệt script hoặc cho phép tự động tiếp tục.

Hợp đồng TOML

[metadata]
title = "Tiêu đề mô tả ngắn"
language = "vi"
platform = "tiktok"
target_duration_seconds = 45
aspect_ratio = "9:16"
source_vds = "path/to/vds.md"

[creative]
audience = "..."
goal = "..."
emotional_arc = ["hook", "tension", "turn", "resolution"]
tone = "reflective"
cta = "..."

[voiceover]
script = """
Toàn bộ kịch bản đọc.
"""
delivery = "ấm, rõ, hơi cinematic"

[[scene_intents]]
id = "SC_01"
start_hint = 0.0
end_hint = 6.0
narrative_role = "hook"
spoken_text = "Câu hoặc đoạn văn dự kiến nói trong scene này."
visual_intent = "Khán giả nên thấy gì, không chọn file cụ thể."
mood = "..."
preferred_shot_types = ["close-up", "slow push-in"]
asset_requirements = ["..."]

[[text_overlays]]
id = "TXT_01"
scene_id = "SC_01"
text = "Text ngắn hiển thị trên màn hình"
role = "hook"
timing = "sync_with_scene_start"
style_ref = "MAIN_TITLE"

Giới hạn độ dài Text Overlay (1080×1920 dọc)

Text trên màn hình phải vừa với khung an toàn ~880px trên canvas rộng 1080px (~82%). Mỗi style_ref có ngưỡng max_chars cứng và mức khuyến nghị giúp text vừa 1–2 dòng mà không phải auto-shrink. Tiếng Việt và các ngôn ngữ có dấu render rộng hơn ~10% so với Latin thuần; số đếm là 0.6 char mỗi ký tự.

style_ref	max_chars (kể cả khoảng trắng)	khuyến nghị	vai trò điển hình
MAIN_TITLE	22	12–16	hook, reveal callout
PUNCH_TAG	18	10–14	punchline, viết hoa
STAT_TAG	14	6–10	số, thống kê, giá tiền
SUBTITLE_BOLD	32	18–26	callout phụ
QUOTE_TAG	36	22–30	câu trích dẫn, in nghiêng

Nếu một câu vượt max_chars của style đã chọn, áp dụng theo thứ tự:

1. Rút gọn / viết tắt trong khi giữ điểm punch (vd "Săn lấp mặt bằng = Xúc đất" → "Săn lấp = Xúc đất").
2. Tách thành hai overlay nối tiếp với start/end ghép nhau (≥0.4s gap, cùng style_ref hoặc style được ghép cặp).
3. Hạ style_ref xuống preset nhỏ hơn (MAIN_TITLE → SUBTITLE_BOLD, PUNCH_TAG → QUOTE_TAG) chỉ khi vai trò cho phép.

Renderer có auto-shrink + word-break phòng thủ, nhưng planner chịu trách nhiệm cho mục tiêu fit. Overlay vượt max_chars sẽ phát warning OVERLAY_TEXT_TOO_LONG từ video-render-plan-builder và bị nhỏ/bóp khi render.

Giới hạn mật độ Subtitle

Trang subtitle (kiểu TikTok highlight từng từ) target ≤ 26 ký tự/trang; renderer tự tách trang dài, nhưng planner nên giữ mỗi câu voiceover đọc trôi chảy, không có 8+ từ ngắn liên tiếp. Tránh số ghép quá dài trong narration ("hai mươi ba triệu năm trăm nghìn"); dùng overlay text thay thế và giữ narration ngắn.

Quy tắc chất lượng

• Kịch bản phải đọc nói được; tránh mệnh đề lồng dài.
• Scene intent nên mang tính ngữ nghĩa và tái sử dụng, không gắn vào file path.
• Không bịa asset có sẵn. Thiếu visual nào thì cho vào asset_requirements.
• Nếu VDS xung đột với yêu cầu user, ưu tiên ý user và adapt VDS một cách bảo thủ.
• Với production đầy đủ, đọc và cập nhật path qua video-job-manager thay vì dùng source/ chung.
• Mỗi [[text_overlays]].text phải thỏa len(text) <= max_chars[style_ref] (xem bảng trên).