mcpField
R
ra-audio-to-subtitles

ra-audio-to-subtitles

github.com/pluviobyte创意与媒体1.7k182 次安装5 周前更新
代码仓库

关于 ra-audio-to-subtitles

ra-audio-to-subtitles 根据最终旁白或合并视频的音频时间戳生成短语级字幕。它保留原始脚本用于显示，并要求通过对齐和可读性检查后才能交付。

主要功能

  1. 01将脚本文本对齐到最终媒体的语音识别时间
  2. 02生成短语字幕和词语时间戳
  3. 03导出 JSON、SRT 和 VTT 字幕文件
  4. 04检查对齐、重叠、碎片及阅读速度
  5. 05交付前要求质检通过

适用场景

  1. 01为完成的配音制作字幕
  2. 02依据录制或合并视频的最终音频制作字幕
  3. 03渲染或交付前验证字幕时间

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/pluviobyte/rnskill --skill ra-audio-to-subtitles

安装后在 Claude Code 中输入/ra-audio-to-subtitles确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
artifact-contract.md
scripts/
generate_subtitles.py

详细介绍

真实时间戳字幕

仅使用最终音频流作为时间依据。绝不要根据字符数、场景时长、TTS 片段时长或固定延迟来估算最终字幕时间。

必需工作流

  1. 先完成并合并旁白。如果用户录制或合并了视频，则改用最终合并后的媒体。
  2. 对最终媒体和准确的旁白脚本运行 scripts/generate_subtitles.py。
  3. 检查短语分段。保留完整的英文产品/模型词项，合并孤立的单词片段，并将“比如说”“但是”和“只是”等连接词与其引出的短语放在一起。
  4. 根据 captions.json 渲染字幕；导出 captions.srt，用于 Bilibili、YouTube、编辑软件和归档。
  5. 最终渲染或交付前，必须确保 caption-qc.json 报告 status: pass。检查项包括对齐、重叠、片段、连接词拆分、字幕时长和阅读速度。
  6. 如果 ASR 失败或对齐覆盖率低于门槛，则停止。只有在明确标记为临时预览时，才可使用字符数估算。

命令

包含 narration_segments.json 的项目：

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 交接文档所对应的录制或合并视频：

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

健康检查：

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

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

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

输出约定

输出目录必须包含：

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

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

硬性规则

  • 转写 MP4 使用的确切最终音频。不要转写较早的片段、草稿语音或剪辑方式不同的文件。
  • 显示字幕时使用原始旁白文本，ASR 仅用于确定时间。这样可以保留名称、英文术语、标点和有意使用的措辞。
  • 先将原始脚本与 ASR 词项对齐，再对短语分组。不要按总字符数缩放边界。
  • 短语字幕仍是默认形式。词语时间戳是时间依据，并不意味着必须显示卡拉 OK 式的逐字符字幕。
  • 保留 Claude Max 等英文名称中的有效空格；绝不要将 ASCII 产品/模型词项拆分到不同字幕中。
  • 拒绝短于 0.5 秒的字幕、孤立片段、被拆开的语篇连接词，以及阅读速度超过 12 个单位/秒的字幕。速度超过 9 个单位/秒时应作为复核警告处理。
  • 只保留一条规范的字幕时间线。场景切换、关键词显示和组件提示都应从该时间线查询字幕文本或时间戳。
  • VOLCENGINE_API_KEY 来自工作区根目录中的 .env 或环境变量。绝不要将其打印出来或复制到任何产物中。
  • 默认资源 ID 为 volc.seedasr.auc；只有当账户使用其他已启用资源时，才通过 VOLCENGINE_RESOURCE_ID 覆盖。
  • 最终交付要求对齐覆盖率至少达到 0.90，除非项目约定设置了更严格的要求。覆盖率较低属于失败，而非警告。

评论

支持 Markdown