Coqui TTS 推理实战：tts 命令行、tts-server 与 Python TTS API 三入口完全指南

Coqui TTS 推理实战：tts 命令行、tts-server 与 Python TTS API 三入口完全指南

【免费下载链接】TTS🐸💬 - a deep learning toolkit for Text-to-Speech, battle-tested in research and production项目地址: https://gitcode.com/GitHub_Trending/tt/TTS

本文围绕 Coqui TTS 仓库中的推理文档（docs/source/inference.md）展开，系统讲解安装后的三大推理入口：tts命令行工具、tts-server本地演示服务器和from TTS.api import TTS的 Python API。读完本文，你将能够用发布模型或自训练模型完成文本转语音、多说话人/多语言合成、声音克隆与声音转换，并从源码层面理解Synthesizer、ModelManager等关键组件在幕后做了什么。

一、安装与三大入口总览

首先通过 PyPI 安装：

$ pip install TTS

安装完成后，仓库的 setup.py 中通过entry_points注册了两个终端命令：

entry_points={"console_scripts": ["tts=TTS.bin.synthesize:main", "tts-server = TTS.server.server:main"]}

因此tts命令实际指向 CLI 入口脚本，tts-server指向 演示服务器。加上 Python 接口，安装后共有三种推理方式：

1. 命令行接口（CLI）：tts
2. 本地演示服务器：tts-server
3. Python：from TTS.api import TTS

版本前提：当前仓库TTS/VERSION为 0.22.0；setup.py 明确限制了 Python 版本需满足>= 3.9 且 < 3.12，不满足时安装脚本会直接抛出RuntimeError。

二、命令行入口tts

2.1 列出与查询已发布模型

tts --list_models

模型元数据来自包内的模型注册表 TTS/.models.json，由 ModelManager 负责读取、检索和下载。CLI 还支持按名称或索引查询模型详情（这些信息在tts -h的帮助文本中有完整说明）：

# 按完整名称查询，格式 <model_type>/<language>/<dataset>/<model_name> tts --model_info_by_name "tts_models/tr/common-voice/glow-tts" tts --model_info_by_name "vocoder_models/en/ljspeech/hifigan_v2" # 按 --list_models 输出中的序号查询 tts --model_info_by_idx "tts_models/3"

2.2 运行发布模型

使用发布模型及其默认声码器（从列表中复制完整模型名即可）：

tts --text "Text for TTS" \ --model_name "<type>/<language>/<dataset>/<model_name>" \ --out_path folder/to/save/output.wav

同时指定 TTS 与声码器模型。注意：并非每个声码器都与每个 TTS 模型兼容：

tts --text "Text for TTS" \ --model_name "tts_models/<language>/<dataset>/<model_name>" \ --vocoder_name "vocoder_models/<language>/<dataset>/<model_name>" \ --out_path folder/to/save/output.wav

从 synthesize.py 的源码可以看到默认声码器的选择逻辑：当--model_name命中.models.json中的tts_models条目时，若该条目声明了default_vocoder且用户未显式指定--vocoder_name，则自动取条目中的default_vocoder字段下载：

if "default_vocoder" in model_item: args.vocoder_name = ( model_item["default_vocoder"] if args.vocoder_name is None else args.vocoder_name )

另外，不指定任何模型时 CLI 默认使用tts_models/en/ljspeech/tacotron2-DDC（synthesize.py 中--model_name的默认值），输出默认写到tts_output.wav。

2.3 运行自训练模型

只带 TTS 模型（无外部声码器时使用 Griffin-Lim 重建波形）：

tts --text "Text for TTS" \ --model_path path/to/model.pth \ --config_path path/to/config.json \ --out_path folder/to/save/output.wav

TTS 与声码器一起指定：

tts --text "Text for TTS" \ --config_path path/to/config.json \ --model_path path/to/model.pth \ --out_path folder/to/save/output.wav \ --vocoder_path path/to/vocoder.pth \ --vocoder_config_path path/to/vocoder_config.json

