音色与 TTS¶
音色与 TTS 决定数字人“说话”的声音。OpenTalking 支持通过不同 TTS Provider 合成语音，并在 WebUI 中选择、试听和使用音色。
你将完成什么¶
本页会说明：
- 如何理解 TTS Provider 和音色。
- 如何使用默认音色开始验证。
- 如何在 WebUI 中切换和试听音色。
- 如何使用 DashScope / Qwen 或 CosyVoice 进行声音复刻。
- 声音不可用、试听失败或复刻失败时如何排查。
TTS Provider 选择¶
TTS Provider 是实际合成语音的服务或模型。不同 Provider 的配置方式、音色标识和延迟表现不同。
常见选择：
edge：适合快速验证，使用成本低。dashscope/qwen：适合使用百炼 / 通义相关 TTS 能力。cosyvoice：适合接入 CosyVoice 音色和声音复刻能力。sambert：适合兼容已有 Sambert 配置的场景。
如果你只是第一次跑通流程，先使用默认 Provider 和默认音色。需要业务化声音时，再配置云端 Provider 或声音复刻。
使用默认音色¶
启动 Mock 或本地服务后，WebUI 通常会显示一组可用音色。选择默认项即可创建会话。
默认音色适合验证：
- 会话是否能创建。
- TTS 是否能返回音频。
- 数字人画面和音频是否同步。
- 字幕和回复是否正常展示。
切换音色¶
在 WebUI 设置区选择 TTS Provider 和 voice。切换后，新的回复会使用新音色；已经生成的音频不会重新合成。
建议切换音色后用短句测试：
如果 voice 标识填写错误，TTS Provider 可能返回音色不存在、参数无效或鉴权失败。
试听音色¶
WebUI 支持在创建会话前试听音色。试听文本建议控制在较短范围内，当前预览接口最多处理 240 个字符。
试听失败时，先检查 Provider Key、网络访问和 voice 标识，再查看后端日志。
声音复刻¶
声音复刻用于根据一段样本音频创建新的 voice。当前 WebUI 中支持的复刻入口主要面向 DashScope / Qwen 和 CosyVoice。
准备样本音频¶
建议样本音频满足：
- 人声清晰，背景噪声低。
- 单人说话，避免多人重叠。
- 语速自然，不要过快或过慢。
- 文件不超过当前上传限制。WebUI 复刻音频上传上限为 12MB。
WebUI 会使用固定样本文本辅助复刻流程：
DashScope / Qwen¶
DashScope / Qwen 路径通常依赖 Provider Key。配置成功后，可以在 WebUI 上传样本音频并生成 voice id。
生成后，把新 voice 应用到当前会话，再通过试听或短文本验证声音效果。
CosyVoice¶
CosyVoice 复刻通常需要服务端能够访问样本音频地址。部署在本机时，如果外部服务无法访问本机地址，需要配置可公开访问的 OPENTALKING_PUBLIC_BASE_URL。
如果复刻请求失败，优先检查公开访问地址、文件上传、Provider 服务状态和后端日志。
在 WebUI 中使用音色¶
- 选择 TTS Provider。
- 选择已有 voice，或通过声音复刻创建新 voice。
- 点击试听，确认声音可用。
- 创建或重建会话。
- 输入短文本验证数字人回复。
如果你已经创建了会话，但之后切换了音色，建议重建会话以减少状态混淆。
常见问题¶
试听没有声音¶
检查浏览器是否静音、页面是否允许播放音频、Provider Key 是否配置正确，以及后端是否返回了音频。
复刻成功但列表里看不到新音色¶
刷新音色列表或刷新页面。仍然没有时，检查后端 voice store 是否正常写入。
CosyVoice 复刻失败¶
确认样本音频能被服务端访问。如果使用云端 CosyVoice，而样本音频只存在于本机临时地址，云端服务可能无法下载。
声音和口型不同步¶
先用短文本确认 TTS 音频时长是否正常，再检查模型推理延迟和浏览器播放状态。长文本、网络 TTS 延迟和低性能设备都会影响同步体验。
参考：配置参考¶
常见相关配置包括：
- Provider Key：不同 TTS 服务需要不同环境变量。
OPENTALKING_PUBLIC_BASE_URL：供外部服务访问上传音频或静态资源。- 默认 TTS Provider / voice：可在后续配置参考中统一整理。
完整配置项会在参考资料中继续补充。