给视频添加字幕
用户提供一段说话视频。他们从字幕样式目录中选择，该目录会在他们自己的视频上预览，然后您交付带字幕的 MP4。一切都在本地通过 HyperFrames 运行。无需 After Effects。
工具包： 工作室仓库内的 .claude/skills/caption-video/kit/。项目在 videos/captions/<name>/ 中创建，完成的视频输出到 out/captions/<name>.mp4（均相对于工作室根目录）。
从工作室根目录，设置 K="$PWD/.claude/skills/caption-video/kit" 并运行 python3 "$K/caption.py" …
（路径加引号；文件夹可能包含空格）。如果系统 Python 缺少 numpy/scipy，请使用工作室的 venv Python（.venv/bin/python）—— setup/setup.sh 会创建它。
流程
1. 获取视频
如果没有给出视频路径，请询问一个。检查它是否存在并且包含说话的人。运行：
python3 "$K/caption.py" new "<video path>" <short-name>
这会复制视频，将其重新编码为 H.264，并使用 WhisperX 逐词转录。第一次运行可能需要一分钟左右。长视频大约需要实时时间除以 4。
2. 显示转录文本
以可读的块形式打印命令输出中的转录文本。指出任何可能的错误，特别是品牌名称和术语（产品名称、“HyperFrames”、首字母缩略词），并请用户确认或更正。更正内容在构建时以 --fix "wrong=right,…" 形式传入。如果转录文本看起来像乱码，或者音频中没有语音，请停止并说明。不要为编造的单词添加字幕。
3. 在他们的视频上展示每种样式
运行 python3 "$K/caption.py" styles 获取列表，运行 python3 "$K/caption.py" preview <name> 获取视觉面板。面板位于 videos/captions/<name>/previews/styles.png。您自己查看它，然后使用 SendUserFile（显示 render）发送。在旁边，给出带有每种样式“最适合”说明的编号列表：
- Lime Hook：模板外观（Anton 大写字母，石灰绿口语词）
- Karaoke Pop：大的两个词爆发，黄色口语词
- One Word：一次一个巨大的词
- Clean Box：白色卡片上的深色文字，口语词上的荧光笔
- Editorial：平静的句子大小写，关键词用斜体衬线
- Subtitle：小的完整句子字幕
- Neon：口语词上的青色辉光
根据内容在一行中推荐一种：炒作或社交 → 1 或 2，解说或广告 → 4，创始人故事或高级 → 5，访谈或播客 → 6，科技或 AI → 7。然后请他们选择一个数字。如果 caption.py 中的目录已更改，请列出 styles 打印的内容，而不是这个副本。
4. 钩子（可选）
从演讲者实际说的内容中建议 3 个钩子。以其最令人惊讶的数字、结果或矛盾开头，使用 4–8 个词，并将结果保持在一个大词上。以钩子语法格式化每一个，然后使用 AskUserQuestion：三个钩子选项加上“无钩子”（用户也可以自己输入）。
钩子语法每行使用一个 |，每个以其样式开头：
s:斜体衬线介绍（“How”、“Why”）c:白色紧凑大写设置b:大的带环结果词或数字（1–2 个词）l:石灰绿大写转折r:小的斜体标签
示例：s:How|c:I reached|b:300k+|l:without ads|r:views。钩子必须与视频前 10 秒内传递的内容匹配。
4b. 润色（提供它；当用户要求评分、清理音频、修剪或音乐时运行它）
python3 "$K/polish.py" <name> [--grade clean|cinematic|none] [--music calm|none] [--music-level 1.0] [--denoise 100]
- 修剪： 切掉第一个词之前和最后一个词之后的空白（保留 0.3 秒和 0.9 秒），并相应地移动转录文本。
- 评分：
clean（默认）提供温暖健康的肤色、柔和的对比度和柔和的渐晕。cinematic更深更冷。在选择之前，将每种颜色的一帧与原始帧进行比较并查看。 - 语音： DeepFilterNet3 降噪（
~/.venvs/dfn，由 setup.sh 创建；切勿全局安装，它需要 numpy<2），然后是高通、存在感增强、去齿音和轻微压缩。 - 音乐： 合成的平静钢琴和垫底。在级别 1 时，它在停顿期间大约低于语音 20 dB，在说话期间大约低于语音 25 dB。使用
--music-level 0.6获得更安静的效果，或使用1.5获得更突出的效果。 - 原始文件保留为
source_orig.mp4/transcript_orig.json，因此可以重新运行润色并指定任何设置。润色后，再次运行build和render。 - 提及开头的任何结巴或假开始（“at the present, at the moment…”）。剪切它们会产生一个小的跳跃剪辑，因此在执行之前请询问。
5. 构建、检查、渲染
python3 "$K/caption.py" build <name> --style <key> [--hook "…"] [--hot "word,word"] [--fix "a=b"]
cd "videos/captions/<name>" && npx --yes [email protected] check
python3 "$K/caption.py" render <name>
--hot列出保持强调色的词。选择 2–5 个结果词；数字自动为强调色。check在钩子淡出时刻的对比度警告是预期的。在渲染之前修复任何实际错误。- 在渲染钩子之前，对其进行快照（
npx --yes [email protected] snapshot . --at 1.6 --no-end --describe false）并检查它是否没有遮挡脸部。当脸部在帧中较高时（坐着或中景），使用--hook-y 0.43将钩子移到胸部；阴影会自动跟随。 - 在发送之前，从
out/captions/<name>.mp4中提取 3–4 帧并查看它们。字幕不得遮盖嘴巴或眼睛。如果遮住了，使用--cap-y重新构建（数字越大 = 在屏幕上越低）。 - 横向拍摄的素材（相机侧放，无旋转元数据）在联系人表中显示为人物侧躺。首先将其旋转（
ffmpeg -vf transpose=2= 逆时针 90°，或transpose=1= 顺时针；检查一帧）到videos/_caption-inputs/，然后在该文件上运行new。 - 使用
SendUserFile发送 MP4，并将其路径作为链接给出。
6. 修订
设置持久保存在 videos/captions/<name>/caption.json 中，因此修订只需 build <name> --<option> … 后跟 render <name>。常见要求：
- 不同样式：
--style。 - 更大或更小：
--size 1.2。 - 更高或更低：
--cap-y 0.7。 - 每个字幕更少的词：
--words 2。 - 不同的颜色：
--accent "#FF4D3D"。 - 更改钩子：
--hook；--hook ""删除它。 - 钩子长度：
--hook-dur 3.5。
他们也可以自己在 HyperFrames Studio 中打开它，使用 cd videos/captions/<name> && npm run dev。
设置事实（如果出现问题）
- 转录调用
~/.claude/skills/embedded-captions/scripts/transcribe.cjs并设置HYPERFRAMES_ROOT=~/.hyperframes-root，这是一个 HyperFrames CLI 0.8.147 安装，带有packages/cli/dist/cli.js符号链接。如果任一丢失，请重新安装：npx hyperframes skills update embedded-captions，然后重建~/.hyperframes-root（npm install[email protected]并符号链接node_modules/hyperframes/dist/cli.js到packages/cli/dist/cli.js）。 - 字体位于
kit/fonts/（均为 SIL OFL）并被复制到每个项目中。 setup/doctor.sh检查下面的每个部分；setup/setup.sh修复它们。- 字幕可以放在人物后方，通过
/embedded-captions工作流程实现，但它慢得多（大约每 10 秒 4 分钟）并且需要设置HYPERFRAMES_ROOT。仅在有人问起时提供。