lexuanthanhhy/MKT.LANDINGPAGE.SKILLS

mkt-full-video-with-11-hyperframe-heygen-16-9

端到端编排器：脚本 → 最终 MP4 16:9 (1920×1080) 播客-基调演讲。

输出是一个 1920×1080 的 MP4 文件，采用“说话人头 + 幻灯片”格式——HeyGen 头像位于右侧的浮动圆角框内（克劳德橙色品牌边框），左侧为现代 AI / Claude 编辑风格的幻灯片内容，并带有当幻灯片需要全屏强调时的画中画 (PIP) 缩放时刻。组合会自动烘焙以下模式——无需手动编辑。

自动烘焙模式（阶段 3 输出）

所有由编排器生成的视频都会自动包含：

1. 每个场景的 HTML 组合——由并行的 LLM 子代理（每个场景一个子代理，在一次消息中扇出）编写，而非 Python 模板：

   • 输出：compositions/scene-1.html … compositions/scene-N.html（每个场景一个文件，对任何 N 都有唯一的文件名）
   • 每个子代理读取其场景块来自 visual-plan.json + 参考文档（references/composition-patterns.md、slide-design-tokens.md、infographic-prompt-template.md），然后从头开始编写 HTML/CSS/GSAP——为该场景的特定隐喻选择正确的模式，不锁定在 5 个固定的原型上
   • 为什么用 LLM 而不用 Python：HyperFrames 拥有无数的视觉思维模式（前后对比、中心辐射式、双钟比较、三层比较、滚动磁带、英雄球体规格三重奏、终端模拟、礼盒……）。Python 生成器只知道 5 个固定的原型 → 很无聊，无法适应特定场景的隐喻，例如“滚动磁带-浪费”或“正确工具-车辆”。每个场景的 LLM 编写足够有创意，能够服务于设计意图。
   • 品牌徽标自动附加：编排器将品牌上下文（claude / chatgpt / gemini / claude-code）传递给子代理，子代理引用 assets/logos/ 中的徽标，并在模式需要时（如球体发光、工具徽章药丸、失败行图标）将其嵌入到组合中

2. 头像呼吸上的“混合钩子”视觉缩放策略（通过 generate_root_index.py 的阶段 3e）：

   • HOOK（钩子）场景：在场景持续时间内缓慢爬升 1.0 → 1.10（构建戏剧张力）
   • HOOK→BODY（钩子→主体）：快速重置 1.10 → 1.0（释放紧张感）
   • BODY（主体）场景：在 PIP-IN（画中画进入）事件时出现 1.06 打击节拍（节奏）
   • CTA（行动号召）场景：温和推 1.0 → 1.04（结束）
   • 取代了扁平的“呼吸悠悠球”——每个场景原型都有其独特的缩放运动

3. 奶油纸 B-roll PIP 交换层（分割劳动架构——重要）：

   • HTML 组合（幻灯片挂载）承载数据/等级字母/项目/徽章/标题/品牌徽标——始终开启
   • <img class="broll-image"> 奶油纸编辑插图承载隐喻/情感——全舞台 1920×1080，在其场景的 PIP 窗口期间淡入，否则淡出
   • 每一层讲述不同的一半信息（HTML = “是什么”，图片 = “为什么/感觉如何”）
   • 关键： 图片仅存在于根层（index.html 中的 <img id="broll-N">）。组合 HTML 不得嵌入 <div class="image-slot"> ——那会将 16:9 图片压缩到一个小框里 → 不好看。组合仅是数据层。
   • 图片来源：策划者技能写入 prompts.md → 用户通过 AI33/Nano Banana Pro 或 mkt-broll-image 生成 1.png-N.png
   • 全舞台 1920×1080，object-fit: contain，奶油色 #F0EEE6 信箱模式背景无缝融合

4. 头像框架品牌色彩边框（通过 generate_root_index.py 的阶段 3e）：

   • SPLIT（分割）默认状态：克劳德橙色 #d97757 3px 实线 + 6px 光晕 + 80px 外发光（温暖的品牌框架，不使用白色边框）
   • PIP（画中画）状态：紫色 #a78bfa 3px 实线 + 6px 光晕 + 60px 发光（当头像缩小时强调提示）
   • 按品牌覆盖：如果用户选择 chatgpt/gemini/claude-code 品牌强调，生成器使用匹配的强调色

