OpenCaptions 扩展

OpenCaptions 扩展 是做什么的？

将 CWI（带意图字幕）字幕集成到 Content Engine 后期制作管线。与静态、平面字幕不同，CWI 编码了言语的体验感受——音高驱动字体粗细、音量驱动字体大小、强调触发发光动画、说话人身份映射到 WCAG AA 颜色。最终产生的字幕能够传达内容是如何被说出的，而不仅仅是被说出了什么。

CWI 是 FCB Chicago 和 Chicago Hearing Society 在 2025 年获得奥斯卡奖的字幕标准。OpenCaptions 是其首个开源编程工具链。

管线接入点

阶段： 后期制作（阶段 3） 位置： 超分辨率与调色之后，最终导出之前。

后期制作链：
  1. 超分辨率（Real-ESRGAN / Topaz）   --> 更高分辨率
  2. 调色（品牌 LUT / ffmpeg）          --> 品牌色
  3. OpenCaptions（CWI）                --> 意图驱动字幕
  4. 最终导出（ffmpeg）                  --> 生产就绪文件

扩展接收一个已调色的视频文件，并生成：

1. 一个带有词级意图注释的 CWI 文档（.cwi.json）
2. 一个适用于需要标准字幕平台的 WebVTT 回退文件（.vtt）
3. 一个包含支柱得分的验证报告（JSON）
4. 一个通过 Remotion 或 ffmpeg 烧录的字幕视频（.mp4）

工作流程

已调色视频 + 场景概要
  |
  ├── [1] 转录（faster-whisper）          --> 词级时间戳
  ├── [2] 话者分离（pyannote-audio）       --> 说话人归属
  ├── [3] 提取意图                         --> 每段话语的音高、音量、情感、强调
  |       V1：parselmouth + FER（音频+视觉）
  |       V2：V-JEPA2 世界模型
  |       V3：TRIBE v2 神经预测
  ├── [4] 意图映射 --> CWI                --> 每个词的粗细、大小、强调、动画
  |       V1：规则映射器（音高-->粗细，音量-->大小）
  |       V2：学习映射器（基于修正数据训练）
  |       V3：神经映射器（大脑区域激活驱动样式）
  ├── [5] 验证（12 条规则）               --> 归因 + 同步 + 语调得分
  └── [6] 渲染                             --> Remotion 叠加 或 ffmpeg 烧录

步骤 1-2：转录 + 话者分离

管线调用 OpenCaptions CLI 或 MCP 服务器，运行 faster-whisper 进行词级时间戳，pyannote-audio 进行说话人检测。这些阶段生成一个 DiarizedTranscript，其中每个单词都标记了说话人。

步骤 3：意图提取

意图提取器分析音频和视频，以确定每段话语的感受寄存器：

• 声音信号：音高（Hz）、音量（dB）、语速（WPM）、暂停时机
• 情感信号：效价（-1 到 1）、唤醒度（0 到 1）、主导情绪
• 语义信号：讽刺概率、强调词、修辞手法

这些信号为每段话语形成一个 IntentFrame。偏离话语基线单词会获得 WordIntent 覆盖。

步骤 4：意图映射

映射器将意图信号转换为 CWI 视觉参数：

意图信号	CWI 属性	映射（V1 规则映射器）
音高（归一化 0-1）	weight（100-900）	线性插值：100 + pitch_norm * 800
音量（归一化 0-1）	size（0.7-1.5）	线性插值：0.8 + volume_norm * 0.55
语义强调 + 高音量	emphasis（布尔值）	词在 emphasis_words 中 或 音量 > p90
说话人身份	说话人 color	从 12 色 WCAG AA 调色板分配
低语（低音量）	weight < 300	覆盖：粗细限制在 100-250
喊叫（高音量）	size > 1.3 + emphasis	覆盖：大小 1.35-1.5，强调为 true

步骤 5：验证

@opencaptions/spec 验证器根据 12 条规则检查 CWI 文档，涵盖三大支柱：

归因（3 条规则）：

• ATT_001：每个字幕都有演员表中的说话人
• ATT_002：说话人拥有唯一颜色
• ATT_003：颜色满足 WCAG AA 对比度（相对于 #1a1a1a 为 4.5:1）

