voiceover-maker 是一个多 provider 的 TTS 配音生成器，由 43 COLLEGE 凯寓（KAIYU）出品，版本 v1.0。它的核心用途是把任意文本转换成 MP3 口播、旁白、配音或朗读文件，并按语种自动路由到不同服务商：中文走 MiniMax（中文质量更好），英文走 ElevenLabs。
【触发场景】 当用户提出“用 TTS 把这段话生成口播/旁白/配音/朗读”“把这段文字变成语音/念出来/录成音频”“做一段视频旁白 MP3”“voice this / narrate this / read this aloud”“把这篇公众号文章录成音频”等需求时触发。若用户只是问“TTS 是什么意思”这类科普问题则不触发，该 Skill 仅用于生成 MP3 文件。
【使用方式】 首次使用需先配置至少一个 provider 的 API key，推荐两个都配以实现按语种自动路由，详见 SETUP.md。主脚本为 scripts/tts.py，零依赖，仅使用 Python 3 标准库。
基本用法示例： python3 ${CLAUDE_SKILL_DIR}/scripts/tts.py "你好世界，这是一段中文测试。" # auto → MiniMax python3 ${CLAUDE_SKILL_DIR}/scripts/tts.py "Hello world, this is a test." # auto → ElevenLabs 输出默认到 ~/Desktop，文件名格式为 tts-{provider}-{voice}-{timestamp}.mp3。
首次使用推荐先跑预检： python3 ${CLAUDE_SKILL_DIR}/scripts/tts.py --check 预检不调真实合成 API，只检查 config.json 是否存在且能解析、ElevenLabs / MiniMax key 是否填写、静默 asset 是否就位、两个 endpoint 网络可达性。
【主要能力】
- 指定音色：--voice 既接受预设名，也接受原始 voice_id 透传，大小写不敏感。
- 强制 provider：--provider minimax 或 --provider elevenlabs。
- MiniMax 情绪/语速/音调/音量调节：--emotion（neutral / happy / sad / angry / fearful / disgusted / surprised）、--speed（0.5–2.0）、--pitch（-12–12）、--vol（0.5–2.0）。ElevenLabs 不支持这些参数，传了会被忽略并打 warning。
- 长文本处理：支持从文件读取并自动分段。MiniMax 单次上限 9500 字符（保留 buffer，原始 10000），ElevenLabs 单次上限 4500 字符。超长按“段落 → 句末标点 → 硬切”顺序自动分段，多段 MP3 帧直接拼接。
- Dry-run 估价：--dry-run 不调 API，打印文本字符数、估算计费字符、估算费用（CNY/USD）、分段数及各段字符数。
- 音色试听：--preview 用固定示例文本生成 5 秒样本到 ~/Desktop/preview-{provider}-{voice}.mp3，自动覆盖同名文件。
- 长稿段间静默：多段合成时默认在段与段之间插 300ms 静默，可用 --gap-ms 调整（按 300ms 单位四舍五入）。
- 输出控制：-o 指定输出路径，-o - 输出到 stdout（管道），--force 覆盖已存在文件（默认不覆盖）。
- 列出音色：--list-voices 列出本地预设，--list-remote-voices 列出 MiniMax 远端系统音色（约 300 个），支持 --filter 过滤。
- 本地缓存：相同 (provider + voice_id + model + text + voice_settings + audio_setting) 组合命中缓存直接复用，命中时打印 ✓ cache hit [hash]。可用 --no-cache 跳过、--clear-cache 清空。
- 用量统计：--usage 打印今天/本月/累计的请求数与计费字符数，按 key 拆分及缓存大小，数据来自 usage.jsonl。
- 单元测试：python3 -m unittest tests.test_logic -v，26 个测试覆盖语种检测、文本分段、计费字符、缓存 key、价格估算，纯逻辑不调网络。
【路由规则】 config.json 的 language_routing 默认为 { "zh": "minimax", "en": "elevenlabs" }。语种检测以汉字占比 ≥ 15% 视为中文，否则英文；中英混杂且占比在 [10%, 90%] 时打混合警告，提示可用 --provider 强制切换。优先级从高到低：--provider 显式指定 → --voice 是某 provider 的预设名则反推（同名冲突即报错，要求 --provider 明确）→ auto + 语种检测。
【内置音色预设】 MiniMax（中文，默认 model speech-2.8-hd）预设包括：lyrical（默认，抒情男声）、gentleman（温润男声）、radio_host（电台男主播）、executive（沉稳高管）、announcer（播报男声）、sincere（真诚青年男声）、news_anchor（新闻女声）、sweet_lady（甜美女声）、warm_bestie（温暖闺蜜女声）、wise_women（阅历姐姐女声）。MiniMax 系统音色总共约 300 个，可用 --list-remote-voices 查 voice_id 后加进 config.json。 ElevenLabs（英文，默认 model eleven_multilingual_v2）预设包括：rachel（默认，英文女声沉稳）、adam（英文男声深沉）、bella（英文女声年轻活泼）、antoni（英文男声温和）、domi（英文女声有力）、josh（英文男声年轻）。
【配置与凭证】 config.json 由 config.json.template 复制而来，含 API key，不要 commit。结构包含 default_output_dir、default_provider、language_routing 以及 providers.elevenlabs 和 providers.minimax 的 api_key、endpoint、default_voice、default_model、voices、voice_settings 等字段。只配一个 provider 也能跑，但建议两个都配。环境变量优先级高于 config.json，可用 ELEVENLABS_API_KEY、MINIMAX_API_KEY、MINIMAX_FALLBACK_API_KEY 覆盖。
【容错机制】 网络层同 key 重试：HTTP 5xx 与 URLError（DNS、超时、连接拒绝）走指数退避（2s → 4s）重试 2 次；4xx 不重试。MiniMax 双 key fallback 触发条件为严格白名单：HTTP 状态码 401 / 402 / 403 / 429，或业务状态码 1004 / 1008 / 1029 / 1039 / 2013 / 2049，满足任一即切到 fallback_keys 重试；其它错误（如 2039 文本审核）直接 fail。api_key 优先使用（推荐放更便宜的 key），fallback_keys 兜底（按量付费 key），两者不通用，必须配两个才能用 fallback。
【适用场景】 适合需要批量或长稿生成中文/英文口播、旁白、配音、朗读音频的场景，例如视频旁白、公众号文章转音频、产品介绍、新闻播报、商务 PPT 旁白等。
【限制与注意事项】 ElevenLabs 按字符计费，长文本前先 --dry-run；MiniMax 单次请求文本上限 10000 字符（脚本内取 9500 留 buffer，自动分段）；MiniMax 计费按 UTF-8 字节，1 个汉字约等于 2 字符；默认输出 ~/Desktop，可在 config.json 改 default_output_dir；已存在的输出文件默认不覆盖，需 --force。跨平台支持 Mac/Windows/Linux，零第三方依赖。
【来源参考】 ElevenLabs 文档：https://elevenlabs.io/docs/api-reference/text-to-speech MiniMax 文档：https://platform.minimaxi.com/docs/api-reference/speech-t2a-http.md MiniMax voice 列表：https://platform.minimaxi.com/docs/faq/system-voice-id.md