5. 字幕叠加（当 compositions/captions.html 存在时默认开启）：

   • 底部居中药丸，位于 bottom: 100px，Inter 600 38px 白色，深紫边框药丸上
   • 逐短语淡入/淡出（0.18 秒），在每个块结束时硬 tl.set 消隐
   • 由 generate_captions.py 从常量的 Jinja 模板 + 每个视频的 captions.json（或回退到 Whisper 分段）生成
   • 由 generate_root_index.py 在 z-index 28 自动挂载；使用 --no-captions 禁用
   • 参见下面的阶段 3e 步骤 2

6. YouTube 订阅底部三分之一 在最后 3 秒（默认开启）：

   • 组合 yt-lower-third.html 在 data-start = total_duration - 3.0s 处挂载
   • 滑入动画 + 订阅按钮按下 + 已订阅状态切换
   • z-index 60（在所有图层之上），pointer-events: none
   • 频道名称 + 订阅者数量烘焙到 compositions/yt-lower-third.html 中（如果用户想重命名，可以编辑）
   • 禁用：generate_root_index.py --no-yt-lower-third。自定义时长：--yt-lower-third-duration 4.5

所有 5 个模式都自动烘焙——编排器无需额外步骤。用户只需渲染 1.png-N.png（阶段 3.5），那么分割劳动才完全可见。如果跳过图像生成，视频仍然可以很好地播放纯 HTML 组合（图像层不透明度为 0）。

与 9:16 兄弟技能的区别

	mkt-full-video-with-11-hyperframe-heygen (9:16)	-16-9（本技能）
宽高比	1080×1920 纵向	1920×1080 横向
布局	头像全屏 + 字幕条 + B-roll 剪切	左侧幻灯片面板 (1200) + 右侧浮动头像框 (540×880)
字幕挂载	是（TikTok 风格逐字）	默认无字幕（幻灯片视觉上承载信息）
PIP 机制	无	SPLIT ↔ PIP 过渡 — 幻灯片扩展到 1920，头像缩小到 320×420 角落
头像运动	静态全屏	呼吸悠悠球 + 场景开始推入
幻灯片样式	基于变体的模型（文章堆叠、AI 窗口、应用卡片……）	LLM 编写每个场景的组合 + 现代 AI 调色板 + 根层奶油纸 B-roll
组合作者	Python 模板	N 个并行 LLM 子代理（每个场景 1 个）
渲染目标	TikTok/Reels/Shorts	播客基调演讲 / YouTube 知识 / LinkedIn
HeyGen 渲染	720×1280 纵向	仍然是 720×1280 纵向（通过 object-position: center 25% 裁剪到横向头像框中——不是 1280×720！）

对于所有横向知识视频，选择此技能。对于所有纵向短格式，选择兄弟技能。

何时使用

• 用户有越南语脚本（60–150 秒）想要制作成播客基调演讲横向知识视频
• 用户希望输出具有“Claude AI / Anthropic 编辑”感觉：深色幻灯片背景，霓虹发光文本层级，玻璃质感卡片，根层奶油色信息图
• 主题：分享知识 / 案例研究 / 前后对比 / 工具比较 / 5 个以上技巧的列表文 — 适合幻灯片驱动，支持任意数量的场景（3、5、7、10……）
• 发布渠道：YouTube 横向视频、LinkedIn 视频、播客剪辑、网站嵌入
• 用户已有 MP3 + source.mp4 并希望重新策划阶段 3 → 编排器跳过阶段 1+2，直接进入阶段 3

不要使用此技能如果：

• 用户需要 TikTok/Reels/Shorts 纵向视频 → 使用兄弟技能 9:16
• 脚本 > 5000 字符 → 先进行语义分割
• 主题纯粹是视觉密集型（蒙太奇、音乐视频）——此技能优化用于说话人头 + 幻灯片

流水线概览

脚本（越南语，≤ 5000 字符）
    │
    ▼
[阶段 0.5 恢复检测 — 如果 voiceover.mp3 + source.mp4 已存在 → 跳过阶段 1+2]
    │
    ▼