在 Synthesizer 中，“Griffin-Lim 兜底”是一个显式开关：use_gl = self.vocoder_model is None。只有当声码器未加载时，才在 TTS 模型侧用 Griffin-Lim 直接由 mel 谱还原波形；加载了声码器后，则走vocoder_model.inference(vocoder_input)的神经声码器路径。

2.4 多说话人模型

先列出该模型可用的说话人 ID，再指定目标说话人：

tts --model_name "tts_models/<language>/<dataset>/<model_name>" --list_speaker_idxs # 列出可用的说话人 ID tts --text "Text for TTS." --out_path output/path/speech.wav --model_name "tts_models/<language>/<dataset>/<model_name>" --speaker_idx "<speaker_id>"

实现上，--list_speaker_idxs会打印synthesizer.tts_model.speaker_manager.name_to_id映射（synthesize.py）；若使用多说话人模型却既未给--speaker_idx也未给--speaker_wav，CLI 会提示并直接退出，避免无声合成。

多语言模型可用--language_idx/--list_language_idxs做类似操作；此外 CLI 还支持--speaker_wav（可用多个文件，取平均 d-vector）、--gst_style、--capacitron_style_wav/--capacitron_style_text等条件参数，均定义在 synthesize.py 的参数表中。

2.5 声音转换（Voice Conversion）

运行已发布的 FreeVC 声音转换模型：

tts --model_name "voice_conversion/<language>/<dataset>/<model_name>" \ --source_wav "my/source/speaker/audio.wav" \ --target_wav "my/target/speaker/audio.wav" \ --out_path folder/to/save/output.wav

在 CLI 中，当model_item["model_type"] == "voice_conversion_models"时走synthesizer.voice_conversion(source_wav=..., target_wav=...)分支（synthesize.py），底层是 FreeVC 模型实现的voice_conversion方法。

2.6 管道输出与其他实用参数

帮助文本中还给出了把合成波形直接送进播放器的玩法：

tts --text "Text for TTS" --pipe_out --out_path output/path/speech.wav | aplay

--pipe_out对应 Synthesizer.save_wav 的pipe_out参数，将 wav 二进制数据写到 stdout。其他常用参数：--use_cuda/--device选择计算设备，--progress_bar控制下载进度条（默认开启），--save_spectogram保存原始频谱供后续处理，--reference_wav/--reference_speaker_idx用于以参考音频做音色迁移。

提示：如果偏好从 TTS 项目目录直接运行，可用./TTS/bin/synthesize.py替代tts命令。

三、演示服务器tts-server

tts-server -h # 查看帮助 tts-server --list_models # 列出可用模型

官方说明：演示服务器并非为性能优化而设计，它的价值在于提供一个与模型交互的简易 Web 界面。界面功能与 CLI 基本一致：

# 使用发布模型及其默认声码器启动服务器 tts-server --model_name "<type>/<language>/<dataset>/<model_name>"

若所选模型是多说话人 TTS 模型，可在 Web 界面中切换不同说话人再合成。同时指定声码器：

tts-server --model_name "<type>/<language>/<dataset>/<model_name>" \ --vocoder_name "<type>/<language>/<dataset>/<model_name>"

从源码结构看，tts-server入口是 TTS/server/server.py，页面模板位于 TTS/server/templates/index.html 与 details.html，运行示例另见 TTS/server/README.md（其中还给出--use_cuda True的 GPU 启动方式，以及用--tts_checkpoint/--tts_config/--vocoder_checkpoint/--vocoder_config加载自训练模型的写法）。

四、Python API：TTS.api.TTS

Python 入口是 TTS/api.py 中的TTS类（继承自nn.Module），它是 Synthesizer 与 ModelManager 的薄封装。

4.1 构造参数

TTS(...)的签名与语义（摘自 api.py 的 docstring）：

