quibex/reel-subs

reel-subs — 为 Reels 添加字幕与动画

你可以在已完成的说话人头视频（从 CapCut / Premiere / 手机导出）基础上，逐句添加带时间轴的字幕和简洁的动态图形。一切均在用户的本地机器上运行。

工作原理： 语音 → 带时间戳的单词（sherpa-onnx，离线）→ 你编写 edit.json（字幕 + 图形元素）→ Remotion 仅渲染一个透明图形层 → ffmpeg 将其叠加在未改动的原始视频上，保留原始视频的色彩标签。切勿通过 Remotion 渲染整个视频：那样会以不同的色彩矩阵重新编码，导致肤色偏移。

下面的 SKILL_DIR 指包含本文件的文件夹。ENGINE = ~/.reel-subs/engine（Windows 上为 %USERPROFILE%\.reel-subs\engine；如果设置了 $REELS_HOME/engine 环境变量，则为该路径）。所有脚本都是纯 Node.js 编写——使用 node 运行，在 macOS、Windows 和 Linux 上方法相同。

用用户的语言与用户交流。 用用户书写语言（通常为俄语）回复，即使本文件是英文：进度提示、问题、错误信息以及最终总结都用用户语言。命令、路径和 JSON 键保持不变。

首先阅读用户的偏好设置。 如果 ~/.reel-subs/preferences.md 存在（或 $REELS_HOME/preferences.md），在步骤 1 之前阅读并遵循它：它记录了该用户先前会话中的偏好，并覆盖本文件中的默认设置。参见下面的“学习用户偏好”。

0. 设置（首次使用，或当 doctor 提示 NOT READY 时）

node SKILL_DIR/scripts/setup.mjs            # 俄语语音模型（默认）
node SKILL_DIR/scripts/setup.mjs --lang multi   # 英语 + 24 种欧洲语言

仅需 Node.js 18+。如果未安装 node，请告知用户从 nodejs.org 安装 LTS 版本（macOS：brew install node 也可行；Windows：winget install OpenJS.NodeJS.LTS），然后停止。Setup 会将引擎复制到 ENGINE，运行 npm install（安装 Remotion、ffmpeg/ffprobe 二进制文件、sherpa-onnx），下载语音模型（~170 MB 俄语 / ~490 MB 多语言）和 headless Chrome。该过程是幂等的。首次执行耗时 2–5 分钟——用一句话告知用户。完成后输出 READY。

如果显示 ✗ headless browser：Remotion 的 Chrome 下载在当前网络下被阻止，且未找到已安装的 Chrome/Edge → 请用户安装 Google Chrome，然后重新运行 setup。

1. 准备

node ENGINE/scripts/prepare.mjs "<video>" [--lang ru|multi] [--audio clean_voice.wav]

• --lang：ru（GigaAM，最适合俄语）或 multi（英语、德语、西班牙语、法语、乌克兰语……）。根据视频中的语言选择；仅在不明确时询问。缺失的模型会自动下载。
• --audio：如果用户有清理过的语音轨道（Auphonic、Adobe Podcast…），使用它——识别效果更好，且渲染时会将其放入最终视频。
• 在视频旁创建 <video 名称>.reels/ 文件夹：包含 transcript.txt、words.json、edit.json（草稿）。
• 遇到 HDR 视频时会停止并给出解释（在 HDR 上叠加图形会导致色彩偏移）——将该信息转达给用户。

2. 理解视频

1. 阅读 transcript.txt（带时间码的短语）并浏览 words.json 以获取精确的单词时间。
2. 查看帧：node ENGINE/scripts/look.mjs "<video>" --every 1 → 打开缩略图。注意人脸位置（顶部 / 中部）、手部动作、屏幕/产品展示位置、剪辑点。对于长视频，可分段生成缩略图（--from 0 --to 30）。

3. 修正字幕（edit.json → captions）

草稿页面已按短语拆分（约 2 秒，≤ 32 个字符）。你的工作：

• 修正识别错误：产品名称、英文术语、数字（如“четыре бакса” → $4）、品牌拼写。识别结果不含标点——仅添加有助于阅读的标点，大多数情况下不添加。
• 保留说话人自己的用词和语言，除非被要求，否则不要翻译。
• 合并/拆分页面，使每个页面成为一个自然短语。保持 startMs/endMs 与 words.json 对齐。
• 字幕文本中的标记：*word* → 强调色（极少使用，用于关键词），~word~ → 红色（说话人开玩笑时口误的标记）。
• 在你最后的回复中列出不确定的单词，而不是默默猜测。

4. 规划图形（edit.json → items）

完整字段参考及示例见 SKILL_DIR/reference/edit-schema.md——在编写 items 之前请先阅读。

