mkt-hyperframe-talking-head-video
封裝管線：從預錄的 MP4（9:16 說話者影片）到完整的 HyperFrames 預覽專案，包含字幕、音效、縮放鉤子、具有豐富效果的全面 B-Roll 場景以及 CTA 結尾。
使用時機
- 使用者已錄製好一個 9:16 的正面拍攝影片（TikTok/Reels/Shorts），並希望加入字幕、視覺鉤子和音效。
- 使用者還有一些想要插入的 B-Roll 圖片或影片（附帶使用目的）。
- 使用者想要輸出預覽 Studio 來在渲染 MP4 之前瀏覽視覺效果。
請勿在以下情況使用此技能：
- 使用者尚未錄製影片 — 請改用
mkt-create-script-short-video來先撰寫腳本，或其他技能來建立 AI 配音和虛擬角色。 - 使用者已有 HyperFrames 專案，只想進行細微調整 — 直接修改檔案，而不是重新建立整個專案。
- 使用者想要從現有專案渲染 MP4 — 直接執行
npx hyperframes render。
管線概覽
MP4 9:16 說話者影片 +（可選）B-Roll 檔案
│
▼
1. 檢查 MP4 ────────── ffprobe → 時長、解析度、FPS
│
▼
2. 規劃結構 ────────── 從使用者輸入或轉錄稿中自動偵測課程標記
│
▼
3. 轉錄 ──────────────── npx hyperframes transcribe --model medium --language vi
│
▼
4. 清理轉錄稿 ──────── 套用越南語 Whisper 錯誤字典（alphabit→Alphabet 等）
│
▼
5. 分組字幕 ────────── 每組 3-5 個詞，在 >0.45 秒間隔處斷開，保留時間戳
│
▼
6. 配對 B-Roll ──────── 詢問使用者目的 → 分配給課程場景
│
▼
7. 建立專案結構 ────── workspace/video-projects/<slug>/
├── index.html (根目錄)
├── source.mp4
├── transcript.json + caption-groups.json
├── compositions/
│ ├── captions.html
│ ├── fs-lesson-N.html (每個課程一個，效果各異)
│ ├── recap-card.html (如適用)
│ └── fs-cta.html
└── sfx/ (6 種音效)
│
▼
8. 語法檢查 ──────────── npx hyperframes lint → 修復任何錯誤
│
▼
9. 開啟預覽 ──────────── npx hyperframes preview (背景) → URL Studio
│
▼
10. 移交給使用者 ─────── 不自動渲染 MP4
預覽優先規則（不可協商）： 技能在步驟 9 結束，提供 Studio URL。僅在使用者在預覽後明確確認時，才執行 MP4 渲染。
步驟 1：驗證輸入並規劃
使用者將提供：
| 輸入 | 必要 | 格式 |
|---|---|---|
| 正面拍攝 MP4 9:16 | 是 | 檔案路徑 |
| 專案名稱 | 否 | 若缺少則從檔名自動衍生 |
| B-Roll 清單 | 否 | [{path: "screenshot.png", purpose: "Bài học 1 — minh họa thử nghiệm"}, ...] |
| 影片結構 | 否 | "3 項課程 + 介紹 + CTA" / "5 個技巧" 等 — 若缺少則自動偵測 |
先檢查 MP4：
ffprobe -v error -show_entries format=duration:stream=codec_type,width,height,r_frame_rate \
-of json "<mp4_path>"
驗證：
- 解析度為 9:16（例如 1080x1920, 1440x2560）— 如果是橫向，發出警告但仍繼續（object-fit:cover 會裁切）
- 時長 < 180 秒為理想；大於 180 秒仍可，但警告使用者 TikTok 演算法偏好 ≤90 秒
- FPS 24/25/30/60 皆可 — 輸出預設為 30fps
專案名稱：從檔名衍生，轉為小寫，越南語重音字 → ASCII，空格 → 破折號。例如 "3 bài học .mp4" → 3-bai-hoc。使用者可覆蓋。
輸出目錄：workspace/video-projects/<slug>/
步驟 2：轉錄並清理
cd workspace/video-projects/<slug>/
cp <user_mp4> source.mp4
npx hyperframes transcribe source.mp4 --model medium --language vi
絕不對越南語音頻使用 --model medium.en 或 small.en — .en 模型會翻譯成英文，而非轉錄。務必對越南語音頻使用 --language vi。
完成後，清理轉錄稿：
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/clean_transcript.py \
transcript.json
# 寫入：transcript.json（原地清理）+ caption-groups.json（自動分組）
腳本已套用越南語 Whisper 錯誤替換（alphabit→Alphabet, Cod→Code, 根據上下文的 dụng/dùng, đ��ng→đắc 等），並在 >0.45 秒間隔處斷開，自動分組為 3-5 個詞的字幕片語。
關鍵的字幕同步規則： 時間戳必須完全保留詞級轉錄稿中的時間。不得手動編輯時間戳。如果需要修改文字，只修改文字 — clean_transcript.py 腳本已經處理。典型的錯誤：手動編輯文字時意外修改了時間戳，導致影片中間的字幕偏移 5 秒。
步驟 3：偵測場景結構
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/detect_scenes.py \
transcript.json
# 輸出：scenes.json
腳本在轉錄稿中尋找以下標記：
- "Bài học đầu tiên / thứ 2 / thứ 3 / thứ N" → 課程場景
- "Tips số 1 / Tip 1 / Số 1" → 技巧場景
- "Tổng kết lại / Recap / Kết luận" → 回顧時刻
- "Comment / Đăng ký / Like / Theo dõi" → CTA 時刻
輸出 scenes.json：
{
"type": "lessons",
"scenes": [
{ "kind": "lesson", "num": 1, "start": 9.4, "end": 13.0, "kicker": "Bài học #1", "heading": "..." },
{ "kind": "lesson", "num": 2, "start": 34.5, "end": 38.0, ... },
{ "kind": "lesson", "num": 3, "start": 61.5, "end": 65.5, ... },
{ "kind": "recap", "start": 84.9, "end": 99.0 },
{ "kind": "cta", "start": 99.0, "end": 106.94 }
]
}
如果自動偵測找不到明確的結構（例如 vlog 自由形式），則向使用者顯示結果並請求確認。使用者可以覆蓋時間戳。
步驟 4：配對 B-Roll
如果使用者提供了帶有目的的 B-Roll 檔案：
[
{ path: "alphabet-screenshot.png", purpose: "Bài học 1 — Alphabet ship beta" },
{ path: "clock-icon.mp4", purpose: "Bài học 2 — minh họa 24h" },
{ path: "team-meeting.png", purpose: "Bài học 3 — bỏ rào cản team" }
]
配對邏輯：
- 每個 B-Roll 根據 purpose 中的文字 "Bài học N" 匹配一個場景
- 圖片 → 用作該場景的全螢幕背景（替換純文字生成的場景）
- 影片 → 用作全螢幕場景背景或畫中畫疊層（預設：全螢幕）
- 預設場景效果（脈衝環、角落標記等）仍然疊加在 B-Roll 圖片/影片的上方
如果使用者未提供 B-Roll，則使用純文字場景（如參考專案 3-bai-hoc/）— 生成帶有標題、大數字和副標題的文字卡片。
步驟 5：生成專案檔案（資訊圖表風格 — 預設）
使用資訊圖表 v2 生成器來建立以內容驅動的模擬 B-Roll（Hostinger 風格：深色玻璃態 + 霓虹光暈 + UI 模擬 + 浮動資料徽章）：
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/scaffold_infographic_v2.py \
--output workspace/content/YYYY-MM-DD/<slug>/compositions/ \
--scenes scenes.json
scenes.json 結構（每個場景，包含 mockup_variant + content）：
{
"scenes": [
{
"kind": "lesson",
"num": 1,
"start": 12.71,
"end": 26.40,
"kicker": "Tư vấn AI",
"heading": "Tư vấn AI cho 1 ngành",
"accent_words": [2],
"mockup_variant": "post-stack",
"content": { "posts": [...] },
"badges": [
{ "pos": "tr", "color": "orange", "icon": "📅", "num": "30", "label": "Ngày" }
]
},
{ "kind": "recap", "mockup_variant": "team-grid", "content": {...} },
{ "kind": "cta", "mockup_variant": "comment-box", "content": {...} }
]
}
7 種模擬變體 — 選擇符合場景語義的一種：
| 場景類型 | 變體 | 用途 |
|---|---|---|
| 個人品牌/發文 | post-stack | 3 張社群卡片堆疊，頂部高亮顯示互動 |
| AI 搜尋/GEO | ai-window | ChatGPT 風格視窗，推薦卡片高亮 |
| 語音/電話/通話 | phone-call | iPhone 模擬機，包含波形、代理氣泡和插槽網格 |
| 分析/儀表板 | dashboard | 玻璃卡片，包含統計數據、創意網格和圖表線 |
| 產品/SaaS 發布 | app-card | 應用卡片，包含圖示、統計數據和可選的隱喻行 |
| 前後對比回顧 | team-grid | 40 點網格變形，帶有動畫倒數和乘數 |
| CTA "評論 X" | comment-box | 評論框模擬 + 2 張禮品卡 + CTA 藥丸按鈕 |
完整內容結構 + 設計標記：請參閱 references/infographic-design-system.md。
通用外殼元素（自動套用於每個場景）：徑向漸變背景 + 青色網格線 + 10 個 SVG 粒子（飄移循環）+ 暗角 + 主題藥丸按鈕（橙色光暈）+ 品牌標題 110px（逐詞 slam-in，強調漸變）。
浮動徽章（每個場景可選 1-4 個）：主要模擬圖周圍的 130px 圓形徽章，包含圖示、數字和標籤，顏色編碼（青色/紫色/橙色/綠色），帶有匹配的光暈，從螢幕外動畫進入並循環擺動。
傳統生成器（已棄用）
scaffold_project.py（環形/角落/光掃描抽象裝飾）— 保留以實現向後相容，但不推薦使用。新影片請使用 scaffold_infographic_v2.py。
每個場景包含：
- 在
.scene-content上進行衝擊式縮放進入（交替縮放 1.12 / 縮小 0.92） - 元素進入順序：眉題 → 數字 → 標題（逐詞 slam） → 副標題
- 場景中的環境效果（脈衝環、呼吸、飄移等）
- 無退出動畫 — 片段結束，框架隱藏
子組合規則：內部時間軸相對於 0 → data-duration，而非絕對時間。在根目錄中使用 data-composition-src="compositions/<name>.html" 掛載，並設定 data-start = scene.start。
步驟 6：複製音效
mkdir -p workspace/video-projects/<slug>/sfx
SFX_SRC="$(git rev-parse --show-toplevel)/.claude/skills/mkt-hyperframe-talking-head-video/assets/sfx"
cp "$SFX_SRC"/{camera-flash.mp3,"búng tay.mp3","Whoosh sound effect (1).mp3",Laser.mp3,ting.mp3,"Discord Notification - Sound Effect.mp3"} workspace/video-projects/<slug>/sfx/
6 種音效標準對應：
| 時間 | 檔案 | 音量 | 時刻 |
|---|---|---|---|
| 0.0s | camera-flash.mp3 | 0.32 | 鉤子開場 — 與來源影片在 0 秒處的衝擊縮放同步 |
| 課程 1 開始前 0.05 秒 | búng tay.mp3 (彈指聲) | 0.30 | 課程 1 揭露 |
| 課程 2 開始前 0.05 秒 | Whoosh sound effect (1).mp3 | 0.22 | 課程 2 轉場 |
| 課程 3 開始前 0.05 秒 | Laser.mp3 | 0.28 | 課程 3 衝擊 |
| 回顧開始前 0.05 秒 | ting.mp3 | 0.20 | 回顧揭露 |
| CTA 開始時 | Discord Notification - Sound Effect.mp3 | 0.28 | CTA 通知感 |
音效音量規則（參閱 references/sfx-library.md）： 鉤子 0.25-0.35，轉場 0.15-0.2，CTA 0.25。最多 5-6 個音效，間隔 ≥1.5 秒。
步驟 7：語法檢查 + 開啟預覽
cd workspace/content/YYYY-MM-DD/<slug>/
npx hyperframes lint
接受警告：
composition_file_too_large— 僅供參考，根目錄可忽略composition_self_attribute_selector— 僅供參考，資訊圖表模擬使用限定的[data-composition-id="..."]選擇器
拒絕錯誤：
gsap_animates_clip_element— 不得在 clip 上動畫化 visibility/display — 只動畫化 opacityroot_composition_missing_data_start— 子組合必須在內部 div 上設定data-start="0"media_missing_data_start—<audio>音效必須有data-start屬性（HF 原生排程，不使用 JS 觸發）- 字幕同步問題 — 重新執行
clean_transcript.py腳本
關鍵：字幕 Z 軸順序
字幕子組合必須使用最高的 data-track-index 掛載，以便顯示在課程子組合（具有全螢幕深色背景）之上。否則字幕會被 B-Roll 遮擋。
<!-- 課程/回顧/CTA 掛載：track-index 40-47 -->
<div class="clip split-mount" data-composition-src="compositions/fs-lesson-1.html" data-start="..." data-track-index="40"></div>
<!-- ... -->
<!-- 字幕最後掛載，track 60 + 內聯 z-index -->
<div class="clip captions-mount"
data-composition-src="compositions/captions.html"
data-start="0" data-duration="..." data-track-index="60"
style="z-index: 100;"></div>
步驟 7.5：分割畫面 + 全臉呼吸佈局（說話者影片 + B-Roll 推薦）
對於任何需要說話者臉部和 B-Roll 模擬圖同時可見的影片請使用此佈局 — 而不是用全螢幕 B-Roll 遮擋臉部。
架構：
- 臉部影片在介紹期間預設為全螢幕
- 當 B-Roll 出現時：臉部縮小到下半部分（1080x960），B-Roll 在上半部分渲染（縮放 0.5）
- 在每個 B-Roll 結束時（下一個場景開始前 1.5 秒）：臉部擴展回全螢幕（"呼吸"時刻）→ 捕捉情緒爆點
- 字幕在中間（分割模式）和底部（全臉模式）之間自動動畫化
生成帶有預先烘焙分割畫面的根目錄 index.html：
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/generate_root_index.py \
--output workspace/content/YYYY-MM-DD/<slug>/index.html \
--scenes scenes.json \
--total-duration 108.92 \
--header-label "6 AI BUSINESS 2026" \
--footer-handle "@tranvanhoang.com"
scenes.json 必須為每個場景包含 brollEnd + hasBreath。有關編輯規則（何時全螢幕 vs. 分割），CSS ...
[原內容因長度截斷]