video-planner

name	video-planner
description	Từ scenes-with-timing.json → xác định content shape → viết visual_brief chi tiết → output video-plan.json. Dùng ở Bước 4, SAU KHI generate-audio đã chạy. Skill cốt lõi quyết định chất lượng visual — 80% tập trung vào "ý tưởng có hình dạng gì" và "viewer thấy + cảm gì".

Video Planner

Skill này làm một việc: biến narration + timing thành bản thiết kế visual chính xác để agent HyperFrames render ngay, không cần đoán thêm.

---

Đọc trước khi làm

1. Đọc DESIGN.md — màu, font, motion defaults
2. Đọc scenes-with-timing.json — narration, _audio.vo_duration, word timestamps, timing_anchors

_audio.scene_duration = vo_duration + 0.5s — đây là thời gian thực của scene, dùng làm duration trong output. Không thay đổi.

---

Bước 1 — Xác định Content Shape TRƯỚC

Câu hỏi quan trọng nhất không phải "nội dung nói gì" mà là "ý tưởng này có HÌNH DẠNG gì?"

Đọc narration của cảnh → phân loại vào một trong các shape dưới đây → shape đó quyết định toàn bộ visual structure.

---

Nhóm 1 — Flow & Process

Shape	Khi nào dùng	Mô tả visual
linear-flow	Các bước nối tiếp nhau	A → B → C → D theo chiều ngang hoặc dọc, mỗi node nối bằng arrow
divergent-flow	Một nguồn tạo ra nhiều kết quả	Node trung tâm ở trên/giữa, các nhánh tỏa ra phía dưới/xung quanh
convergent-flow	Nhiều thứ gộp lại thành một	Nhiều node ở trên, các lines chụm vào một node kết quả bên dưới
hourglass-flow	Nhiều → lọc → một → mở rộng	Phễu thu hẹp rồi nở ra — dùng khi có bước lọc/tổng hợp ở giữa
cycle-flow	Quy trình lặp lại không ngừng	Vòng tròn khép kín, mỗi node có arrow sang node tiếp theo
parallel-flow	Nhiều việc xảy ra đồng thời	Các track chạy song song, cùng start/end nhưng độc lập nhau
decision-tree	Rẽ nhánh theo điều kiện	Diamond ở giữa, nhánh YES/NO rẽ ra hai hướng khác nhau
funnel	Lọc từ nhiều → ít → một kết quả tinh chất	Hình phễu, từng tầng thu hẹp, tầng cuối là essence

Ví dụ áp dụng:

• "Claude Code nhận ý tưởng → tạo ra 5 loại software" → divergent-flow
• "5 loại software → đều ra tiền" → convergent-flow
• Kết hợp: Claude Code → [5 software] → TIỀN = divergent + convergent nối tiếp → hourglass

---

Nhóm 2 — Comparison & Contrast

Shape	Khi nào dùng	Mô tả visual
two-column	A vs B, cũ vs mới, có vs không	Hai cột đứng cạnh nhau, header rõ ràng
before-after	Transformation, cải thiện rõ rệt	Split đôi màn hình — trái (trước, xấu), phải (sau, tốt)
spectrum	Mức độ từ thấp → cao, từ tệ → tốt	Thanh gradient ngang, mũi tên hoặc điểm đánh dấu vị trí hiện tại
venn	Hai khái niệm có điểm giao nhau	Hai vòng tròn chồng, vùng giao là điểm chung quan trọng
quadrant	Phân loại theo 2 trục độc lập	Ma trận 2×2, trục X và Y rõ ràng, 4 góc = 4 loại
stack-rank	Ưu tiên theo thứ tự quan trọng	Danh sách xếp chồng, item #1 to nhất ở trên cùng

---

Nhóm 3 — Data & Stats