• hook — 前 2–4 秒，直到第一个剪辑点或笑点：用一句话概括视频精华，使用说话人的语言。当 hook 显示时，字幕自动隐藏。
• card — 关键点：包含 label（小号大写字母）+ title 和/或 chips，这些内容会在它们说明的单词出现时显示（at），on: true 用于结果芯片，strikeAt 用于划掉内容。
• big — 说话人强调的数字或单词（“$1”、“5000”）。
• terminal — 仅在讨论代码、智能体、命令时使用。
• punch — 笑话 / 自嘲：a 被划掉，b 大号显示。字幕自动隐藏。
• pop — 小型 HUD 小部件，当说话人做手势时（“这些动画会…”）迅速出现在手旁边。将它们放置在 单词前约 0.3 秒处：识别的时间戳有延迟。
• badge — 左上角持久标签（如剧集编号），仅当用户需要时使用。

规则：

• 切勿遮挡面部。 卡片默认位于上半部分（top: 260）。如果面部位于画面上半部分，使用 top: 1110（低位）。也不要遮挡说话人正在指向的内容。
• 所有内容保持在安全区域内（卡片宽 840 px，居中）——不要将元素移到边缘。
• 密度：平均每 5–10 秒一个图形，与单词时间对齐。不要出现重复说话内容的文字框，不要解释显而易见的信息，不要使用弹跳/幼稚的动画。
• 首次提及某个产品/项目：卡片应用几个字说明其是什么——观众可能不了解。
• 时间以源视频的秒为单位。图形可以覆盖字幕；hook 和 punch 会自动隐藏字幕。
• 不要编造事实：芯片和卡片内容应严格遵循说话人的表述。

5. 预览 — 在完整渲染之前务必查看

node ENGINE/scripts/preview.mjs "<work>/edit.json"            # 每个 item 内取一帧
node ENGINE/scripts/preview.mjs "<work>/edit.json" --at 1.2,7,15

打开 previews/sheet.jpg（以及需要的单个 at_<t>.jpg）。检查：面部清晰、文字适配、无元素触及边缘、字幕可读。修正 edit.json 后再次预览。每次运行约 10–30 秒。

6. 渲染

node ENGINE/scripts/render.mjs "<work>/edit.json" [--out file.mp4]

每分钟视频渲染约 1–4 分钟。输出默认为源视频旁的 <video 名称>_final.mp4。会打印输出帧数与源帧数的对比——如果显示 MISMATCH，请告知用户。 然后向用户提供：输出路径、2–3 行你添加内容的摘要、存疑的单词。

修订

编辑 edit.json → 预览修改的时刻 → 再次渲染。用户批准字幕之后，切勿重新运行 prepare.mjs --force（那样会重置字幕）。在重大修改前复制 edit.json。

学习用户偏好

该技能应随着每次使用而更适应用户。用户的笔记保存在 ~/.reel-subs/preferences.md（如果设置了 $REELS_HOME 则为 $REELS_HOME/preferences.md）——位于技能文件夹和 ENGINE 之外，因此更新技能或重新运行 setup 时绝不会被清除。

何时提供保存：

• 用户两次纠正同一类问题（字体、颜色、字幕大小或位置、图形数量、钩子措辞、哪些单词需要强调…）。
• 用户说类似“запомни”、“в следующий раз делай так”、“мне так больше нравится”的话。
• 在包含修订的会话结束时：用 2–4 行简要列出修正，并询问一次是否保存以供下次使用。

如何执行：

• 总是先询问，展示你将要写入的确切内容，仅在用户同意后写入。切勿自行保存。
• 写入规则，而非历史记录：例如「字幕字体更大：captionSize 60」、「钩子不带 emoji」、「每 10 秒最多一个卡片」。在简短的标题（样式、字幕、图形、措辞）下对它们进行分组。更新或删除旧规则，而非添加矛盾规则。
• edit.json → style 支持的样式值应作为精确值写入，以便你可以将其复制到每个新的 edit.json 中。
• 如果某个需求需要修改代码（新字体、新动画、不同的卡片外观），在 ENGINE/src/ 中进行修改，并在 preferences.md 的 Engine changes 下记录：哪个文件、修改了什么、原因。Setup 会重新复制引擎并覆盖已编辑的文件（新文件会保留），因此在每次 setup 运行后检查此列表并重新应用缺失的更改。
• 用户也可以手动编辑 preferences.md，或直接告诉你需要修改什么。

自定义

• 颜色 / 大小：edit.json → style（accent、captionSize、captionTop、font）。
• 新的图形类型：在 ENGINE/src/components/ 中添加组件，在 src/types.ts 中添加类型，在 src/Overlay.tsx 中添加 case——下次预览时构建会自动重建。保持图层透明（Remotion 内部无背景、无视频）。
• 在 ENGINE 内运行 npm run studio 可打开 Remotion Studio 进行实时调整。

故障排除

• doctor：node ENGINE/scripts/doctor.mjs — 显示每个依赖项的 ✓/✗。
• 可变帧率警告 → 请用户以恒定 30 或 60 fps 导出。
• 非 9:16 比例 → 图形按竖屏视频布局；会缩放适配，但请告知用户。
• Windows：使用相同的命令；带空格的路径请用引号括起来。PowerShell 和 cmd 均可。
• 没有任何数据上传：模型和 Chrome 仅下载一次，之后全部离线运行。