项目概览
xiaohuai-video-translate 是一套面向 AI 编程工具的视频翻译技能套件，由 xiaohuailabs（小灰）开发。它不是独立应用，而是由「脚本 + 说明书」组成的 AI Agent 技能，可被 Claude Code、OpenClaw、Gemini CLI、Codex 等工具加载和驱动。项目将下载、转写、翻译、润色、烧录等步骤编排为一条龙流水线，用户只需说一句话即可完成。转写使用本地 Whisper 引擎，不产生 API 费用；翻译复用已有的 AI 模型。项目包含三个独立技能：总指挥、字幕润色、下载专员，可单独或组合使用。支持中英双语字幕，通过 ASS 格式实现中文大、英文小的字号反差。全程本地运行，不上传数据，保护隐私。项目处于活跃状态，最新提交为 2026-06-08，采用 MIT 协议。
解决什么问题
在 xiaohuai-video-translate 出现之前，将外语视频翻译成中文字幕视频需要多个工具和繁琐步骤。报告指出传统流程存在六大痛点：工具碎片化（下载、转写、翻译、字幕编辑、烧录需用不同软件）；时间戳对不齐（YouTube 自动字幕为滚动叠加格式，Whisper 默认按 segment 切分，导致字幕与说话人不同步）；字幕不像人写的（机翻字幕专有名词错误、断句不合中文习惯）；双语字幕无法实现字号反差（SRT 与 ffmpeg 的 force_style 无法一条内分字号）；烧录和水印两次编码损失画质；每个工具学习成本高。此外，AI Agent 已能理解自然语言指令，但缺少将视频翻译任务标准化、技能化的方案。
工作方式
项目采用技能制架构，由三个独立技能组成：xiaohu-video-md（总指挥，负责编排）、xiaohu-subtitle-polish（字幕专家，负责润色）、xiaohu-video-download（下载专员）。底层依赖 yt-dlp、Whisper、ffmpeg 和 AI 大模型，项目在其上做编排和润色。完整流程包括：确认字幕类型、下载视频、提取音频并转写、调用润色技能、烧录字幕和水印（一次编码）、生成 Markdown 文稿。转写引擎采用三层降级链：MLX Whisper（Apple Silicon GPU）→ faster-whisper（通用）→ whisper-cli（纯文本应急）。字幕润色定义了 8 条规则：纠正 ASR 识别错误、去标点、去冗余、时间戳严格对齐、断句分段（每行 ≤12 中文字符）、专有名词保留原文、当代语言风格、歌词处理。双语字幕通过 SRT 转 ASS 格式，使用 libass 渲染实现中文大、英文小的反差效果。烧录和水印在同一条 ffmpeg 命令中完成，避免两次编码。
核心能力
- 全程本地运行，转写零 API 费用
- 自然语言驱动，一句话完成翻译
- 兼容多 AI 工具（Claude Code、OpenClaw、Gemini CLI、Codex）
- 词级时间戳精度，字幕不跑在说话人前面
- 专业字幕润色，8 条规则保证质量
- 双语 ASS 字幕，中文大、英文小
- 一次编码，字幕和水印同时完成，不损失画质
- 多语种支持（英语、日语、韩语、法语、西班牙语等）
- 三个技能独立可组合
- 丰富的踩坑经验记录在 SKILL.md 中
使用前需要了解
- AI 整理 · 本地测试，未经人工复核；依据历史报告节选，不代表当前产品状态。
- 报告明确列出以下局限：不支持实时翻译（需先下载完整视频）；音频质量要求高（BGM 太响或背景噪音大时误判率上升）；长视频处理时间长（140 分钟视频转写约 5-8 分钟，总计可能 15-20 分钟）；抖音下载依赖浏览器登录态。不建议用于专业影视剧字幕翻译（需逐句精校、配音对齐、特效字幕）、直播实时字幕、没有 AI 编程工具的环境、对翻译质量要求极高的正式发布（建议人工审校）。此外，项目依赖本地 GPU/CPU 性能，macOS 优先（MLX 仅支持 Apple Silicon），跨平台字体适配不完善（需手动切换中文字体）。安装后必须设置 config.json 中的 output_dir 为绝对路径，否则报错停止。