阶段 1 ── mkt-elevenlabs-tts-to-mp3 ──────► voiceover.mp3
    │                                          │
    │                              检查点 #1 — 用户收听并审核 MP3
    │                                          │
    │                                          ▼ （OK）
阶段 2 ── heygen-mp3-to-mp4 ──────────────► source.mp4（720×1280 纵向，口型同步）
    │                                          （不渲染 1280×720）
    │
    ▼
阶段 3a ── 转录（Whisper）→ voiceover.srt + transcript.json
阶段 3b ── plan_visuals.py → visual-plan.json + prompts.md
              （策划者技能：mkt-plan-short-video-edit-16-9）
              检查点 #2 — 用户审核计划
    │
    ▼ （LLM 按场景隐喻/等级字母/项目自定义 visual-plan.json）
    │
阶段 3c ── apply_plan_to_scenes.py → scenes.json（编辑器兼容）
阶段 3d ── 🔥 扇出 N 个并行 LLM 子代理（每个场景 1 个）🔥
              → compositions/scene-1.html … scene-N.html
              （每个子代理：读取 visual-plan 场景块 + 参考 → 编写 HTML/CSS/GSAP）
阶段 3e ── scaffold_project.py（sfx/ + logos/ + avatar.jpg + yt-lower-third.html）
            generate_root_index.py → index.html（1920×1080，挂载 scene-N.html，broll 层，PIP，SFX，品牌标记，克劳德橙色头像边框）
阶段 3f ── lint + 预览（Studio @ http://localhost:3002）
            （可选阶段 3.5：通过 AI33/Nano 生成 1.png-N.png 奶油纸）
    │
    ▼
用户审核预览 Studio → “render” → npx hyperframes render → out.mp4 1920×1080

检查点：

• #1 MP3 配音 — 编排器门控（如果恢复模式则跳过）。
• #2 视觉计划 — 阶段 3b 门控（如果 auto_scenes=true 则可跳过）。
• 渲染门控 — 用户在 Studio 中确认后才渲染。

输入

输入	必需	格式/示例
主题	是	简短标题（“Claude AI 的好处”、“5 个节省 Claude token 的技巧”）
品牌强调	是	claude / chatgpt / gemini / claude-code / generic — 决定强调色调色板 + 徽标 + 头像边框颜色
脚本文本	是（除非恢复模式）	.txt/.md 文件或内联。越南语。≤ 5000 字符
输出别名	否	从主题自动派生。小写，ASCII，短横线。
场景数量	否	默认 5（钩子 / 问题 / 解决方案 / 回顾 / 行动号召）。可以是 3–10 取决于长度。5 个以上技巧的列表文可以 — 每个技巧扇出 1 个子代理 + 1 个钩子 + 1 个行动号召。
头像外观	否	1 个 ID 从 HEYGEN_AVATAR_LOOKS 环境变量获取。如果未选择则随机。
信息图模式	否	now（立即通过 mkt-broll-image 生成图像）/ scaffold（仅写入 prompts.md，用户后续手动生成）/ none。默认 scaffold。
auto_scenes	否	默认 false。true 以跳过场景大纲检查点。
start_at	否	phase_1（默认）/ phase_2 / phase_3。恢复入口点。
skip_phase_1 / skip_phase_2	否	恢复模式的布尔快捷方式（替代 start_at=phase_3）。

工作区布局

