真实时间戳字幕

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.

Required workflow

1. Finish and concatenate narration first. If the user recorded or merged a video, use that final merged media instead.
2. Run scripts/generate_subtitles.py against the final media and the exact narration script.
3. 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.
4. Render captions from captions.json; export captions.srt for Bilibili, YouTube, editing software, and archive.
5. 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.
6. 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.

Commands

Project with 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

Recorded or merged video with a Markdown handoff containing - 口播： lines:

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:

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

Offline regression test with an existing Volcengine response:

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

Output contract