Remotion 逐词高亮字幕

概述

本技能将本地视频转换为带字幕的视频，采用可复用的“精细版”方案：Whisper 生成带词级时间戳的转录结果，并由 Remotion 渲染当前词高亮效果。除非用户明确要求简单静态字幕（如纯 SRT 烧录），否则请优先使用本技能。

详细使用指南、README 及效果预览地址：https://github.com/0x00000003/remotion-word-highlight-subtitles

触发语句

以下请求适用本技能：

• “给这个视频添加字幕：/path/to/video.mp4”
• “给这个视频加逐词高亮字幕”
• “按之前 Remotion 那个字幕方案处理这个视频”
• “重新转写 word timestamps，然后加当前词高亮字幕”

若用户仅提供一个视频路径，则将输出文件置于源视频同一目录下。

默认配置

• 输入源：本地 .mp4、.mov、.m4v 或其他具备可用音频轨道的音视频文件。
• 输出路径：_remotion逐词高亮字幕.mp4，与源文件同目录；除非用户另行指定目标路径。
• 语音转录：使用 Whisper 生成带词级时间戳的中文转录，默认参数为：--language zh --word_timestamps True --output_format json。
• 转录质检（QA）：渲染前必须执行。需基于用户提示、文件夹/文件名、可见上下文及主题构建小型术语表，并修正明显 ASR 错误，包括产品/模型/人名/地名、英文术语、数字及同音异义词。
• 字幕数据：基于 Whisper 输出的词级时间戳构建 Remotion 字幕块，每个 token 包含精确的 startMs 和 endMs。Whisper 返回的长段落须依据标点、时间间隔、持续时长或字符长度进行合理切分后方可渲染。
• 字幕位置：所有字幕统一置于适合截图的下半区域，略高于底部 UI 区域。起始底部留白约为 height * 0.28，仅当原始构图明显需要时才微调。
• 视觉样式：使用加粗的中文 UI 字体；基础文字为白色；当前词高亮为黄色；关键词可选性稀疏着色；添加黑色阴影/描边以确保可读性。
• 字幕尺寸：将字体大小视为硬性视觉门限，而非松散风格建议。对于横屏 1080p 视频，目标字号为 height * 0.056（约 60px），且不得低于 56px；对于竖屏 720x1280，目标字号为 40–46px。其余分辨率按高度线性缩放，但须在静帧 QA 中保持一致的视觉感知大小。
• 标点显示：默认字幕为干净的中文展示文本。渲染前须从字幕文本及 token 文本中移除所有可见句末标点，包括 。 ， 、 ？ ！ ： ； , . ? ! : ;。仅当用户明确要求逐字保留标点时，才将其用于切分或计时目的。
• 验证环节：确认输出文件存在、音频完整保留、时长与源视频高度一致，并在最终接受样式前对关键静帧进行人工目检。

工作流程

1. 使用 ffprobe 检查源文件的宽、高、帧率、时长及音频是否存在。
2. 转录前构建小型领域术语表。涵盖可能的产品名、模型名、人名、地名、中英混用词、数字，以及由文件夹名或文件名暗示的相关术语。
3. 运行 Whisper 词级时间戳转录。优先选用已缓存/本地部署且可在当前机器运行的模型；turbo 是推荐默认选项（如有）。当术语表中含高风险名称或英文术语时，应使用 --initial_prompt 参数引导识别。
4. 渲染前必须执行强制性转录 QA。逐段阅读转录结果，结合视频主题与上下文比对，建立明显 ASR 错误的修正映射。在已知错误未修复前，禁止进入渲染阶段。
5. 使用 scripts/whisper_json_to_captions.py 将 Whisper JSON 转换为 public/captions.json，通过 --replace 或 --replace-phrase 应用修正。同步完成转录修正、术语合并、展示标点剥离；若 Whisper 返回长段落，需启用辅助脚本的字幕切分功能。
6. 在视频所在目录中新建或复用小型 Remotion 工程。将视频复制至 public/input.mp4，或编码为 H.264 兼容格式并保存为 public/input-h264.mp4。
7. 将 Remotion 合成设置为与源视频完全一致的宽度、高度、帧率及帧数时长。
8. 全量渲染前，至少从 Remotion 合成中导出并检查两张静帧：一张含长句/双行字幕，另一张含高密度关键词/当前词高亮字幕。在最终渲染前，须修复以下问题：文字模糊、描边过重、背景黑块过大、断行生硬、字号过小、标点残留、定位不准、错别字或错字。
9. 使用 Remotion 渲染至源文件同目录下的输出路径。
10. 使用 ffprobe 验证最终输出；提取并检查渲染视频中的静帧，确认最终编码文件完整保留已批准的字幕样式。

