真实时间戳字幕

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

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

- 口播：

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

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

Output contract

• 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

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.