Skip to content

SKILL.md

Latest commit

 

History

History
215 lines (176 loc) · 7.81 KB

SKILL.md

File metadata and controls

215 lines (176 loc) · 7.81 KB
Raw

ai-video-dubber

描述

AI 视频配音工具，将视频从源语言（默认中文）配音为目标语言（默认英文），使用 ElevenLabs 克隆说话人声音，Gemini 多模态优化同步质量。

核心流程：

  1. 人声分离（htdemucs_ft → UVR-MDX fallback → FFmpeg fallback）
  2. ASR 转录（ElevenLabs Scribe）
  3. 翻译（Gemini 2.5 Flash via OpenRouter）
  4. TTS 合成（ElevenLabs eleven_v3）
  5. Gemini 多模态优化循环（最多 5 轮）
  6. FFmpeg 渲染混音

触发条件

  • 用户说"帮我配音"、"把这个视频翻译成英文"、"video dubbing"
  • 用户发送视频文件并要求语言转换
  • 用户问"配音质量怎么样"、"修复某个片段"

工具列表

  • dub_video: 完整配音流程（transcription → translation → TTS → render → Gemini 优化）
  • fix_segment: 修复单个片段（翻译、情绪、时间轴）
  • analyze_quality: 用 Gemini 分析配音质量
  • adjust_volume: 调整背景音量或特定说话人音量
  • list_projects: 列出历史项目
  • show_segments: 查看项目片段详情

使用方式

dub_video（完整配音）

from dubber.adapters.openclaw_skill import DubberSkill

skill = DubberSkill(config={
    "gemini_api_key": "sk-or-...",
    "gemini_base_url": "https://openrouter.ai/api/v1",
    "gemini_model": "google/gemini-2.5-flash",
    "elevenlabs_api_key": "...",
    "storage_dir": "/path/to/storage",
})

result = await skill.execute("dub_video", {
    "video_path": "/path/to/video.mp4",
    "source_language": "zh-CN",
    "target_language": "en-US",
    "optimize": True,
    "max_iterations": 5,
    "feishu_open_id": "ou_xxx",  # 可选，完成后自动发送到飞书
})

fix_segment（修复片段）

result = await skill.execute("fix_segment", {
    "project_id": "abc123",
    "segment_index": 3,
    "translation": "Hello, nice to meet you.",
    "emotion": "happy",
})

list_projects / show_segments

projects = await skill.execute("list_projects", {})
segments = await skill.execute("show_segments", {"project_id": "abc123"})

参数说明（dub_video）

参数 类型 必填 默认值 说明
video_path string ✅ — 视频文件路径
source_language string "auto" 源语言代码（auto = 自动检测）
target_language string ✅ — 目标语言代码，如 en-US、ja、ko
optimize boolean true 是否启用 Gemini 逐步优化
max_iterations integer 5 最大优化轮数（0 = 禁用优化）
quality_threshold integer 95 达到此分数后提前停止（0–100）
max_cost_usd float 5.0 Gemini API 最大消费（美元）
source_text string — 手动提供源语言转录文本（跳过 ASR）
skip_render boolean false 跳过最终渲染（仅做 TTS）
feishu_open_id string — 完成后自动发送视频到飞书用户
gemini_api_key string config 覆盖配置中的 Gemini API key
gemini_base_url string config 覆盖配置中的 base URL
gemini_model string config 覆盖配置中的模型名

配置优先级

配置值按以下优先级读取（高 → 低）：

  1. skill config — DubberSkill(config={...}) 或 execute("dub_video", {...}) 的参数
  2. settings.json — storage/settings.json 中的值
  3. config.py defaults — dubber/config.py 中的硬编码默认值

默认值

配置项 默认值 config.py 常量
asr_model scribe_v2 DEFAULT_ASR_MODEL
tts_model eleven_v3 DEFAULT_TTS_MODEL
gemini_model google/gemini-3.1-pro-preview DEFAULT_GEMINI_MODEL
bg_volume 1.0 DEFAULT_BG_VOL
bg_lufs -14.0 DEFAULT_BG_LUFS
drums_silent_threshold_db -50.0 DRUMS_SILENT_THRESHOLD_DB
vocals_bleed 0.0 VOCALS_BLEED_DEFAULT
ambient_mode "auto" AMBIENT_MODE
speed_min 0.7 SPEED_MIN
speed_max 1.3 SPEED_MAX
max_stretch_ratio 1.5 DEFAULT_MAX_STRETCH_RATIO

