语音克隆技能

一种自初始化、零配置的语音克隆技能。它管理一个后台 TTS 守护进程，将重型模型权重常驻内存，以实现快速推理。支持多种引擎，并可处理任意长度的文本。

快速参考

何时使用该技能

• 用户发送语音备忘录或音频文件，而你需要以音频形式回复。
• 用户说“请朗读这段内容”、“跟我说话”、“用我的声音”、“语音模式”等类似指令。
• 对话上下文暗示预期回复为语音形式。
• 用户提供参考音频，并要求你模仿其声音。

分步使用说明

1. 确定输入项

你需要以下两项：

• ref_audio：用户参考音频文件（待克隆的声音）的本地绝对路径。通常为用户刚发送、并由 ASR 系统（例如 openai-whisper）保存的音频文件。
• text：你希望合成语音的文本内容。按常规方式生成即可——先构思你的回复，再将其转为语音文本。

2. 执行语音合成

执行如下命令：

bash scripts/run_tts.sh --text "你的回复文本内容。" --ref_audio "/absolute/path/to/reference.ogg"

可选参数：

• --speed 1.2 — 加快语速。取值范围：0.5 至 2.0；默认值：1.0。
• --output_dir "/tmp/" — 将生成的音频文件保存至指定的绝对目录路径。默认路径：server/generated_audio/。

含全部选项的示例：

bash scripts/run_tts.sh 
  --text "很高兴认识你，这是我克隆后的声音。" 
  --ref_audio "/tmp/user_voice_msg.ogg" 
  --speed 0.9

3. 处理输出结果

脚本将在 stdout 输出单行绝对路径（例如：/path/to/reply_a1b2c3d4.ogg）。 请使用附件格式将其附加到你的响应中：

MEDIA:/path/to/reply_a1b2c3d4.ogg

4. 重要约束条件

• 切勿手动启动 python app.py 或自行管理后端服务。run_tts.sh 脚本会自动检测、自动安装并自动启动全部依赖组件。
• 首次运行较慢（约 30–60 秒），因需下载模型权重并加载至内存；后续调用均为毫秒级响应。
• 长文本可自动处理。引擎将文本按句子切分，逐段合成，再无缝拼接，无长度限制。

控制语音特征

语速（所有引擎均支持）

--speed 参数用于调节语速：

F5-TTS 原生支持语速调节。其他引擎通过 ffmpeg 后处理（atempo 滤镜）实现，效果良好，但在极端数值下可能轻微影响音质。

情感与语气

这些模型依赖对参考音频进行声学特征提取——不支持接收基于文本的情感标签（如 [happy] 或 [sad]）。

输出语音的情感完全由参考音频决定。

如需控制语气，请选择或准备具备目标情绪特征的参考音频：

Agent 的实用做法：若用户已发送多条语音消息，请从中选择情感基调最贴合你回复语境的一条作为参考。若仅有一条可用，则直接使用——模型将尽力复现说话人的整体风格。

ChatTTS 特性说明：该引擎支持在文本中嵌入情感标签：[laugh]、[uv_break]（停顿）。当提供参考音频时，亦支持语音克隆功能。

可用引擎

切换引擎方法：在服务启动前设置环境变量：

export TTS_BACKEND=cosyvoice

卸载

# 彻底移除全部内容（虚拟环境、守护进程、技能注册）
bash scripts/uninstall.sh

# 仅移除某一引擎的源码
bash scripts/uninstall.sh --engine cosyvoice

# 彻底移除全部内容（含已下载的模型权重，数 GB）
bash scripts/uninstall.sh --purge

文件结构

scripts/
├── run_tts.sh              # 主入口脚本（自动修复、自动启动守护进程）
├── tts_client.py            # 与后端通信的 HTTP 客户端
├── auto_installer.sh        # 安装 F5-TTS（默认）并注册技能
├── install_cosyvoice.sh     # 安装 CosyVoice 引擎
├── install_chattts.sh       # 安装 ChatTTS 引擎
├── install_openvoice.sh     # 安装 OpenVoice 引擎
└── uninstall.sh             # 清理脚本
server/
├── app.py                   # FastAPI 守护进程（自动托管，切勿手动启动）
├── core_tts.py              # 多引擎工厂 + 长文本分块处理逻辑
└── requirements.txt         # 基础依赖项

参考资料

• 阅读 references/architecture.md 了解系统架构与设计原理。