同步（5 条规则）：

• SYN_001：所有单词都有时间戳
• SYN_002：时间戳单调递增
• SYN_003：字幕事件不重叠
• SYN_004：动画持续时间为规范要求的 600ms
• FCC_001：说话期间无大于 3 秒的间隙
• FCC_002：每行最多 42 个字符（符合 FCC 要求）

语调（3 条规则）：

• INT_001：粗细在有效范围（100-900）内
• INT_002：大小在有效范围（0.7-1.5）内
• INT_003：超过 20% 的单词具有非默认粗细（字幕实际上有变化）

每个支柱得分范围为 0-100。只有当所有三个支柱得分 >= 80 时，CWI 文档才算通过。

步骤 6：渲染

两种渲染路径：

Remotion 路径（Content Engine 推荐）：CWI 单词成为 React 组件，位于 <CaptionOverlay> 组合中。每个单词在其时间戳出现，并带有 spring() 入场动画、说话人颜色、可变字体粗细和强调发光。完整映射请参阅 references/cwi-remotion-bridge.md。

ffmpeg 烧录（回退）：从 CWI 文档生成 ASS 字幕文件，并通过 ffmpeg -vf ass=captions.ass 将其烧录到视频中。这会丢失逐词动画，但保留说话人颜色和字体粗细变化。

CLI 使用

# 从视频生成 CWI 字幕
npx opencaptions generate video.mp4 --output captions.cwi.json

# 使用 TRIBE v2 神经后端生成
npx opencaptions generate video.mp4 --backend tribe --output captions.cwi.json

# 验证 CWI 文档
npx opencaptions validate captions.cwi.json

# 在终端中预览字幕（ANSI 彩色）
npx opencaptions preview captions.cwi.json

# 导出为 WebVTT
npx opencaptions export captions.cwi.json --format webvtt

# 导出为 After Effects ExtendScript
npx opencaptions export captions.cwi.json --format ae-json

# 导出为 Premiere Pro XML
npx opencaptions export captions.cwi.json --format premiere-xml

# 检查系统依赖
npx opencaptions doctor

# 安装 Python 依赖
npx opencaptions setup

MCP 服务器使用

OpenCaptions MCP 服务器暴露了四个用于代理集成的工具：

工具	描述
generate_captions	在视频文件上运行完整管线
validate_captions	根据 12 条规则验证 CWI 文档
preview_captions	在给定时间点的终端格式化预览
export_captions	导出为 WebVTT 格式

通过 Claude Code 使用时，请将 MCP 服务器添加到您的设置中：

{
  "mcpServers": {
    "opencaptions": {
      "command": "npx",
      "args": ["@opencaptions/mcp"]
    }
  }
}

然后在对话中调用：“为 video.mp4 生成 CWI 字幕”将触发 generate_captions。

compose-video.py 集成

Content Engine 的 compose-video.py 接受一个 --captions 标志：

python3 scripts/compose-video.py storyboard.md --brand arcan-studio --captions

当传入 --captions 时，在所有剪辑生成并拼接后，管线将：

1. 运行 npx opencaptions generate {final-video}.mp4 --output {output-dir}/captions.cwi.json
2. 验证 CWI 文档（如果得分 < 80 则发出警告，但不阻止）
3. 如果还传入了 --remotion，则将 CWI JSON 注入到 Remotion 组合中作为 <CaptionOverlay> 属性
4. 否则，与最终视频一起生成 WebVTT 作为侧车文件

如果未安装 OpenCaptions（npx opencaptions doctor 失败），管线会优雅降级：

• 回退到场景概要文本叠加（来自故事板 ## Shot 描述的静态文本）
• 记录警告：“OpenCaptions 不可用，使用场景概要文本叠加”
• 仍会生成一个 .vtt 文件，其时间源自剪辑边界

字幕样式

三种内置字幕样式预设，可通过配置选择：

1. 逐词模式（brainrot）

高留存风格：每个单词单独居中显示，最大程度的大小变化。用于针对多巴胺勾的社交媒体/TikTok/Reels 内容。