配置要求

在 skill config 或 storage/settings.json 中设置：

{
  "api_keys": {
    "openai_api_key": "sk-or-...",
    "openai_base_url": "https://openrouter.ai/api/v1",
    "elevenlabs_api_key": "..."
  },
  "models": {
    "tts_provider": "elevenlabs",
    "tts_model": "eleven_v3",
    "asr_provider": "elevenlabs-scribe",
    "translation_model": "google/gemini-2.5-flash"
  },
  "gemini_api_key": "sk-or-...",
  "gemini_base_url": "https://openrouter.ai/api/v1",
  "gemini_model": "google/gemini-2.5-flash"
}

环境变量也支持：

  • GEMINI_API_KEY
  • GEMINI_BASE_URL

Atomic Operations（24 个原子操作）

Gemini 优化循环会从以下操作中选择并应用：

Op 说明 触发场景
translation_fix 修正翻译文本 翻译不准或语义错误
emotion_change 改变情绪标签 情绪与画面不符
tts_resynth 重新合成 TTS 翻译或情绪改变后
segment_timing 调整片段时间轴 音视频不同步
rephrase_translation 改写翻译使其更简短/更长 语速过快/过慢
speed_adjust 调整 TTS 播放速度 细微速度调整
volume_adjust 调整片段音量 某片段过响/过轻
background_volume 调整背景音乐音量 背景音掩盖人声
speaker_volume 调整说话人音量 某说话人音量不均
emotion_change 修改情绪 语气与内容不符
av_align 微调音视频对齐（ms 级） 细微口型不同步
sync_offset 全局音视频偏移 系统性延迟偏移
batch_timing_shift 批量时间轴偏移 整段偏移修正
segment_split 拆分片段 长句需拆成短句
segment_merge 合并片段 碎片化片段合并
segment_delete 删除片段 噪声/重复片段
retranscribe 重新转录某时间段 遗漏内容
source_text_fix 修正源语言文本 ASR 识别错误
speaker_assign 重新分配说话人 说话人识别错误
speaker_merge 合并说话人 同一人被识别为多人
voice_change 更换 TTS 声音 声音与角色不符
tts_style 调整 TTS 风格参数 stability/style 微调
subtitle_fix 修正字幕文本 字幕错误
subtitle_style 修改字幕样式 字体/位置/颜色调整
set_speed_limit 设置最大速度拉伸比 控制 atempo 上限

输出格式

dub_video 成功后返回：

{
  "success": true,
  "output_path": "/path/to/output.mp4",
  "project_id": "abc123",
  "report_text": "✅ 配音完成\n...",
  "report": {
    "video_info": {"duration_seconds": 120, ...},
    "segments": {"total": 45, "translated": 45, "with_tts": 45},
    "speakers": [{"label": "说话人1", "gender": "female", ...}],
    "optimization": {"iterations": 3, "final_score": 87}
  }
}

安装依赖

cd /path/to/ai-video-dubber
python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
# 可选，用于更好的音频时间拉伸:
.venv/bin/pip install pyrubberband

系统依赖：

  • ffmpeg（含 libass 字幕支持建议用 ffmpeg-full）
  • ffprobe
  • demucs（htdemucs_ft 人声分离，可选）

注意事项

  • 长视频自动分块：超过 ChunkManager 阈值（约 10 分钟）自动切片处理后合并
  • MP3 时长探测：优先用 soundfile，失败自动 fallback 到 ffprobe（避免部分 MP3 编码问题）
  • bg_volume clamp：背景音量强制限制在 [0.01, 2.0] 防止爆音
  • auto-rephrase：TTS 超时（ratio > max_ratio × 1.05）时自动调用 rephrase_translation op 缩短文本
  • 飞书发送：需要 ~/.openclaw/openclaw.json 中有 appId 和 appSecret