use-screenkite-advanced-b-roll

use-screenkite-advanced-b-roll

用途

在 ScreenKite 录制内容的屏幕 + 摄像头合成画面上叠加简短的动画 B-roll 视觉素材。屏幕录制始终是主要内容；B-roll 只是短暂点缀（4–6 秒的角落画中画），出现后留出时间让观众阅读，然后通过 magicMove 消失。

流程（7 个阶段）

1. Locate mic audio in .skbundle
2. Transcribe with ElevenLabs Scribe  → word-level JSON
3. Pack to phrase view  + proofread via web search
4. Propose visual idea menu with density bundles
5. Scaffold N Hyperframes projects (one per visual slot)
6. Dispatch parallel sub-agents → each writes one index.html
7. Render each to MP4  →  apply setSceneLayout DSL with magicMove

先决条件（开始前检查）

• macOS 上的 ScreenKite.app，路径为 /Applications/ScreenKite.app。
• PATH 中有 Node ≥ 22 和 FFmpeg。
• uv（推荐）——快速的 Python 脚本运行器。如果可用，优先使用 uv run 而非 python3——它会通过 PEP 723 内联元数据自动安装依赖（无需手动运行 pip install）。安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh。如果未安装 uv，则回退到 python3（你需要手动运行 pip install requests，以供 transcribe_mic.py 使用）。
• 项目 .env 中的 ELEVEN_LABS_API_KEY（注意：不是 ELEVENLABS_API_KEY——本仓库使用带下划线的形式）。**如果缺少密钥或 .env 不存在，请先向用户索取密钥，再继续操作。**不要静默失败或跳过转录。
• Hyperframes CLI——通过 npx hyperframes 调用（首次使用时会自动安装）。仓库：https://github.com/heygen-com/hyperframes
• Hyperframes Agent 技能（可选，但有助于子 Agent）：npx skills add heygen-com/hyperframes——注册 hyperframes、hyperframes-cli、gsap 技能。
• video-use 辅助工具（随附副本位于 scripts/transcribe_mic.py 和 scripts/pack_transcripts.py；上游仓库：https://github.com/browser-use/video-use）。

如果缺少任何内容，请指导用户安装后再继续。请参阅 references/external-tools.md。

阶段 1 — 定位麦克风音频

ScreenKite .skbundle 是一个目录。麦克风音频位于 <bundle>/media/microphone_*.m4a。屏幕录制位于 <bundle>/media/screen_*.mp4，摄像头录制位于 <bundle>/media/camera_*.mov，系统音频位于 <bundle>/media/system_audio_*.m4a。

确认项目已在 ScreenKite 中打开（以便后续 CLI 调用使用当前项目）：

'/Applications/ScreenKite.app/Contents/MacOS/ScreenKite' agent project open --path '<bundle path>' --json
'/Applications/ScreenKite.app/Contents/MacOS/ScreenKite' agent project current --json

阶段 2 — 转录

使用 scripts/transcribe_mic.py——这是 ElevenLabs Scribe 的轻量封装，会从项目 .env 读取 ELEVEN_LABS_API_KEY，并按源文件缓存结果。优先使用 uv run（通过 PEP 723 内联元数据自动安装 requests）；如果已安装 requests，也可以使用 python3。

**运行前：**确认项目 .env 中存在 ELEVEN_LABS_API_KEY。如果不存在，请停止并向用户索取密钥。继续操作前，将密钥写入 .env，格式为 ELEVEN_LABS_API_KEY=<key>。

uv run scripts/transcribe_mic.py \
  '<bundle>/media/microphone_dji-mic-mini.m4a' \
  --edit-dir '.' \
  --language zho \
  --num-speakers 1

--edit-dir 默认为当前工作区目录（.），因此转录文本、打包视图和 B-roll 都会与 Agent 的工作树放在一起。也可以传入 --edit-dir '<bundle-parent>/<project-slug>-edit'，将输出放在 .skbundle 旁边。

输出：<edit-dir>/transcripts/microphone_*.json（逐词、带说话人区分和音频事件信息；3 分钟音频约为 155KB）。

缓存：如果输出文件已存在，则跳过重新上传。

阶段 3 — 打包并校对

3a. 打包为短语级视图

uv run scripts/pack_transcripts.py --edit-dir '<edit-dir>'

生成 <edit-dir>/takes_packed.md——短语会在静音时长 ≥ 0.5 秒处断开。比原始 JSON 精简 10 倍。

3b. 校对——涉及任何英文产品名／专有名词时都必须执行

ASR 经常会在说话者切换语言时误识别专有名词。在一个衍生会话中，Scribe 在整段中文录音里始终把「Claude」听成了「Cloud」。每个此类误识别都会传播到生成的视觉内容中。

**规则：**在进入阶段 4 之前，检查整理后的转录文本，找出任何看起来像产品名的英文单词。对每个单词，使用 WebSearch 核实：

