video-dubbing

video-dubbing: 视频翻译配音与字幕同步

Purpose

把一段视频整体本地化为另一种语言：识别原语音、翻译、用 TTS 生成目标语言配音，在保持原始 时间戳的前提下合成音轨并把译文硬字幕烧进画面。产出是可直接发布的单文件视频，配音与字幕 天然同步，不需要二次对轴。

When to Use

• 用户要求把视频翻译成另一种语言，并要配音（不只是字幕）。
• 需要给视频加目标语言配音 + 同步字幕（双语或纯译文）。
• 触发词：视频翻译、视频配音、翻译字幕、生成外语配音、双语字幕、dub a video、translate a video、 foreign-language voiceover。
• 任何 ASR -> 翻译 -> TTS -> 视频合成的工作流。

When NOT to Use

• 只需转录、不需要翻译或配音 -> 交给 video-minutes 或直接 whisper。
• 只需把文字合成为音频、不涉及视频 -> 交给 mlx-tts。
• 需要保留原背景音乐/音效并做专业混音（人声分离）-> 本技能默认不做 Demucs，需另行处理。
• 视频无音轨或音质极差到无法识别。

Workflow

端到端推荐直接用编排脚本 <skill>/scripts/dub.py（见 ## Scripts），它会依次执行下面各步并 在翻译处暂停等待 AI 翻译。手动执行时按以下步骤：

1. 抽音轨（16kHz 单声道）： ffmpeg -y -i input.mp4 -ar 16000 -ac 1 -c:a pcm_s16le audio16k.wav

2. ASR 转录（要逐段准确时间戳）： whisper audio16k.wav --model large-v3-turbo --language <源语言> --output_format srt --output_dir . 产出 audio16k.srt，时间戳与原视频天然对齐。想要更好的中文识别可改装 Qwen3-ASR （pip install qwen-asr）并用 <skill>/scripts/qwen3_asr.py。

3. 翻译字幕（由 AI 完成）：读 SRT，逐段翻译。每个 SRT 段输出一行译文，严格保持顺序。 先数清段数（如 27 段 -> 27 行），存为 translated.txt，继续前核对行数一致。

4. 生成配音： python3 <skill>/scripts/dub_segments.py audio16k.srt translated.txt dubbing.wav subtitle_synced.srt --lang <目标语言> 脚本会：用首段作音色参考保证音色一致；保留原始时间戳让字幕与画面同步；只对溢出槽位 的段做变速（atempo 0.88–1.20）；把相邻小于 1s 的间隔桥接起来让听感自然。

5. 合并配音音轨到视频：

   ffmpeg -y -i input.mp4 -i dubbing.wav \
     -map 0:v:0 -map 1:a:0 \
     -c:v copy -c:a aac -b:a 192k -shortest output_temp.mp4
   

   然后确认音轨已被替换： ffprobe -v error -show_entries stream=codec_type -of csv=p=0 output_temp.mp4（应显示 video, audio）。

6. 烧录硬字幕： python3 <skill>/scripts/burn_subtitles.py output_temp.mp4 subtitle_synced.srt output_final.mp4 把译文字幕永久渲染进画面。

7. 清理（可选）：删除 audio16k.wav、audio16k.srt、translated.txt、dubbing.wav、 subtitle_synced.srt、output_temp.mp4 等中间产物。

Decision Rules

• 想一键跑完 -> 用 dub.py；只想重跑某一步（如已有 SRT）-> 用 dub.py --srt existing.srt 跳步。
• ASR 引擎：默认 --asr whisper（large-v3-turbo）；中文识别要求高 -> --asr qwen3。
• 不需要硬字幕 -> dub.py --no-burn（只到音轨合并）。
• 目标语言由 --target-lang 决定（默认 zh）；dub_segments.py 的 TTS 语言由 --lang 决定。
• 翻译必须由 AI 完成且与 SRT 段严格 1:1；行数不符时脚本直接报错退出，不要绕过。
• 字幕没出现/中文变方框 -> 用 burn_subtitles.py（moviepy 渲染，自动找中文字体），不要依赖 ffmpeg 的 subtitles=（libass 缺失时会静默失败）。
• 配音时长溢出槽位 -> 依赖脚本的分段 atempo，不要对整条音轨做全局变速。