tts

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

如果用户没有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）。代理也可以手动编写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	Joyful
77e15f2c	婉青｜情绪抚慰	zh	F	Calm
ac09aeb4	阿豪｜磁性主持	zh	M	Calm
87cb2405	建国｜知识科普	zh	M	Calm
3b9f1e27	小明｜科技达人	zh	M	Joyful
95814add	Science Narration	en	M	Calm
883b6b7c	The Mentor (Alex)	en	M	Joyful
a845c7de	The Naturalist (Silas)	en	M	Calm
5a68d66b	The Healer (Serena)	en	F	Calm
0e4ab6ec	The Mentor (Maya)	en	F	Calm

安全与数据披露

此技能在运行时执行以下文件和网络操作：

• 凭据存储：当您运行 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。