构造函数中的路由逻辑（api.py）：

if model_name is not None and len(model_name) > 0: if "tts_models" in model_name: self.load_tts_model_by_name(model_name, gpu) elif "voice_conversion_models" in model_name: self.load_vc_model_by_name(model_name, gpu) else: self.load_model_by_name(model_name, gpu)

按名称加载时，download_model_by_name会先经ModelManager.download_model拉取模型文件；若条目声明了default_vocoder，会连带下载默认声码器（api.py）。对 Fairseq 这类多文件目录模型，则返回model_dir并交由模型自身从目录加载。

4.2 多语言声音克隆模型（XTTS v2）

import torch from TTS.api import TTS # 获取设备 device = "cuda" if torch.cuda.is_available() else "cpu" # 列出可用模型 print(TTS().list_models()) # 初始化 TTS tts = TTS("tts_models/multilingual/multi-dataset/xtts_v2").to(device) # 运行 TTS # 由于这是多语言声音克隆模型，必须提供目标 speaker_wav 和 language # 输出为振幅值列表 wav = tts.tts(text="Hello world!", speaker_wav="my/cloning/audio.wav", language="en") # 直接写入文件 tts.tts_to_file(text="Hello world!", speaker_wav="my/cloning/audio.wav", language="en", file_path="output.wav")

模型是否为多说话人/多语言可通过属性判断，它们分别对应 api.py 中的is_multi_speaker、is_multi_lingual，并从speaker_manager/language_manager读取tts.speakers、tts.languages。

4.3 单说话人模型

# 以目标模型名初始化 tts = TTS(model_name="tts_models/de/thorsten/tacotron2-DDC", progress_bar=False) # 运行 TTS tts.tts_to_file(text="Ich bin eine Testnachricht.", file_path=OUTPUT_PATH)

4.4 多语言声音克隆（YourTTS：英/法/葡）

tts = TTS(model_name="tts_models/multilingual/multi-dataset/your_tts", progress_bar=False).to("cuda") tts.tts_to_file("This is voice cloning.", speaker_wav="my/cloning/audio.wav", language="en", file_path="output.wav") tts.tts_to_file("C'est le clonage de la voix.", speaker_wav="my/cloning/audio.wav", language="fr", file_path="output.wav") tts.tts_to_file("Isso é clonagem de voz.", speaker_wav="my/cloning/audio.wav", language="pt", file_path="output.wav")

4.5 声音转换与“TTS + VC 伪克隆”

用 FreeVC 把source_wav的说话人转换为target_wav的说话人：

tts = TTS(model_name="voice_conversion_models/multilingual/vctk/freevc24", progress_bar=False).to("cuda") tts.voice_conversion_to_file(source_wav="my/source.wav", target_wav="my/target.wav", file_path="output.wav")

用任意单说话人 TTS 模型 + 声音转换模型组合实现克隆（“this way, you can clone voices by using any model in TTS”）：

tts = TTS("tts_models/de/thorsten/tacotron2-DDC") tts.tts_with_vc_to_file( "Wie sage ich auf Italienisch, dass ich dich liebe?", speaker_wav="target/speaker.wav", file_path="output.wav" )

从源码看，tts_with_vc 的流程是：先把文本合成到临时 wav（tempfile.NamedTemporaryFile），若尚未加载声音转换模型则自动加载voice_conversion_models/multilingual/vctk/freevc24，再调用voice_converter.voice_conversion(source_wav=临时文件, target_wav=speaker_wav)。也就是说上述示例无需显式加载 FreeVC，API 会按需补载。

4.6 Fairseq 模型：约 1100 种语言

Fairseq 模型的名称格式为tts_models/<lang-iso_code>/fairseq/vits，语言 ISO 代码清单可在包内模型注册表 TTS/.models.json 及源码注释（api.py）中查阅。示例：