• 是否确有这个产品，且拼写完全一致？
• 上下文是否一致（发布日期、功能、定位）？
• 标准大小写是什么？

将校正后的版本写入 <edit-dir>/takes_packed_proofread.md，并附上一张简短的差异表，说明校正了什么以及原因。

**即使看起来显而易见，也不要跳过此步骤。**七个视觉片段都用错产品名，会浪费 15 分钟以上的渲染时间。

阶段 4 — 视觉创意菜单 + 密度

1. **提出菜单。**阅读 references/visual-ideas-menu.md，了解大量适合不同节拍的视觉创意。按节拍提出菜单（开场／工具名称／类比／功能亮点／定价／结尾等）。

2. 提供密度组合：

密度	数量	节奏	适用场景
稀疏	4	间隔约 40 秒	纪录片风格
中等	7	间隔约 24 秒	默认——均衡
密集	11–13	间隔约 13 秒	讲解类视频的活力节奏
超密集	15+	短语级	最大限度提升短视频留存率

默认选择中等（7），除非用户另有要求。B-roll 是屏幕录制教程中的点缀，而不是主角。

3. **等待确认。**用户批准某个组合前，不要搭建项目。

阶段 5 — 搭建 N 个 Hyperframes 项目

每个槽位一个 Hyperframes 项目，全部放在 <video-project-root>/broll/slot_XX/ 下：

broll/
├── slot_01/
│   ├── hyperframes.json
│   ├── index.html          (written in Phase 6)
│   └── assets/              (logos, images referenced by index.html)
├── slot_02/ ... slot_NN/

使用 uv run scripts/scaffold_slots.py <broll-dir> <count> 创建目录和 hyperframes.json 桩文件。如果某个槽位需要 Logo／素材文件（例如 ScreenKite 自我推广），请将其复制到对应的 slot_XX/assets/ 文件夹中。

阶段 6 — 并行子 Agent 构建各自的 index.html

在同一条消息中派发 N 个子 Agent（一次响应中发起的每个 Agent 工具调用都会并行执行）。每份 Agent 任务说明都必须完整自洽。使用 references/subagent-brief-template.md 作为模板——其中包含下方的所有硬性规则。

每份任务说明都必须包含的硬性规则

完整清单见 references/hyperframes-contract.md。关键规则如下：

1. **内容必须填满整个 1920×1080 MP4 画面。**MP4 本身就是画中画（PiP）——ScreenKite 使用 placeSelf="topRight" width="40%" 放置时，整个画面都会出现在角落中。不要把内容放在 MP4 画面内的某个小角落（否则它会埋在角落中的角落里）。使用暖奶油色全幅背景，将内容居中并调整大小以填满画面。

2. **时间线结构：入场 → 稳定停留 → 不要添加内部退场。**ScreenKite 的 magicMove 会处理退场。如果构图自身也带有退场动画，观众就会看到双重退场。结构如下：

   • 0.0 – 1.5s：入场动画（弹出、滑动、弹跳）
   • 1.5 – end：稳定停留——视觉内容清晰可读，仅有轻微的环境动态效果
   • 最后 0.5 秒内不要添加淡出／缩小退出动画。

3. **构图时长 ≥ DSL 窗口时长 + 1.5–2 秒阅读停留时间。**入场结束后，观众需要时间阅读。5 秒的 DSL 窗口至少需要 3.5 秒的入场后停留时间。不要让视觉内容一闪而过。

4. **使用同步时间线，保持暂停，并注册到 window.__timelines["main"]。**不要使用 async、setTimeout、Promise。不要使用 Math.random、Date.now、repeat: -1。重复次数必须有限：repeat: Math.ceil(holdLen / cycleLen) - 1。

5. **使用独立构图（不要使用 <template> 包装器）。**根 div 直接放在 <body> 中。样板代码见 references/dsl-cookbook.md。

6. **完成前运行 Lint。**每个 Agent 都要在槽位目录中运行 npx hyperframes lint --json，修复错误，并报告警告。

启动子 Agent

在一条消息中启动 N 个 Agent 工具调用，全部设置 run_in_background: true。每条提示词都应包含：

• 绝对输出路径：<broll>/slot_XX/index.html
• 插槽内容规范（展示什么、文本内容、图标）
• 调色板（十六进制值——不要写“自行选择颜色”）
• 字号（大号——显示文字 160–220px，正文 48–72px）
• 时长和时间线节拍
• 资源路径（如适用，包括徽标、图像）
• 上述硬性规则
• “不要提问。如果有歧义，请选择最明显、温馨可爱的解读。”

第 7 阶段 — 渲染 + 应用 DSL

7a. 串行渲染

每次 npx hyperframes render 都会启动 Chrome。并行运行会导致资源争用。串行即可——30 秒的合成渲染需要 30–50 秒：

for i in $(seq -w 01 07); do
  ( cd broll/slot_$i && npx hyperframes render --output renders/slot_$i.mp4 --quality standard )