Shape	Khi nào dùng	Mô tả visual
big-number	Một con số gây shock, cần viewer dừng lại	Số khổng lồ chiếm 50–70% canvas, label context nhỏ phía dưới
counter	Đếm lên/xuống, cảm giác realtime	Số thay đổi động trong scene (animate từ 0 → target)
progress-bar	Phần trăm hoàn thành, mức độ	Thanh fill từ 0% → X%, label % hiện thị khi fill
bar-chart	So sánh nhiều giá trị cùng loại	Các cột cao thấp cạnh nhau, cột quan trọng highlight màu
growth-arrow	Xu hướng tăng trưởng theo thời gian	Đường cong đi lên + số liệu tại điểm cuối
pie-donut	Tỷ lệ phần trăm của tổng thể	Hình tròn chia phần, một phần được tách ra/highlight
dashboard	Nhiều metric cùng một lúc	Cards nhỏ xếp theo grid, mỗi card = một số liệu kèm label

---

Nhóm 4 — Structure & Hierarchy

Shape	Khi nào dùng	Mô tả visual
pyramid	Tầm quan trọng từ nền → đỉnh	Hình tam giác, tầng dưới rộng = nền tảng, đỉnh = cao nhất
concentric	Lớp core → outer layers	Vòng tròn đồng tâm, trong cùng = quan trọng nhất
network	Nhiều node kết nối nhau không theo thứ bậc	Web/spider, các node nối bằng đường, node trung tâm lớn hơn
mind-map	Một chủ đề trung tâm + nhiều nhánh ý tưởng	Node center + 4–6 nhánh xung quanh, mỗi nhánh có label
grid-cards	Nhiều item ngang hàng, không có thứ bậc	Lưới ô vuông hoặc chữ nhật, mỗi ô = một item bình đẳng
timeline	Sự kiện theo thứ tự thời gian	Đường ngang (hoặc dọc), các mốc xuất hiện lần lượt trên trục
org-chart	Cấu trúc tổ chức, phân cấp rõ ràng	Tree từ trên xuống, cấp trên → cấp dưới

---

Nhóm 5 — Narrative Moments

Shape	Khi nào dùng	Mô tả visual
title-card	Hook, bold claim, CTA, tên chủ đề	Headline chiếm canvas, tối giản, high contrast
spotlight	Nhấn mạnh một vấn đề/giải pháp duy nhất	Element trung tâm sáng, xung quanh tối hoặc mờ
reveal	Bí mật được hé lộ dần dần	Element ẩn → xuất hiện từng phần, tạo anticipation
checklist	Từng bước được xác nhận theo thứ tự	Các item, dấu ✓ hoặc icon xuất hiện lần lượt khi narration nhắc
quote-card	Câu nói nổi bật, testimonial, trích dẫn	Text lớn căn giữa + dấu "" + tên/nguồn nhỏ phía dưới
step-by-step	3–5 bước rõ ràng, viewer làm theo được	Cards xếp thẳng hàng (ngang/dọc tùy format), có số thứ tự
cta	Kêu gọi hành động kết thúc video	Badge/button nổi bật + urgency text + halo glow

---

Bước 2 — Áp dụng Shape vào Visual Brief

Sau khi chọn shape, viết visual_brief theo template 5 phần:

CONTENT SHAPE: [tên shape đã chọn + lý do ngắn gọn]

HERO FRAME: [Mô tả trạng thái đỉnh cao — khi mọi thứ đã vào vị trí đầy đủ.
             Viewer nhìn vào frame này phải hiểu ngay thông điệp chính.]

ENTRANCE: [Element nào xuất hiện trước, theo sau là gì.
           Dùng motion vocabulary: slam, bloom, drift, snap, cascade, draw-on, sweep, pulse, burst, float.
           Timing stagger: "0.2s sau", "ngay khi node xuất hiện", "đồng thời với ding"]

FOCAL MOMENT: [Một khoảnh khắc duy nhất — timestamp + điều xảy ra.
               Thường sync với SFX hoặc từ quan trọng trong VO.
               "Tại Xs: [element] [action] — đây là đỉnh cảm xúc của cảnh."]

VIEWER EMOTION: [Viewer cảm gì sau cảnh này — PHẢI cụ thể.
                 TỐT: "Viewer thấy: 'Ồ, mình chưa biết điều này'"
                 TỆ: "Viewer cảm thấy ấn tượng"]

VO SYNC: [Element nào xuất hiện/highlight khi từ nào được nói.
          Dùng timing_anchors từ scenes-with-timing.json nếu có.]