• 一次仅显示一个单词
• 大基础字号（1080p 下 64px）
• 极端粗细变化（100-900 全范围）
• 强调词放大至 1.5 倍并带有发光
• 背景：无（单词浮动在视频上）
• 字体：Roboto Flex 可变字体

2. 叙事模式（编辑型）

带逐词样式显示的完整句子。用于长篇内容、纪录片、博客视频嵌入。

• 完整字幕事件可见，单词内联样式
• 中等基础字号（1080p 下 48px）
• 适中的粗细变化（300-700）
• 强调词获得轻微尺寸提升（1.15x）
• 背景：半透明药丸形状（rgba(0,0,0,0.6)）
• 字体：Roboto Flex 可变字体

3. 极简模式（低位三栏）

简洁的下三分之一呈现。说话人名称 + 文本。视觉干扰最小。用于采访、大头讲话、会议录音。

• 说话人名称标签使用说话人颜色，字幕文本使用白色
• 小基础字号（1080p 下 36px）
• 仅强调时变化粗细（默认 400，强调 700）
• 无大小变化
• 背景：渐变条（帧底部 15%）
• 字体：系统无衬线字体

数据契约

读取（不可变）

• 来自前序后期制作步骤的已调色视频资产
• knowledge/compiled/brands/{brand_slug}.md -- 用于字幕颜色调色板和排版偏好
• 场景概要（运行时参数）-- 用于预期情感基调的上下文

写入（仅命名空间内）

• extensions/opencaptions/output/{asset_id}.cwi.json -- CWI 文档
• extensions/opencaptions/output/{asset_id}.vtt -- WebVTT 回退
• extensions/opencaptions/output/{asset_id}-report.json -- 验证报告
• extensions/opencaptions/output/{asset_id}-captioned.mp4 -- 渲染的视频（仅 Remotion 路径）

配置

opencaptions:
  # 字幕样式预设
  style: "narrative"              # word-by-word | narrative | minimal

  # 视觉参数
  font_family: "Roboto Flex"      # 用于粗细轴的可变字体
  base_font_size: 48              # 1080p 下的像素值
  position: "bottom"              # top | center | bottom
  max_chars_per_line: 42          # FCC 合规
  background: "pill"              # pill | shadow | gradient | none
  background_opacity: 0.6         # 0.0 - 1.0

  # 管线后端
  backend: "av"                   # av (V1) | jepa (V2) | tribe (V3)
  language: "en"                  # 转录的 ISO 639-1 提示

  # 说话人覆盖（可选，默认自动检测）
  speakers:
    - name: "解说员"
      color: "#6B8AFF"
    - name: "嘉宾"
      color: "#FF6B6B"

  # 渲染
  render_mode: "remotion"         # remotion | ffmpeg | sidecar-only
  output_format: "mp4"            # mp4 | webm
  fps: 30                         # 匹配源视频

  # 验证
  min_score: 80                   # 继续管线的最低总分
  fail_on_low_score: false        # 若为 true，低分时阻断管线

  # TRIBE v2 神经映射（仅 V3 后端）
  neural_mapping: false           # 启用预测的神经响应样式

优雅降级

扩展从不阻塞 Content Engine 管线。降级阶梯如下：

条件	行为
已安装 OpenCaptions CLI + 所有 Python 依赖	完整 CWI 管线（转录、话者分离、意图、映射）
已安装 OpenCaptions CLI，无 Python 依赖	使用占位字幕 + 验证的模拟后端
未安装 OpenCaptions CLI	在剪辑边界处使用场景概要文本叠加作为静态字幕
视频无音轨	跳过字幕生成，记录信息消息
验证得分 < 80	发出警告但继续（除非 fail_on_low_score: true）
Remotion 不可用	回退到 ffmpeg ASS 烧录
ffmpeg 不可用	仅输出 CWI JSON + WebVTT 侧车文件（无渲染视频）

相关

• OpenCaptions 项目：~/broomva/apps/opencaptions/
• CWI-Remotion 桥接：references/cwi-remotion-bridge.md
• 集成指南：references/integration-guide.md
• Content Engine SKILL.md：../../SKILL.md
• 扩展框架：../README.md