Whisper 命令示例

按需调整模型与路径，命令结构如下：

whisper "/absolute/path/video.mp4" --model turbo --language zh --word_timestamps True --output_format json --output_dir "/absolute/path"

涉及专有名词或中英混用主题时，建议添加简短提示词，而非依赖 Whisper 自行推断：

whisper "/absolute/path/video.mp4" 
  --model turbo 
  --language zh 
  --word_timestamps True 
  --output_format json 
  --initial_prompt "本视频可能出现这些词：Cursor、Kimi 2.5、马斯克、AI大模型、转推、套壳。" 
  --output_dir "/absolute/path"

若 Whisper 无法直接解析视频容器格式，请先提取音频：

ffmpeg -y -i "/absolute/path/video.mp4" -vn -ac 1 -ar 16000 "/absolute/path/video_audio.wav"

随后对 WAV 文件运行 Whisper，并确保输出命名清晰可辨。

强制性转录质检（QA）

Whisper 完成后，在构建字幕前务必打印或通读分段转录文本。此步骤为必需关卡，非可选项。

重点核查以下内容：

• 产品、模型、公司、人名、地名
• 中英混用术语，例如 Cursor、Kimi 2.5、ChatGPT、Claude、OpenAI
• 数字、日期、模型版本、缩略词
• 语境中看似合理实则错误的中文同音词，例如“却”与“圈”、“死腿”与“转推”
• 若 Whisper JSON 中包含置信度概率，则需关注低置信度词汇

创建简明修正映射并在渲染前应用。单 token 修正使用 --replace，跨相邻 Whisper token 的词语组合修正使用 --replace-phrase。

示例：

python3 scripts/whisper_json_to_captions.py 
  "/absolute/path/transcript.json" 
  "/absolute/path/remotion-project/public/captions.json" 
  --replace-phrase "科舍=Cursor" 
  --replace-phrase "KMI 2.5=Kimi 2.5" 
  --replace-phrase "Kimi 2.5=Kimi 2.5" 
  --replace-phrase "AI却=AI圈" 
  --replace-phrase "死腿=转推" 
  --merge-term "Cursor" 
  --merge-term "Kimi 2.5" 
  --keyword "AI" 
  --keyword "Kimi 2.5"

若某项修正存疑，建议优先尝试使用更精准的 --initial_prompt 重新运行 Whisper，或在决策前检查对应音视频片段。最终响应中需汇报修正映射。

字幕 JSON 格式

Remotion 应加载 public/captions.json，其结构如下：

[
  {
    "text": "我们用手机随便拍张照片",
    "startMs": 0,
    "endMs": 1600,
    "tokens": [
      { "text": "我们", "startMs": 0, "endMs": 300, "keyword": false },
      { "text": "手机", "startMs": 440, "endMs": 700, "keyword": true }
    ]
  }
]

推荐使用辅助脚本：

python3 scripts/whisper_json_to_captions.py 
  "/absolute/path/transcript.json" 
  "/absolute/path/remotion-project/public/captions.json" 
  --keyword "提示词" 
  --keyword "Codex" 
  --replace-phrase "错识别词=正确词" 
  --max-caption-chars 28 
  --max-caption-duration-ms 4200 
  --split-gap-ms 260 
  --min-punctuation-caption-ms 900

请在执行该转换命令前完成转录 QA。若修正导致相邻 tokens 合并为一个显示词，也需通过 --merge-term 或相同文本的 --replace-phrase 显式传入该最终词，以确保高亮呈现为完整单词而非断裂字符。

默认情况下，scripts/whisper_json_to_captions.py 会在最终字幕文本与 token 文本中剥离可见的展示标点，但仍保留标点作为切分信号。除非用户明确要求逐字保留标点，否则请勿传递 --keep-display-punctuation。若手动构建 JSON，请移除纯标点 token 并在渲染前裁剪末尾标点。

