视频中文配音工具

使用随附的Python流水线完成完整的中文配音视频。当用户提供URL并要求最终成品时，不要仅仅提供建议的工作流程：如果终端执行可用且用户已授权所需的网络/下载操作，则应运行流水线。

需要Python 3.10+、FFmpeg/ffprobe、用于URL下载的网络访问以及本地faster-whisper模型。在线翻译和语音是可选的；当需要自然的普通话语音且无需付费语音API时，请使用本地CosyVoice后端。

将<skill-root>解析为包含此SKILL.md的目录；不要假定调用者的当前工作目录就是技能目录。在macOS/Linux上，优先使用<skill-root>/.venv/bin/python；在Windows上优先使用<skill-root>/.venv\Scripts\python.exe（如果该虚拟环境存在）；否则使用活动的Python解释器。以下命令假定当前目录已切换到<skill-root>。

快速开始

检查先决条件：
```
python3 scripts/check_environment.py
```
安装FFmpeg和Python依赖项。请参阅README.md了解macOS、Windows和Linux的命令。
如需免费API的自然翻译，请使用已安装的Ollama模型，并带上参数--translation-provider ollama --ollama-model MODEL。流水线会在本地运行两遍翻译，并验证每个片段ID；在交付前请检查术语和时序。如果没有本地模型，仅在允许的情况下使用--translation-provider google作为在线草稿，并手动润色带时间戳的片段；或通过--segments-file传递已审阅的JSON。仅在明确允许时才使用OPENAI_API_KEY或DEEPSEEK_API_KEY；切勿切换到不允许的API。

转换视频URL（Bilibili、YouTube或任何yt-dlp支持的网站）：

python3 scripts/translate_video.py "https://www.youtube.com/watch?v=VIDEO_ID" \
  --translation-provider ollama --ollama-model MODEL --output-dir ./output

Bilibili URL可以包含参数如?p=2；请传递完整的目标URL。

或者处理本地视频：

python3 scripts/translate_video.py ./input.mp4 \
  --translation-provider ollama --ollama-model MODEL --output-dir ./output

默认值和选项

源语言默认为英语（--source-language en）；使用auto可自动检测。
中文语音默认为zh-CN-XiaoxiaoNeural；使用--voice zh-CN-YunxiNeural可获得较年轻的男声，或使用--voice zh-CN-YunyangNeural获得男性旁白声。
对于免费的自然语音合成，当有明确授权的参考片段和精确逐字稿时，优先使用本地安装的Fun-CosyVoice3-0.5B的zero-shot模式。否则，使用CosyVoice-300M-SFT及内置说话人（例如中文女）。未经许可不得克隆声音。模型会对所有片段加载一次，写入PCM16 WAV片段并检查点进度。请参阅README.md了解相关标志。
如果Edge TTS不可用，请设置DASHSCOPE_API_KEY并使用--tts-provider dashscope --voice Cherry来使用Qwen3 TTS。翻译后的逐字稿文本将发送到DashScope。
翻译默认设置为auto，即仅使用明确配置的本地OLLAMA_MODEL，否则会在翻译前停止。在向外部翻译器发送任何逐字稿之前，请明确选择--translation-provider openai或google。Ollama需要其本地服务和一个已安装的模型；本技能不会自动下载模型。当文件名不能清晰标识主题时，使用--translation-context "视频主题和关键术语"；否则将使用标题或文件名。
--audio-mode replace用中文语音替换源音频（默认，可靠）。--audio-mode mix以低音量保留原始音轨，同时叠加中文语音。--audio-mode background尝试使用可选的Demucs分离原始人声，然后将中文语音与剩余背景混合。如果Demucs不可用或失败，脚本会报告问题并安全地回退至替换音频模式。
--subtitle-mode soft在MP4中嵌入可选的中文字幕，并同时写入外部SRT文件（默认）。首先检查源帧：如果字幕已烧录到画面中，请保持soft模式以避免重复文本重叠。burn将字幕烧录到画面中，需要带有subtitles/libass滤镜的FFmpeg构建以及可用的中文字体。none在MP4中省略字幕，但会生成一个SRT侧边文件供审阅。
使用--model small（平衡默认值）、--model medium或--model large-v3来调整ASR。较大的模型需要更多内存并且耗时更长。首次运行会下载所选模型。
仅当您已登录且网站需要您自己的浏览器会话时，才使用--cookies-from-browser chrome。这会读取本地浏览器cookie；默认不启用。
使用--keep-intermediates保留下载的源音频、WAV文件以及生成的语音片段，以便进行故障排除。
使用--segments-file path/to/translated.segments.json可在TTS失败后重复使用已审阅的翻译，而无需重复进行识别和翻译。
使用--reuse-tts-dir path/to/tts_segments配合现有的一组生成片段来调整时序并重新渲染，而无需再次调用语音服务。