workspace/content/YYYY-MM-DD/<slug>/
├── script.txt                  # 阶段 0 — 用户提供的干净文本
├── script-tagged.txt           # 阶段 1a — 脚本 + ElevenLabs v3 音频标签（[excited]、[sigh]……）
├── voiceover.mp3               # 阶段 1b
├── voiceover.srt               # 阶段 3a（Whisper）
├── voiceover_segments.json     # 阶段 3a（词级片段）
├── source.mp4                  # 阶段 2（720×1280 纵向 — 不要渲染为横向）
├── transcript.json             # 阶段 3a（whisper 词）
├── transcript-cleaned.json     # 阶段 3a（手动修正错别字）
├── scenes-outline.json         # 阶段 3b — 检查点前大纲
├── visual-plan.json            # 阶段 3b — 完整的机器可读计划（策划者输出）
├── scenes.json                 # 阶段 3c — 编辑器兼容的 visual-plan 展开
├── prompts.md                  # 阶段 3b — 奶油纸编辑提示（每个场景 1 个）
├── 1.png  2.png  ... N.png     # 阶段 3.5 — 奶油信息图图像（每个场景 1 个），根层 broll
├── captions.json               # 阶段 3e（可选） — 编排器策划的 [{text,start,end},...]；如果缺失则回退到 voiceover_segments.json
├── compositions/
│   ├── scene-1.html            # 阶段 3d — LLM 编写，1200×1080 原生横向
│   ├── scene-2.html            # 每个场景 1 个文件，无论 N 是多少
│   ├── ...
│   ├── scene-N.html
│   ├── captions.html           # 阶段 3e — 从 captions.html.j2 + captions.json（或 Whisper 片段）生成
│   └── yt-lower-third.html     # 阶段 3e — 从技能资产自动复制
├── assets/
│   └── logos/                  # 阶段 3e — 自动复制（claude.png、chatgpt.png、gemini.jpg、claude-code.png）
├── sfx/                        # 阶段 3e — 6 个默认音效
└── index.html                  # 阶段 3e — 根组合 1920×1080

YYYY-MM-DD = 今天日期（UTC+7）。

工作流程

步骤 0 — 设置 + 恢复检测

1. 验证 len(script_text) <= 5000（如果恢复模式且没有脚本输入则跳过）。超过 → 停止。
2. 如果主题缺失则从主题派生别名。
3. 创建 workspace/content/YYYY-MM-DD/<slug>/。保存 script.txt（如果恢复且脚本已存在则跳过）。
4. 选择品牌强调色调色板（参见 references/slide-design-tokens.md）。
5. 恢复检测 — 检查工作区：
   • 如果 voiceover.mp3 + source.mp4 都存在且用户未请求重新运行 → 设置 start_at=phase_3。报告：“MP3 + source.mp4 已存在。跳过阶段 1+2。开始阶段 3。”
   • 如果只有 voiceover.mp3 → 设置 start_at=phase_2。报告：“MP3 已存在。跳过阶段 1。开始阶段 2（HeyGen）。”
   • 如果还没有任何内容 → start_at=phase_1。报告：“工作区创建于 <folder>。开始阶段 1 — ElevenLabs TTS。”
6. 用户可以通过输入标志（例如，使用 start_at=phase_3 强制跳过）覆盖恢复检测。

步骤 1 — 阶段 1：脚本 → MP3（ElevenLabs）

如果 start_at=phase_2 或 phase_3 则跳过。

此阶段分为两个子步骤：

• 1a — 音频标签丰富：编排器（LLM）读取 script.txt，插入 ElevenLabs v3 音频标签（[excited]、[curious]、[sigh]、……）与内容情感匹配，写入 script-tagged.txt。不自动运行脚本 — LLM 自己完成，因为需要按句映射语气。
• 1b — TTS 渲染：在 script-tagged.txt 上调用 mkt-elevenlabs-tts-to-mp3。子技能已默认 model_id=eleven_v3，因此接受内联标签。

1a — 生成 script-tagged.txt

（可选深入探究：references/elevenlabs-audio-tags.md 如果它存在于技能文件夹中 — 目前仅内联。不要盲目读取此路径而不先验证；如果缺失，下面的内联摘要就足够了。）核心摘要：

• Hoàng 的品牌声音（K7ewtjKRNtwwt3lKQ6M0）——越南语男性中音，对话式。适用于 [excited]、[curious]、[sigh]、[chuckles]、[sarcastic]、[whispers]（适度）。避免 [shouts]、[crying]、[sings]、音效标签（[applause]、[gunshot]……）——组合层使用单独的音效文件。
• 密度：每 8–15 秒 1 个标签。60 秒脚本 ≈ 总共 4–8 个标签。不要过度。
• 标签必须插入句中合适的位置，后跟空格，然后继续。
• 示例：Hôm nay, tôi muốn [excited] kể cho bạn nghe về một điều thú vị.

1b — TTS 渲染

使用 mkt-elevenlabs-tts-to-mp3 工具。输入：script-tagged.txt。输出：voiceover.mp3。

步骤 2 — 阶段 2：MP3 → 源 MP4（HeyGen）

如果 start_at=phase_3 则跳过。