该辅助脚本会依据可见长度、持续时长、标点及词间时间间隔对 Whisper 长段落进行切分。短片字幕请保持此行为开启；否则单个 Whisper 段落可能被渲染为不可读的多行字幕。

Remotion 字幕图层要求

字幕图层应满足以下条件：

• 使用 OffthreadVideo 加载源视频。
• 通过 delayRender、continueRender 与 staticFile 加载 captions.json。
• 通过 currentMs >= startMs && currentMs < endMs 判定当前活跃字幕块。
• 当 currentMs 处于某 token 的时间区间内时，高亮该 token。
• 关键词着色仅为次要强调；当前正在朗读的词才是主要视觉效果。
• 保持 letterSpacing: 0。
• 渲染干净的展示型字幕，不包含句末标点。除非用户明确要求逐字保留标点，否则不得显示逗号、句号、问号、感叹号、冒号、分号或顿号等标点 token。
• 将字幕尺寸视为硬性门限。对于 1080p 横屏视频，渲染字号应约为 60px，且不得低于 56px；若静帧显示为细小 UI 注释文字，则需放大并重渲染。
• 所有字幕保持标准位置；除非用户明确要求，否则不得添加特殊截图句式定位。
• 默认禁用 WebkitTextStroke 作为中文大字幕描边。该属性在小分辨率下极易吞噬白色填充。推荐使用多方向 textShadow；若必须使用 WebkitTextStroke，则描边宽度不得超过 1.5px，且需验证静帧效果。
• 默认禁用覆盖整个字幕的大型半透明圆角黑色矩形背景。若画面确实需要背景衬底，请使用极细微的逐行衬底（不透明度 <= 0.16，内边距紧凑），并验证其不呈现为深色横幅。

凡出现以下任一问题的静帧，均须拒绝并修订：文字模糊/灰暗、黑色光晕过厚、大块黑色背景、文字截断、断行突兀、句末标点可见、字号相对于画面过小、或字幕遮挡讲话者口部/下巴（适用于人像视频）。

以下样式常量为基准参考：

const captionBottom = Math.round(height * 0.28);
const isLandscape = width >= height;
const baseCaptionFontSize = Math.round(height * (isLandscape ? 0.056 : 0.032));
const minCaptionFontSize = isLandscape && height >= 1000 ? 56 : Math.round(height * 0.032);
const captionFontSize = Math.max(baseCaptionFontSize, minCaptionFontSize);
const captionMaxWidth = Math.round(width * 0.88);
const activeColor = "#FFE45C";
const keywordColor = "#D6FFF8";
const outlinePx = Math.min(3, Math.max(1.5, captionFontSize * 0.055));

推荐使用干净的阴影描边，而非厚重描边：

const textShadow = [
  `${outlinePx}px 0 0 rgba(0, 0, 0, 0.96)`,
  `-${outlinePx}px 0 0 rgba(0, 0, 0, 0.96)`,
  `0 ${outlinePx}px 0 rgba(0, 0, 0, 0.96)`,
  `0 -${outlinePx}px 0 rgba(0, 0, 0, 0.96)`,
  `0 ${outlinePx * 1.4}px ${outlinePx * 1.4}px rgba(0, 0, 0, 0.72)`,
].join(", ");

对于 1920x1080 横屏视频，此配置生成约 fontSize: 60，且不得低于 56。对于 720x1280 竖屏视频，对应值约为 paddingBottom: 358、fontSize: 41、maxWidth: 634 及 2px 描边。对于启发本技能设计的原始 2160x2974 源文件，对应底部留白约为 830。

关键词处理

若用户未指定关键词，应从转录文本中推断少量关键词：

• 产品/工具名：Codex、Remotion、Whisper
• 内容对象：提示词、照片、手机、封面
• 承载视频核心钩子的地名或名词
• 对承诺达成至关重要的数字或结果

关键词高亮须保持稀疏。过多着色词会削弱当前黄色高亮词的视觉主导性。

输出命名规范

优先采用：

_remotion逐词高亮字幕.mp4

同一源文件多次迭代时，依次追加 _v2、_v3 等后缀。严禁覆盖用户原始源文件。

最终响应

向用户明确告知输出路径，说明其采用可复用的 Remotion + Whisper 词级时间戳流程，并附上转录修正映射；若无需修正，则注明“无修正项”。若任一验证步骤未能执行，需直述说明。