必需输出检查

脚本必须验证MP4文件存在、非空、包含视频流和音频流，并且时长接近输入文件。它会生成一个SRT文件、翻译后的片段JSON以及一个处理报告，位于最终MP4文件旁边。任何阶段失败都必须停止流水线并给出有用的错误信息，而不是假装输出完成。

在交付前，检查翻译后的JSON/SRT中是否存在误转写的人名和术语、不自然的逐字翻译以及被加速或截断的片段。还要检查渲染的画面：拒绝出现字形缺失的方框、屏幕外字幕以及重复的硬编码字幕。对于CosyVoice，在渲染长视频前先试听一小段样本；检查实际发音是否准确，尤其是小数、代码名称和英语术语，而不仅仅是它们的书面形式。经过审阅的片段可以在spoken_text中添加拼音或文件名自然读出，同时保持zh_text为精确的字幕内容。其含义必须匹配。避免交付经过裁剪的语音或明显加速的内容。

工作流程

解析URL或本地文件。对于URL，使用yt-dlp仅下载请求的视频（--no-playlist）。如果Bilibili页面返回412，脚本仅当视频明确标记为可下载时才使用Bilibili的公共API；保留请求的?p=部分。切勿绕过DRM、付费墙或账户限制。
使用ffprobe检查流和时长。提取16kHz单声道PCM音频。
使用faster-whisper进行转写，保留源时间戳。如果未检测到语音，请明确失败。
结合主题和邻近语音上下文进行翻译，然后润色成简洁、地道的中文。保留ID、顺序、含义、数字、名称和技术术语。根据视频主题检查识别错误。
通过选定的语音服务生成每个中文语音片段。保守地将其适配到时间戳窗口内；当片段需要激进加速或截断时，在报告中给出警告。
构建完整长度的中文语音音轨。应用请求的音频模式；可选的Demucs分离是增强功能，而非硬性依赖。
写入中文SRT和翻译后的JSON。按请求封装或烧录字幕，导出广泛兼容的H.264/AAC MP4，并验证结果。
报告确切的输出路径、所选设置、警告以及任何剩余的审阅需求。

示例

# YouTube URL；API翻译；中文女声；对提取的背景进行配音叠加
OPENAI_API_KEY="$OPENAI_API_KEY" python3 scripts/translate_video.py "https://youtu.be/VIDEO_ID" \
  --translation-provider openai --audio-mode background --subtitle-mode soft --output-dir ./output

# Bilibili第2部分；使用已配置的LLM密钥进行自然翻译
python3 scripts/translate_video.py "https://www.bilibili.com/video/BV1NAuq6uE8t/?p=2" \
  --translation-provider openai --translation-context "规范驱动开发 SDD 与智能体编程" \
  --voice zh-CN-YunyangNeural --audio-mode mix --output-dir ./output

# 将中文字幕烧录到画面中
python3 scripts/translate_video.py ./input.mp4 --subtitle-mode burn --output-dir ./output

# 使用CosyVoice3和授权参考片段进行完全本地语音合成；无需付费API
python3 scripts/translate_video.py ./input.mp4 --segments-file ./reviewed.segments.json \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/Fun-CosyVoice3-0.5B \
  --cosyvoice-mode zero-shot --cosyvoice-prompt-audio ./reference.wav \
  --cosyvoice-prompt-text-file ./reference.txt --subtitle-mode burn --output-dir ./output

# 本地转写、Ollama翻译和CosyVoice旁白
python3 scripts/translate_video.py ./input.mp4 --translation-provider ollama --ollama-model MODEL \
  --tts-provider cosyvoice --cosyvoice-python /path/to/cosyvoice-python \
  --cosyvoice-repo /path/to/CosyVoice --cosyvoice-model-dir /path/to/CosyVoice-300M-SFT \
  --cosyvoice-mode sft --output-dir ./output

安全与权利

仅处理您拥有所有权、获得改编许可或以其他方式允许下载和转换的视频。尊重源平台的条款和版权。切勿绕过DRM或技术访问控制。--cookies-from-browser是选择加入的，仅应使用用户自己的已认证会话。未经确认适用权利，请勿发布配音衍生作品。

该项目用于学习、研究和技术交流。请勿将其用于非法活动、未经授权的语音克隆、欺诈、身份冒充或误导性内容。请参阅README.md中的免责声明；用户需自行承担根据适用法律使用和分发生成内容的责任。

video-zh-dubbing：英文视频转中文配音成片