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 → 视频时长、分辨率、帧率
│
▼
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（后台运行）→ Studio 预览链接
│
▼
10. 交接给用户 ──────── 不自动渲染 MP4
预览优先规则（不可协商）： 技能在第 9 步结束，返回 Studio 预览链接。只有当用户在预览后明确确认，才会执行 MP4 渲染。
步骤 1：验证输入并规划
用户将提供：
| 输入 | 是否必需 | 格式 |
|---|---|---|
| 9:16 竖屏出镜 MP4 | 是 | 文件路径 |
| Slug/项目名称 | 否 | 若缺失，自动从文件名提取 |
| B-roll 列表 | 否 | [{path: "screenshot.png", purpose: "课程 1 — 演示测试"}, ...] |
| 视频结构 | 否 | "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 秒
- 帧率 24/25/30/60 均可 —— 输出默认为 30fps
Slug：从文件名提取，转小写、去越南语变音符、空格替换为连字符。例如 "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 等），并自动将字幕分组为每 3-5 个词的短语，遇到 >0.45 秒的间隔时断开。
关键字幕同步规则： 时间点必须严格保留 word-level 字幕中的数据。不要手动编辑时间点。如需修改文本，仅修改文本 —— 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"（第 1/2/3/N 课） → 课程场景
- "Tips số 1 / Tip 1 / Số 1"（技巧 1/提示 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 根据目的中的 "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（逐词涌入，强调渐变色）。
浮动标签（每个场景可选 1-4 个）：围绕英雄模拟的 130px 圆形标签，包含图标+数字+标签，按颜色编码（青/紫/橙/绿）并配以相应发光效果，动画从屏幕外进入并循环浮动。
旧版生成器（已弃用）
scaffold_project.py（抽象装饰元素：圆环、角落标记、扫描光效）—— 为保持向后兼容而保留，但不推荐使用。新视频请使用 scaffold_infographic_v2.py。
每个场景包含：
- 在
.scene-content上执行缩放推进入场（交替使用 1.12 倍缩放或 0.92 倍缩小） - 元素入场：眉毛文字 → 数字 → 标题（逐词涌入） → 副标题
- 场景持续期间的氛围效果（脉冲光环、呼吸、漂浮等）
- 无出场动画 —— 剪辑结束时，框架自动隐藏
子合成规则：内部时间线为 RELATIVE 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 | 开场钩子 —— 与 source 视频在 0 秒处的缩放推进同步 |
| 课程 1 开始前 0.05s | búng tay.mp3（弹指声） | 0.30 | 课程 1 揭示 |
| 课程 2 开始前 0.05s | Whoosh sound effect (1).mp3 | 0.22 | 课程 2 过渡 |
| 课程 3 开始前 0.05s | Laser.mp3 | 0.28 | 课程 3 推进 |
| 复盘开始前 0.05s | 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
关键：字幕层叠顺序
字幕子合成必须以最高 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 细节以及 JS 动画模板，请参阅 references/split-screen-pacing.md。
编辑速查表：
| 时刻 | 布局 |
|---|---|
| 开场钩子 0-12 秒 | 全脸 |
| 每个想法（数据/模拟密集） | 分屏（B-roll 在上，人脸在下） |
| 每个想法结束时（结论句前 1.4 秒） | 全脸呼吸 |
| 复盘计数器可视化 | 先 分屏，动员口号时转为 全脸 |
| CTA | 前 2 秒分屏（展示评论框），然后转为 全脸 直接提出请求 |
步骤 7.6：字幕错别字修正（Whisper 转录后）
Whisper 在处理越南语时会持续出现错误（变音符丢失、品牌拼写错误、缺少空格）。运行自动修正脚本：
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/fix_caption_typos.py \
caption-groups.json \
script.txt # 源口语脚本，用于额外的差异检查
该脚本会应用一个精心策划的修正映射（约 25 个来自以往视频的已知错误：vừa dọt → vừa rót、Cửa số → Cửa sổ、Lê tân → Lễ tân、Common Cloud → Comment Claude、Cloud AI → Claude AI、Vice → Vise、level bổ → Lovable 等），并标记源脚本中不存在的可疑令牌。
修正后，重新注入：
python3 .claude/skills/mkt-hyperframe-talking-head-video/scripts/inject_captions.py \
composition
…
[截断]