yanghhu/ai-voiceover

AI 语音旁白

使用 voiceover CLI（包 ai-voiceover-studio，Python 3.9+）生成旁白。

环境检查

1. voiceover --version — 如果缺失：pip install -e "<仓库路径>[edge]" （[edge] = 免费语音，[yaml] = voices.yaml 支持）
2. 运行 voiceover doctor --json 并修复报告为 fail 的所有问题（它从不输出密钥）。
3. 引擎：无密钥时默认使用免费 edge 引擎（需要网络，无需账户）。 MIRAGEA_API_KEY 会将默认引擎切换为 Miragea（声音克隆、表现力模型）； OPENAI_API_KEY 启用 --provider openai。切勿要求用户在聊天中粘贴密钥、 不得回显密钥、不得将密钥写入文件。
4. MP3输出和视频需要 ffmpeg（内嵌字幕需要 libass 支持）。

工作流：为脚本配音

1. 准备脚本（Markdown 或 TXT）。每行或每段一个说话人标签：

   [叙述者]: 开场台词。
   未标签的行继续当前说话人。
   
   [ALEX](tags=excited, speed=1.1): 另一个角色。
   [pause 1]
   

   标题、HTML注释、代码块和表格将被忽略。
2. 语音配置（可选）。 如果没有语音文件，每个说话人会自动获得一个语音， 根据脚本语言自动选择。如需手动选择：voiceover voices --json（添加 --provider edge --filter en-GB 获取 Edge 语音，如 en-GB-SoniaNeural；Miragea 下使用 voice_id = actor id）。如果两个语音同名，请询问用户选择哪个。使用 Miragea 时， 语音也可以是公开参考音频URL及其精确转录（reference_text）。 仅克隆用户拥有或有权使用的语音。
3. 编写 voices.json 如果用户选择了语音（键名大写）：

   {"NARRATOR": {"actor_id": "en-US-AndrewNeural"}, "ALEX": {"actor_id": "en-US-AvaNeural", "speed": 1.05}}
   

4. 空跑验证（离线，验证说话人和时间线）： voiceover script script.md -o out/ --dry-run --json
5. 生成：voiceover script script.md [--voices voices.json] -o out/ --json 输出 out/voiceover.mp3、out/voiceover.srt、out/manifest.json、out/segments/。
6. 报告保存的路径和时长。仅当命令退出码为0时才宣称成功。

其他命令

• 单行生成：voiceover say "文本" [--voice <语音ID|https://参考音频.wav>] [--ref-text "..."] [--lang en] -o line.mp3
• 无脸视频：voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] 默认内嵌字幕。每段一张图片可实现精确幻灯片时间线；没有 --images 则使用渐变背景。对于短视频推荐 --size 1080x1920 --style bold。
• 通过语音识别生成字幕（Miragea）：添加 --subtitles recognize（额外一次API调用）。
• 等待超时后恢复任务：voiceover task <任务ID> --wait -o out.mp3

规则

• 重复运行相同命令是安全的：未更改的片段来自缓存，远程请求使用幂等键。仅在用户要求重新录制时使用 --fresh。
• 等待超时后，保留报告的 task_id 并使用 voiceover task 恢复；不要重新提交。
• 退出码：0 成功，1 提供者任务失败，2 使用/配置/API错误。使用 --json 时，错误格式为 {"error": {"code", "message", "http_status", "retryable"}, "task_id"?}。
• 401：密钥被拒 → 用户检查密钥变量。403：账户无API访问权限。 429：配额/速率限制 → 等待，不要循环。400：修正文本/语音/速度/标签。
• proxy_unsupported（edge）：设置 VOICEOVER_EDGE_PROXY 或取消 HTTPS_PROXY 环境变量后重试。
• 语言支持：edge 覆盖75种语言；Miragea 覆盖中文、英语、日语、韩语、德语、 法语、俄语、葡萄牙语、西班牙语、意大利语（含声音克隆）。