from TTS.api import TTS api = TTS(model_name="tts_models/eng/fairseq/vits").to("cuda") api.tts_to_file("This is a test.", file_path="output.wav") # 在线（on the fly）声音转换 api = TTS("tts_models/deu/fairseq/vits") api.tts_with_vc_to_file( "Wie sage ich auf Italienisch, dass ich dich liebe?", speaker_wav="target/speaker.wav", file_path="output.wav" )

加载链路在 Synthesizer 中按model_dir处理：路径含fairseq时调用_load_fairseq_from_dir，内部以VitsConfig构造 VITS 并执行load_fairseq_checkpoint(checkpoint_dir=model_dir)（synthesizer.py）。

4.7 参数校验：_check_arguments

tts/tts_to_file在真正合成前都会先执行 _check_arguments，常见报错来自这些硬性规则：

• 多说话人模型必须提供speaker或speaker_wav，否则抛出ValueError；
• 多语言模型必须提供language；
• 单说话人/单语言模型却传入speaker/language也会报错（Tortoise 的voice_dir情形除外）；
• emotion与speed只能同时用于已停服的 Coqui Studio 模型，二者同时非空会直接抛错。

这些校验帮助你在调用阶段（而非合成中途）就发现参数与模型能力不匹配的问题。

五、底层实现：Synthesizer 的推理管线

无论 CLI、服务器还是 Python API，最终都汇聚到 Synthesizer.tts。理解它有助于排查实际合成中的行为：

1. 分句合成：输入文本默认经pysbd.Segmenter(language="en", clean=True)切成句子，逐句合成后拼接；split_sentences=False会一次性送入整段文本——官方注释提醒这会消耗更多 VRAM 并可能触碰模型文本长度或显存上限（api.py）。
2. 说话人/语言解析：多说话人模型按name_to_id把speaker_name映射为 speaker id，或从speaker_wav用 speaker encoder 现场计算 d-vector（compute_embedding_from_clip）；多语言模型同理走language_manager.name_to_id，语言名不存在时会明确列出可用语言。
3. 声码器衔接：TTS 输出的 mel 谱先按 TTS 音频配置反归一化，再按声码器配置重新归一化；若两者采样率不一致还会打印> interpolating tts model output.并做插值（synthesizer.py）。
4. 静音修剪与性能统计：配置开启do_trim_silence时自动裁剪首尾静音；每次合成结束打印处理耗时与实时率：> Real-time factor: {process_time / audio_time}，这是评估某模型/设备推理速度的直接依据。
5. 模型下载与缓存：ModelManager.download_model（manage.py）按.models.json条目下载并本地缓存，含 GitHub / HuggingFace 两种下载通道；CLI 与 Python API 共用同一注册表 TTS/.models.json，其中tts_models、vocoder_models、voice_conversion_models三大类型与文档中的<type>/<language>/<dataset>/<model_name>命名格式一一对应。

六、小结与适用边界

• 命令选择建议：脚本化/批量任务用ttsCLI（配合--list_models、--model_info_by_name检索模型）；交互式试听用tts-server；工程集成用TTS.api.TTS，尤其是声音克隆（speaker_wav）与 TTS+VC 组合场景。
• 兼容性约束：声码器与 TTS 模型并非两两兼容；Fairseq 多文件模型只能按tts_models/<lang-iso>/fairseq/vits名称加载；Python 环境需落在 3.9~3.11 区间。
• 延伸阅读：本文所有示例均以当前仓库（版本 0.22.0）源码为准，进一步实现细节可对照 TTS/api.py、TTS/bin/synthesize.py、TTS/utils/synthesizer.py、TTS/utils/manage.py 与 TTS/server/README.md；推理相关的回归测试位于 tests/inference_tests/test_synthesizer.py 和 tests/inference_tests/test_synthesize.py。

【免费下载链接】TTS🐸💬 - a deep learning toolkit for Text-to-Speech, battle-tested in research and production项目地址: https://gitcode.com/GitHub_Trending/tt/TTS