---

Bước 3 — Ví dụ Visual Brief tốt theo từng Shape

divergent-flow — "Claude Code → nhiều ý tưởng phần mềm"

CONTENT SHAPE: divergent-flow — một nguồn (Claude Code) tạo ra nhiều output (các ý tưởng).

HERO FRAME: Node "Claude Code" glow xanh ở trên cùng center. Bên dưới, 4 nodes tỏa ra: "Web App", "Mobile App", "Bot", "API Tool" — mỗi node là một card nhỏ với icon. SVG lines nối từ Claude Code xuống từng card. Toàn bộ cấu trúc chiếm 70% canvas.

ENTRANCE: Node Claude Code bloom từ center tại 0.2s. Tại 0.8s: line đầu tiên draw-on xuống → card "Web App" snap in. Lần lượt 0.5s mỗi nhánh, cascade từ trái sang phải. Mỗi ding SFX = một nhánh hoàn chỉnh.

FOCAL MOMENT: Tại 3.0s (khi cả 4 nhánh đã visible): node Claude Code pulse mạnh + glow burst — như hệ thống vừa hoàn tất khởi động.

VIEWER EMOTION: "Claude Code không chỉ viết code — nó đang generate ra hẳn một ecosystem."

VO SYNC: Khi VO nói "Web App" → card Web App xuất hiện đúng lúc.

---

hourglass-flow — "Claude Code → ý tưởng → TIỀN"

CONTENT SHAPE: hourglass-flow — divergent (Claude Code → nhiều ý tưởng) kết hợp convergent (nhiều ý tưởng → một kết quả: TIỀN).

HERO FRAME: Trên cùng: node "Claude Code" glow. Giữa: 3 nodes "Ý tưởng 1/2/3" xếp ngang. Dưới cùng: node lớn "TIỀN 💰" với glow mạnh nhất. SVG lines tạo hình hourglass — tỏa ra rồi chụm lại.

ENTRANCE: Claude Code bloom tại 0.3s. Lines tỏa xuống draw-on → 3 ý tưởng cascade snap in (0.5s, 1.0s, 1.5s). Pause 0.5s. Sau đó 3 lines convergent draw-on chụm xuống → node TIỀN bloom lớn tại điểm cuối.

FOCAL MOMENT: Tại 3.5s: node TIỀN đạt full size + glow burst mạnh + đổi màu sáng hơn — đây là payoff của toàn bộ cảnh.

VIEWER EMOTION: "Tôi hiểu rồi — đây không phải tool code, đây là tool kiếm tiền."

VO SYNC: Khi VO nói "tiền" — node TIỀN vừa xuất hiện hoặc vừa burst.

---

big-number — "15 giờ tiết kiệm mỗi tuần"

CONTENT SHAPE: big-number — một con số cần viewer dừng lại và thấm vào.

HERO FRAME: "15" chiếm 55% canvas chiều dọc, neon green, glow rực. Bên phải: "GIỜ/TUẦN" in thẳng đứng nhỏ hơn. Bên dưới: "Thời gian bạn sẽ lấy lại" — trắng, mờ nhẹ. Background radial glow tập trung vào số.

ENTRANCE: "15" impact slam từ scale 0 tại 0.1s — không drift, không fade — là cú đấm thẳng. "GIỜ/TUẦN" sweep từ phải vào 0.3s sau. Label phía dưới drift up 0.5s sau.

FOCAL MOMENT: Tại 0.5s (impact SFX): "15" scale pulse 1.08 → về 1.0 với elastic — như số đang thở.

VIEWER EMOTION: "15 giờ — tức là gần 2 ngày làm việc mỗi tuần. Mình đang lãng phí điều đó."

VO SYNC: Số "15" xuất hiện 0.2s trước khi VO nói "15 giờ" — visual dẫn trước audio.

---

checklist — "3 bước để bắt đầu"

CONTENT SHAPE: checklist — viewer cần thấy từng bước được tick off theo narration.

HERO FRAME: 3 rows xếp dọc, mỗi row: số thứ tự neon green + icon + text + dấu ✓ (xuất hiện sau cùng). Spacing đều nhau, căn giữa canvas.