使用 heygen-mp3-to-mp4 工具。输入：voiceover.mp3。输出：source.mp4（720×1280 纵向，口型同步）。重要：不要渲染为 1280×720 横向。

步骤 3 — 阶段 3：组合 + 渲染

如果 start_at != phase_3 则运行此步骤。

这是主要阶段。它被分解为子步骤 3a–3f：

• 3a 转录：在音频上运行 Whisper 以生成 voiceover.srt + transcript.json（词级数据）。使用 transcribe.py 或等效工具。
• 3b 视觉策划：运行 plan_visuals.py（调用 mkt-plan-short-video-edit-16-9 策划者技能）以生成 visual-plan.json + prompts.md。这为每个场景定义了视觉隐喻、等级字母、项目、徽章和奶油纸图像提示。这是一个检查点：用户可以查看和调整计划。如果 auto_scenes=true，则跳过此检查点。
• 3c 应用计划：运行 apply_plan_to_scenes.py 以展平 visual-plan.json 为 scenes.json（编辑器兼容格式）。
• 3d LLM 组合编写：扇出 N 个并行调用到 LLM（每个场景 1 个）。每个子代理接收其场景的 visual-plan.json 块 + 参考文档。每个子代理输出 compositions/scene-N.html，从头开始编写 HTML/CSS/GSAP。
• 3e 项目脚手架：
  1. 运行 scaffold_project.py 以复制默认资源：sfx/、logos/、avatar.jpg（用户选择或随机）、yt-lower-third.html。
  2. 运行 generate_root_index.py 以创建 index.html（1920×1080 根组合）。它挂载每个 scene-N.html、broll 图像层、PIP 行为、品牌头像边框、字幕（如果存在）、YouTube 水印和音效。
• 3f lint + 预览：可选。为最终检查启动一个本地服务器 http://localhost:3002。

步骤 4 — 阶段 3.5（可选）：图像生成

如果 infographic_mode=now：通过 mkt-broll-image 或手动使用 AI33/Nano 为每个场景生成奶油纸图像 1.png-N.png。

步骤 5 — 渲染

在 Studio 预览中审核后，运行：

npx hyperframes render

输出：out.mp4 1920×1080。

检查点详细信息

检查点 #1 — MP3 配音

• 目的：在继续进行 HeyGen 渲染之前，确保配音听起来自然。
• 操作：编排器等待用户确认或上传新文件。
• 跳过：如果 start_at=phase_2 或 phase_3。

检查点 #2 — 视觉计划

• 目的：确保视觉隐喻与脚本情感和品牌指南一致。
• 操作：编排器向用户显示 visual-plan.json + prompts.md 摘要。用户可以批准或请求编辑。
• 跳过：如果 auto_scenes=true。

渲染门控

• 目的：防止意外渲染。
• 操作：用户在 Studio 预览中明确单击“渲染”或运行 npx hyperframes render。

参考

• references/composition-patterns.md：HyperFrames 的视觉模式目录（前后对比、中心辐射式、双钟比较、三层比较、滚动磁带、英雄球体规格三重奏、终端模拟、礼盒等）。
• references/slide-design-tokens.md：品牌特定设计令牌（调色板、排版、间距、徽标大小、动画曲线）。
• references/infographic-prompt-template.md：用于奶油纸图像生成的提示模板。
• references/elevenlabs-audio-tags.md：ElevenLabs v3 音频标签文档（如果存在）。

故障排除

• 问题：视频渲染看起来被剪裁或拉伸。
  • 原因：source.mp4 被渲染为 1280×720 横向而不是 720×1280 纵向。
  • 解决方案：使用 heygen-mp3-to-mp4 重新生成，并指定正确的方向。
• 问题：B-roll 图像不出现。
  • 原因：图像文件 1.png-N.png 缺少或 index.html 中的文件名不匹配。
  • 解决方案：确保图像存在于工作区根目录并正确命名。
• 问题：字幕不同步。
  • 原因：captions.json 与配音时间戳不匹配。
  • 解决方案：从 voiceover_segments.json 重新生成 captions.json。
• 问题：HeyGen 头像嘴唇不同步。
  • 原因：HeyGen 渲染错误或音频格式问题。
  • 解决方案：使用正确的格式（MP3, 16kHz）重新渲染 Phase 2。