用途:为已完成并拼接好的最终旁白音频或最终合并视频生成生产级字幕。必须以最终音轨作为唯一时间来源,不得用字符数、场景时长、TTS 分段时长或固定延迟估算时间。
主要能力:调用 scripts/generate_subtitles.py,结合最终媒体与准确旁白文本进行 ASR 对齐;输出 asr-result.json(火山引擎原始响应)、captions_words.json(词/字时间戳与检测到的间隙)、captions.json(短语字幕,供 HyperFrames 或 Remotion 使用)、captions.srt 与 captions.vtt(通用字幕文件)、caption-qc.json(对齐覆盖率与时间校验)。
必要用法:项目含 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;已录或合并视频且交接文档含“- 口播:”行时,用 <project>/merged.mp4 与 <project>/handoff.md 同理运行。健康检查加 --doctor;离线回归用 --asr-result <volcengine-result.json>。VOLCENGINE_API_KEY 取自工作区根 .env 或环境变量,不得写入产物。默认资源 ID 为 volc.seedasr.auc,仅在账号使用不同已启用资源时用 VOLCENGINE_RESOURCE_ID 覆盖。整合其他渲染器或交付检查器前需阅读 references/artifact-contract.md。
限制与规则:仅转录 MP4 实际使用的最终音频,不得转录草稿或不同裁剪文件;显示用原始旁白文本,ASR 仅提供时间;分组短语前先将原始脚本与 ASR token 对齐,不得按总字符数缩放边界。保留 Claude Max 等英文名称中的空格,不得拆分 ASCII 产品/模型 token。拒绝短于 0.5 秒的字幕、孤立片段、被拆分的语篇连接词及超过 12 单位/秒的阅读速度,超过 9 单位/秒为复查警告。最终交付要求对齐覆盖率至少 0.90,更低即为失败。caption-qc.json 须报告 status: pass 才能最终渲染或交付;ASR 失败或覆盖率不足时应停止,字符数估算仅可用于明确标注的临时预览。其余集成细节暂未提供。