ENTRANCE: Row 1 slide in từ trái tại 0.3s. Dấu ✓ appear 0.4s sau khi row visible. Row 2 tại 1.5s. Row 3 tại 2.8s. Mỗi row có SFX click khi xuất hiện.

FOCAL MOMENT: Tại 3.5s (khi row 3 và ✓ cuối visible): toàn bộ checklist có brief green flash — "done" feeling.

VIEWER EMOTION: "Chỉ 3 bước — mình làm được trong buổi sáng."

VO SYNC: VO nói "bước một" → row 1 xuất hiện. "Bước hai" → row 2. "Bước ba" → row 3.

---

Motion Vocabulary

Dùng trong visual_brief — agent HyperFrames nhận diện và implement đúng:

Từ	Ý nghĩa animation
slam	Xuất hiện mạnh từ ngoài frame, expo.out, instant
bloom	Scale từ 0 → 1 tại center, radial expand
drift	Float nhẹ y ±20–40px, power2.inOut chậm
snap	back.out(2) có bounce nhẹ, nhanh
cascade	Elements lần lượt với stagger đều
draw-on	SVG line hoặc path vẽ từ từ theo hướng
sweep	Quét ngang từ trái → phải (divider, underline)
pulse	Sine.inOut lặp lại — scale hoặc glow ambient
burst	Glow hoặc scale spike mạnh rồi fade về — focal moment
float	Up-down ambient motion chậm, liên tục
impact	Xuất hiện + scale overshoot rồi settle — cho số lớn
reveal	Clip-path hoặc opacity từng phần, như đang mở màn

---

SFX Timing

Visual event phải xảy ra ĐÚNG khi SFX phát — không trước, không sau:

SFX	Visual event tương ứng
drum-hit	Element đầu tiên slam/impact in
whoosh	Element sweep ngang hoặc transition
ding	Node kết nối xong, connection complete
click	Card/step pop in
impact	Số lớn xuất hiện
chime	CTA badge xuất hiện, scene kết thúc nhẹ nhàng
whoosh-soft	Transition mềm giữa các section

---

Clip Duration Rule (quan trọng)

Mọi clip trong sub-composition phải có data-duration đủ để tồn tại đến cuối scene.

data-duration của clip = scene_duration - data-start

Ví dụ: scene_duration = 8.0s, clip start = 1.5s → data-duration = 6.5s

Clip KHÔNG được biến mất trước khi scene kết thúc — trừ trường hợp có animation exit có chủ đích trong visual_brief.

---

Output Format

Lưu vào {project-path}/video-plan.json:

{
  "design": "DESIGN.md",
  "format": "9:16",
  "total_duration": 29.0,
  "scenes": [
    {
      "sceneId": "scene_01",
      "duration": 2.6,
      "content_shape": "big-number",
      "mood": "explosive",
      "transition": { "type": "flash-white", "duration": 0.3 },
      "sfx_picks": [
        { "id": "drum-hit", "at": 0.0, "volume": 0.6 }
      ],
      "elements": [
        { "id": "number",  "text": "3",           "role": "hero number — neon green 130px, dominates" },
        { "id": "unit",    "text": "GIỜ/NGÀY",    "role": "unit label — smaller, white" },
        { "id": "caption", "text": "để viết content?", "role": "context — muted, drift in" }
      ],
      "visual_brief": "CONTENT SHAPE: big-number...\nHERO FRAME: ...\nENTRANCE: ...\nFOCAL MOMENT: ...\nVIEWER EMOTION: ...\nVO SYNC: ...",
      "subtitle": true
    }
  ]
}

duration = _audio.scene_duration từ scenes-with-timing.json.

---

Checklist

• Đã xác định content_shape trước khi viết visual?
• Shape phù hợp với cấu trúc ý tưởng trong narration?
• visual_brief có đủ 5 phần + content_shape?
• Elements list reflect đúng shape (node/line cho flow, column cho comparison...)?
• Focal moment có timestamp cụ thể và sync với SFX?
• Viewer emotion KHÔNG phải "ấn tượng" hay "đẹp"?
• duration = _audio.scene_duration?
• Không có 2 scene liên tiếp cùng content_shape?