done

质量：审阅时使用 standard，最终交付时使用 high，快速迭代时使用 draft。

7b. 规划 DSL 窗口（简短展示 + 阅读停留）

N=7 时的默认位置轮换：

• 插槽 1：bottomLeft 40%（下三分之一），3.6 秒
• 插槽 2、3、5、7：topRight 38–45%，5–5.5 秒
• 插槽 4、6：topLeft 40–42%，4.5–6 秒

所有插槽的摄像头位置都保持为 bottomRight 22% aspect=3:4，以确保连贯性。

每个插槽的显示窗口应为入场 + 阅读停留，而不是合成的完整时长。如果合成时长为 12 秒（入场 1.5 秒 + 长时间停留），5 秒的显示窗口会显示入场 + 3.5 秒停留，然后由 magicMove 接管。

7c. 应用 setSceneLayout

使用 scripts/apply_broll_dsl.py——它会读取计划 JSON，通过 ScreenKite CLI 逐项应用，然后清除所有旧尾段。

uv run scripts/apply_broll_dsl.py <plan.json>

计划 JSON 的架构和可直接复制的 DSL 代码片段，请参阅 references/dsl-cookbook.md。

7d. 清除尾段时的注意事项

setSceneLayout 会拆分现有片段，不会替换。如果你之前应用了一个 22 秒的 advanced 片段，现在又在相同起始位置重新应用一个 5 秒的片段，最终会得到一个新的 5 秒片段 + 一个仍显示 advanced 模式的 17 秒残留尾段。必须对每个尾段范围调用 setSceneLayout，并设置 mode: "pictureInPicture"，以清除尾段。

apply_broll_dsl.py 会自动处理：应用新的 B-roll 窗口后，它会读取布局状态，找到所有与预期计划不匹配的 advanced 片段，并将它们恢复为 PiP。

7e. 验证

'/Applications/ScreenKite.app/Contents/MacOS/ScreenKite' agent tool call \
  --name getProjectState --input-json '{"scope":"layout"}' --json

确认预期范围内恰好有 N 个 advanced 片段，其他所有位置均为 pictureInPicture。打开 ScreenKite 并拖动时间线，进行视觉验证。

迭代

如果视觉效果有误（内容、时间、位置）：

1. 编辑 broll/slot_XX/index.html（或通过针对性子 Agent 重新生成）
2. 重新渲染：cd broll/slot_XX && npx hyperframes render --output renders/slot_XX.mp4
3. 更新 plan.json 并重新运行 apply_broll_dsl.py（该脚本具备幂等性——尾段会再次清除）

ScreenKite DSL 通过绝对路径引用 MP4，因此，如果时间没有变化，只需替换文件即可完成迭代。

参考资料（按需加载）

• references/external-tools.md — 每项前置条件的安装说明/仓库 URL
• references/dsl-cookbook.md — 各位置的 DSL 代码片段 + plan.json 架构
• references/hyperframes-contract.md — 合成内容创作的所有硬性规则
• references/visual-ideas-menu.md — 按节拍分类的创意目录 + 密度组合
• references/subagent-brief-template.md — 供并行 Agent 使用的自包含任务说明模板

脚本（节省令牌）

优先使用 uv run（自动配置依赖，无需虚拟环境）。若不可用则使用 python3——只有 transcribe_mic.py 需要 requests；其余脚本仅使用标准库。

• scripts/transcribe_mic.py — ElevenLabs Scribe 封装器，带缓存，使用 ELEVEN_LABS_API_KEY
• scripts/pack_transcripts.py — 将原始 Scribe JSON 按短语打包
• scripts/scaffold_slots.py — 创建 N 个包含 hyperframes.json 存根的插槽目录
• scripts/apply_broll_dsl.py — 根据计划 JSON 应用 setSceneLayout + 清除尾段
• scripts/find_skbundle_mic.py — 在 .skbundle 中定位麦克风音频

反模式

• 不要跳过校对步骤。 Scribe 会误识别中文／繁体中文录音中的英文专有名词；生成视觉内容前请先核实，避免把「Claude」写成「Cloud」。
• 不要把内容放在 MP4 画面的角落。 MP4 本身就是画面。内容应填满画面。
• 不要让构图在自身画面内执行退出动画。 退出动画由 magicMove 处理。内部退出会导致重复淡出。
• 重新应用 setSceneLayout 前，不要忘记清除尾部片段。 否则僵尸 B-roll 会在原定时间窗口内一直播放。
• 不要并行渲染。 Chrome 会发生资源争用。串行渲染已经足够快。
• 不要重新转录已缓存的来源。 不可变输入 → 不可变输出。Scribe 会产生费用。
• 用户确认密度和素材包选择前，不要开始渲染。 返工成本很高。
• 如果已经安装 Hyperframes，就不要在这里使用 Remotion。 此技能只使用一种工具。