youtube-chinese-localizer

name	youtube-chinese-localizer
description	Localize YouTube or other foreign-language videos into Chinese. Use when Codex needs to turn a YouTube URL or local video into Simplified Chinese subtitles, Mandarin dubbing, and a final exported video; also use for requests about 自动下载 YouTube 视频、生成中文字幕、中文配音、混音、烧录字幕、导出成片.

YouTube Chinese Localizer

Overview

Turn a YouTube URL or local video into a Chinese-localized deliverable:

• download or ingest the source video
• transcribe speech into timestamped segments
• translate lines into natural Simplified Chinese
• synthesize Mandarin dubbing
• mix the dub with optional low-volume source audio
• export a final MP4 with burned-in subtitles or a sidecar subtitle track

Prefer the bundled script for repeatable work instead of reassembling the pipeline by hand.

Workflow

1. Confirm the input.

Accept either:

• a YouTube URL
• a local video file
• a pre-existing transcript JSON when transcription has already been done elsewhere

2. Check runtime prerequisites.

Read references/runtime-requirements.md before first use or whenever the environment is missing tools. At minimum, the workflow expects ffmpeg. For YouTube URLs it also expects yt-dlp. For local speech-to-text it prefers faster-whisper. Translation uses Volcengine TranslateText; dubbing uses Volcengine TTS.

3. Run the pipeline script.

Use the default command first:

scripts/run_localize_video.sh \
  --input "https://www.youtube.com/watch?v=..." \
  --workdir ./runs/demo \
  --cookies-from-browser edge

Useful variants:

scripts/run_localize_video.sh \
  --input /path/to/video.mp4 \
  --workdir ./runs/local-video \
  --voice zh_female_qingxin \
  --background-volume 0.12

scripts/run_localize_video.sh \
  --input /path/to/video.mp4 \
  --workdir ./runs/from-transcript \
  --transcript-json /path/to/segments.json \
  --skip-transcription

scripts/run_localize_video.sh \
  --input "https://www.youtube.com/watch?v=..." \
  --workdir ./runs/subtitles-only \
  --skip-tts

4. Verify the outputs.

Expect these files inside the work directory:

• source.*: downloaded or copied source video
• audio.wav: extracted mono wav for speech processing
• transcript.json: timestamped source segments
• translated_segments.json: translated segments with Chinese text
• subtitles.zh.srt: Simplified Chinese subtitles
• dub_track.wav: synthesized Chinese dub track when TTS is enabled
• final_audio.wav: mixed final audio
• final.mp4: exported video deliverable

5. Review quality before handing off.

Check:

• subtitles stay aligned with scene changes
• Chinese phrasing is concise enough for speech
• dub volume is dominant and intelligible
• the original soundtrack, if retained, does not overpower speech
• no segment overflows badly past its subtitle time slot

Decision Rules

Prefer this order of execution:

1. Use a provided transcript JSON if it already contains timestamps.
2. Otherwise use local faster-whisper if available.
3. Only download with yt-dlp when the input is an online URL.
4. Use Volcengine translation credentials for subtitle translation and Volcengine TTS credentials for dubbing.
5. If TTS is unavailable, still produce the Chinese SRT and stop there instead of guessing.

Keep the translated Chinese concise. It is better to slightly compress the spoken line than to preserve every filler word and overrun the dub timing.

Failure Handling

• If yt-dlp is missing, install it or ask for a local video file.
• If YouTube blocks anonymous download, rerun with --cookies-from-browser edge or another installed browser.
• If faster-whisper is missing, install it or require --transcript-json.
• If Volcengine translation credentials are missing and the transcript lacks translated_text, stop and request either VOLCENGINE_ACCESS_KEY plus VOLCENGINE_SECRET_KEY or a pre-translated transcript.
• If Volcengine TTS credentials are missing, keep generating Chinese subtitles and stop before dubbing.
• If subtitle burn-in fails because of an ffmpeg path issue, keep subtitles.zh.srt and export without burn-in rather than losing the localized result.

Resources

• scripts/run_localize_video.sh: wrapper that runs the pipeline inside the preinstalled .venv
• scripts/localize_video.py: end-to-end download, ASR, translation, TTS, subtitle, mix, and export pipeline
• references/runtime-requirements.md: dependency setup, environment variables, and troubleshooting notes