ra-audio-to-subtitles

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

真实时间戳字幕

Use the final audio stream as the only timing source. Never estimate final subtitle timing from character count, scene duration, TTS segment duration, or fixed delays.

将最终音频流作为唯一的计时来源。最终字幕时间绝不能根据字符数、场景时长、TTS 分段时长或固定延迟进行估算。

Required workflow

必需工作流

Finish and concatenate narration first. If the user recorded or merged a video, use that final merged media instead.
Run
```
scripts/generate_subtitles.py
```
against the final media and the exact narration script.
Inspect phrase segmentation. Keep English product/model tokens intact, merge isolated one-word fragments, and place connectors such as
```
比如说
```
,
```
但是
```
, and
```
只是
```
with the phrase they introduce.
Render captions from
```
captions.json
```
; export
```
captions.srt
```
for Bilibili, YouTube, editing software, and archive.
Require
```
caption-qc.json
```
to report
```
status: pass
```
before final render or delivery. The gate includes alignment, overlap, fragments, connector splits, caption duration, and reading speed.
If ASR fails or alignment coverage is below the gate, stop. A character- count estimate may be used only for an explicitly labeled scratch preview.

首先完成并拼接旁白。如果用户录制或合并了视频，则改用该最终合并媒体。
针对最终媒体和准确的旁白脚本，运行
```
scripts/generate_subtitles.py
```
。
检查短语分段。完整保留英文产品或型号词元，合并孤立的单词片段，并将
```
比如说
```
、
```
但是
```
和
```
只是
```
等连接词与它们引入的短语放在同一条字幕中。
从
```
captions.json
```
渲染字幕；导出
```
captions.srt
```
，用于 Bilibili、YouTube、编辑软件和归档。
在最终渲染或交付之前，要求
```
caption-qc.json
```
报告
```
status: pass
```
。该门禁包括对齐、重叠、片段、连接词拆分、字幕时长和阅读速度检查。
如果 ASR 失败或对齐覆盖率低于门禁要求，则停止。只有在明确标记为草稿预览时，才可以使用基于字符数的估算。

Commands

命令

Project with

narration_segments.json

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py \
  <project>/media/final-voiceover.mp3 \
  --script <project>/narration_segments.json \
  --out-dir <project>/media/captions

Recorded or merged video with a Markdown handoff containing

- 口播：

lines:

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py \
  <project>/merged.mp4 \
  --script <project>/handoff.md \
  --out-dir <project>/media/captions

Health check:

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py --doctor

Offline regression test with an existing Volcengine response:

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py \
  <audio> --script <script> --asr-result <volcengine-result.json> \
  --out-dir <output>

使用

narration_segments.json

的项目：

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py \
  <project>/media/final-voiceover.mp3 \
  --script <project>/narration_segments.json \
  --out-dir <project>/media/captions

录制或合并的视频，其 Markdown 交接文件包含

- 口播：

行：

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py \
  <project>/merged.mp4 \
  --script <project>/handoff.md \
  --out-dir <project>/media/captions

健康检查：

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py --doctor

使用现有 Volcengine 响应进行离线回归测试：

bash

python3 .claude/skills/ra-audio-to-subtitles/scripts/generate_subtitles.py \
  <audio> --script <script> --asr-result <volcengine-result.json> \
  --out-dir <output>

Output contract

输出契约

The output directory must contain:

```
asr-result.json
```
: raw Volcengine response
```
captions_words.json
```
: word/character timestamps and detected gaps
```
captions.json
```
: phrase captions consumed by HyperFrames or Remotion
```
captions.srt
```
and
```
captions.vtt
```
: portable subtitle files
```
caption-qc.json
```
: alignment coverage and timing validation

Read references/artifact-contract.md before integrating another renderer or delivery checker.

输出目录必须包含：

```
asr-result.json
```
：原始 Volcengine 响应
```
captions_words.json
```
：词或字符时间戳及检测到的间隔
```
captions.json
```
：供 HyperFrames 或 Remotion 使用的短语字幕
```
captions.srt
```
和
```
captions.vtt
```
：通用字幕文件
```
caption-qc.json
```
：对齐覆盖率和计时验证

在集成其他渲染器或交付检查工具之前，请阅读 references/artifact-contract.md。

Hard rules

硬性规则

Transcribe the exact final audio used by the MP4. Do not transcribe an earlier segment, draft voice, or a differently trimmed file.
Use the original narration text for display and ASR only for timing. This preserves names, English terms, punctuation, and intentional wording.
Align the original script to ASR tokens before grouping phrases. Do not scale boundaries by total character count.
Phrase captions remain the default. Word timestamps are the timing substrate, not a requirement to show karaoke-style one-character captions.
Preserve meaningful spaces inside English names such as
```
Claude Max
```
; never split an ASCII product/model token across captions.
Reject captions shorter than 0.5 seconds, isolated fragments, split discourse connectors, and reading speeds above 12 units/s. Treat speeds above 9 units/s as a review warning.
Keep one canonical caption timeline. Scene changes, keyword reveals, and component cues should look up caption text or timestamps from that timeline.
```
VOLCENGINE_API_KEY
```
comes from the workspace root
```
.env
```
or the environment. Never print or copy it into an artifact.
Default resource ID is
```
volc.seedasr.auc
```
; override only with
```
VOLCENGINE_RESOURCE_ID
```
when the account uses a different enabled resource.
Final delivery requires alignment coverage at least 0.90 unless a stricter project contract is set. Lower coverage is a failure, not a warning.

转录 MP4 所使用的准确最终音频。不得转录较早的分段、草稿旁白或经过不同裁剪的文件。
显示时使用原始旁白文本，ASR 仅用于计时。这样可以保留名称、英文术语、标点和有意使用的措辞。
在组合短语之前，将原始脚本与 ASR 词元对齐。不得根据总字符数缩放边界。
默认使用短语字幕。词级时间戳是计时基础，并不要求显示卡拉 OK 式的单字符字幕。
保留英文名称中有意义的空格，例如
```
Claude Max
```
；切勿将 ASCII 产品或型号词元拆分到多条字幕中。
拒绝时长短于 0.5 秒的字幕、孤立片段、被拆开的话语连接词，以及阅读速度高于 12 units/s 的字幕。阅读速度高于 9 units/s 时应触发审查警告。
保持唯一规范的字幕时间线。场景切换、关键词显现和组件提示应从该时间线查找字幕文本或时间戳。
```
VOLCENGINE_API_KEY
```
来自工作区根目录的
```
.env
```
或环境变量。切勿打印或复制到产物中。
默认 Resource ID 为
```
volc.seedasr.auc
```
；仅当账户使用其他已启用资源时，才通过
```
VOLCENGINE_RESOURCE_ID
```
覆盖。
最终交付要求对齐覆盖率至少达到 0.90，除非项目契约设置了更严格的标准。覆盖率较低属于失败，而不是警告。