tts 是做什么的？
将任何文本转换为语音音频。支持两种后端（Kokoro 本地、Noiz 云端）、两种模式（简单或时间轴精确）、以及按片段控制语音。
触发条件
- 文本转语音 / tts / 朗读 / 说出
- 语音克隆 / 配音
- epub 转音频 / srt 转音频 / 转换为音频
- 语音 / 说 / 讲 / 说话
简单模式 — 文本转音频
speak 是默认子命令，可以省略：
# 基本用法（speak 可省略）
python3 skills/tts/scripts/tts.py -t "Hello world" # 添加 -o 路径以保存
python3 skills/tts/scripts/tts.py -f article.txt -o out.mp3
# 语音克隆 — 本地文件路径或 URL
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio ./ref.wav
python3 skills/tts/scripts/tts.py -t "Hello" --ref-audio https://example.com/my_voice.wav -o clone.wav
# 语音消息格式
python3 skills/tts/scripts/tts.py -t "Hello" --format opus -o voice.opus
python3 skills/tts/scripts/tts.py -t "Hello" --format ogg -o voice.ogg
第三方集成（飞书/Telegram/Discord）请参见 ref_3rd_party.md。
时间轴模式 — SRT 到时间对齐音频
用于精确的逐片段定时（配音、字幕、视频旁白）。
步骤 1：获取或创建 SRT
如果用户没有，可以从文本生成：
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt
python3 skills/tts/scripts/tts.py to-srt -i article.txt -o article.srt --cps 15 --gap 500
--cps = 每秒字符数（中文默认 4；英文约 15）。Agent 也可以手动编写 SRT。
步骤 2：创建语音映射
JSON 文件，控制默认及每个片段的语音设置。segments 的键支持单个索引 "3" 或范围 "5-8"。
Kokoro 语音映射：
{
"default": { "voice": "zf_xiaoni", "lang": "cmn" },
"segments": {
"1": { "voice": "zm_yunxi" },
"5-8": { "voice": "af_sarah", "lang": "en-us", "speed": 0.9 }
}
}
Noiz 语音映射（增加了 emo、reference_audio 支持）。reference_audio 可以是本地路径或 URL（用户自己的音频；仅 Noiz）：
{
"default": { "voice_id": "voice_123", "target_lang": "zh" },
"segments": {
"1": { "voice_id": "voice_host", "emo": { "Joy": 0.6 } },
"2-4": { "reference_audio": "./refs/guest.wav" }
}
}
动态参考音频切片：
如果正在翻译或配音视频，并且希望每个句子自动使用原始视频中相同时间戳的音频作为参考音频，请使用 --ref-audio-track 参数，而不是在映射中设置 reference_audio：
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --ref-audio-track original_video.mp4 -o output.wav
完整的示例请参见 examples/。
步骤 3：渲染
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json -o output.wav
python3 skills/tts/scripts/tts.py render --srt input.srt --voice-map vm.json --backend noiz --auto-emotion -o output.wav
何时选择哪种后端
| 需求 | 推荐后端 |
|---|---|
| 只是朗读文本，不搞复杂 | Kokoro（默认） |
| EPUB/PDF 有声书带章节 | Kokoro（原生支持） |
语音混合（"v1:60,v2:40"） | Kokoro |
| 从参考音频进行语音克隆 | Noiz |
情绪控制（emo 参数） | Noiz |
| 精确的服务端每片段时长 | Noiz |
当用户需要同时具备情绪控制 + 语音克隆 + 精确时长时，Noiz 是唯一支持这三者的后端。
访客模式（无需 API 密钥）
当未配置 API 密钥时，tts.py 自动回退到 访客模式 —— 一个无需认证的有限 Noiz 端点。访客模式仅支持 --voice-id、--speed 和 --format；语音克隆、情绪、时长和时间轴渲染不可用。
# 访客模式（未设置 API 密钥时自动检测）
python3 skills/tts/scripts/tts.py -t "Hello" --voice-id 883b6b7c -o hello.wav
# 显式切换后端为 kokoro
python3 skills/tts/scripts/tts.py -t "Hello" --backend kokoro
可用的访客语音（15 种内置）：
| voice_id | 名称 | 语言 | 性别 | 语调 |
|---|---|---|---|---|
063a4491 | 販売員（なおみ） | ja | F | 喜び |
4252b9c8 | 落ち着いた女性 | ja | F | 穏やか |
578b4be2 | 熱血漢（たける） | ja | M | 怒り |
a9249ce7 | 安らぎ（みなと） | ja | M | 穏やか |
f00e45a1 | 旅人（かいと） | ja | M | 穏やか |
b4775100 | 悦悦｜社交分享 | zh | F | 喜悦 |
77e15f2c | 婉青｜情绪抚慰 | zh | F | 平静 |
ac09aeb4 | 阿豪｜磁性主持 | zh | M | 平静 |
87cb2405 | 建国｜知识科普 | zh | M | 平静 |
3b9f1e27 | 小明｜科技达人 | zh | M | 喜悦 |
95814add | Science Narration | en | M | 平静 |
883b6b7c | The Mentor (Alex) | en | M | 喜悦 |
a845c7de | The Naturalist (Silas) | en | M | 平静 |
5a68d66b | The Healer (Serena) | en | F | 平静 |
0e4ab6ec | The Mentor (Maya) | en | F | 平静 |
安全与数据披露
此技能在运行时执行以下文件和网络操作：
- 凭据存储：当您运行
config --set-api-key时，密钥将保存到~/.config/noiz/api_key（权限0600）。也支持使用NOIZ_API_KEY环境变量作为替代。 - 旧密钥迁移：如果
~/.noiz_api_key存在而~/.config/noiz/api_key不存在，密钥将被复制（而非删除）到新位置。会打印一条消息；旧文件保持不变，供您手动删除。 - 网络调用（Noiz 后端）：文本和可选的参考音频会上传到
https://noiz.ai/v1/进行合成。除非您调用 Noiz 命令，否则不会发送任何数据。 - 参考音频下载：当
--ref-audio是 URL 时，文件会被下载到临时文件，用于 API 调用，然后删除。如果未提供 voice-id 或 ref-audio，则会从storage.googleapis.com或noiz.ai下载默认参考音频。 - 临时文件：合成过程中可能会创建临时音频/文本文件，并在使用后清理。
- ffmpeg：仅在时间轴
render模式下调用，以组装最终音频。
不会修改输出路径和 ~/.config/noiz/ 以外的文件。Kokoro 后端完全离线运行，无网络访问。
要求
ffmpeg在 PATH 中（仅时间轴模式）requests包：uv pip install requests（Noiz 后端必需）- 在 Noiz Developer 获取您的 API 密钥，然后运行
python3 skills/tts/scripts/tts.py config --set-api-key YOUR_KEY（访客模式无需密钥即可工作，但功能有限） - Kokoro：如果已安装，传递
--backend kokoro以使用本地后端
Noiz API 认证
仅使用 base64 编码的 API 密钥作为 Authorization——无前缀（例如不带 APIKEY 或 Bearer ）。任何前缀都会导致 401。
关于后端详情和完整参数参考，请参见 reference.md。