Chatterbox 开源语音合成快速上手指南从零到多语言 TTS 实战【免费下载链接】chatterboxSoTA open-source TTS项目地址: https://gitcode.com/GitHub_Trending/chatterbox7/chatterboxChatterbox 是 Resemble AI 开源的语音合成模型家族覆盖多语言 TTS、零样本语音克隆与低延迟实时合成三类需求。本文带你完成安装、跑通第一条语音并拆清每个模型的参数默认值与适用边界。读完之后你能独立选型并用几行代码生成带克隆音色的多语言音频不用再靠示例文件猜参数。️ 装好环境两条安装路径先说结论Python 用 3.11 最稳依赖已在 pyproject.toml 里钉死照装即可。项目官方在 Python 3.11Debian 11上开发测试torch锁 2.6.0transformers锁 5.2.0混版本容易崩。两条路径任选其一。# 方式一包管理器最快 pip install chatterbox-tts# 方式二源码安装便于改依赖 conda create -yn chatterbox python3.11 conda activate chatterbox git clone https://gitcode.com/GitHub_Trending/chatterbox7/chatterbox cd chatterbox pip install -e .一行验证能 import 就算成功python -c import chatterbox; print(ok)小贴士首次运行from_pretrained会从 HuggingFace 拉模型权重Turbo 约 350M、多语言约 500M。国内网络建议先配好镜像或HF_TOKEN否则下载步骤会卡住。 5 行代码出第一个声音这条示例放在所有讲解之前目的只有一个让你最快听到声音。用原版ChatterboxTTS不传参考音时走内置音色无需准备音频文件。import torchaudio as ta from chatterbox.tts import ChatterboxTTS model ChatterboxTTS.from_pretrained(devicecuda) # 也可 cpu / mps text Welcome to Chatterbox, an open-source text to speech model. wav model.generate(text) # 返回 1 维张量 ta.save(first.wav, wav, model.sr) # model.sr 是采样率跑通这一步你会看到终端无报错当前目录多出first.wav用播放器打开是一段英文朗读。设备不支持 GPU 就把device改成cpu速度慢但不影响出结果。 三大核心能力拆解零样本语音克隆3 秒音频复刻音色它能做什么给一段参考语音把任意文本用该音色念出来不用训练。依据在prepare_conditionals——参考音会被切成说话人嵌入和语音 token 提示长度上限由DEC_COND_LEN 10 * S3GEN_SR控制所以取 3~10 秒最稳。import torchaudio as ta from chatterbox.tts import ChatterboxTTS model ChatterboxTTS.from_pretrained(devicecuda) wav model.generate( 你好这是我克隆出来的声音。, audio_prompt_pathreference.wav, # 传入即启用克隆 exaggeration0.5, # 情感夸张度 cfg_weight0.5, # 条件引导强度 ) ta.save(clone.wav, wav, model.sr)参数默认作用audio_prompt_pathNone参考音频传入即启用克隆exaggeration0.5情感夸张度0.7更戏剧化cfg_weight0.5条件引导降到0可减少口音残留temperature0.8采样随机性多语言 TTS一个模型切换 23 种语言它能做什么同一个对象改language_id就换语种无需重载模型。依据是mtl_tts.py里的SUPPORTED_LANGUAGES共 23 项覆盖中文、日文、法文等。多语言版language_id是必传参数传错会直接抛ValueError。import torchaudio as ta from chatterbox.mtl_tts import ChatterboxMultilingualTTS # t3_modelv3 用最新检查点不传默认 v2 model ChatterboxMultilingualTTS.from_pretrained( devicecuda, t3_modelv3 ) wav_zh model.generate(你好欢迎使用多语言语音合成。, language_idzh) wav_ja model.generate(こんにちは、多言語音声合成のテストです。, language_idja) ta.save(zh.wav, wav_zh, model.sr)常用语言代码zh中文、ja日文、en英文、ko韩文、fr法文、de德文、es西文、ru俄文、ar阿文、hi印地文、tr土耳其文等完整 23 项见SUPPORTED_LANGUAGES。Turbo 低延迟合成副语言标签让语气更真实它能做什么英文低延迟场景更快并原生支持[laugh]、[chuckle]、[cough]这类副语言标签。依据是tts_turbo.py用S3Gen(meanflowTrue)且n_cfm_timesteps2把解码从 10 步压到一步显存占用更低。Nano110M与 Turbo 同类传nanoTrue即可8 核 CPU 能跑到 3 倍实时。Turbo 采用单步解码配合副语言标签面向低延迟语音助手场景。import torchaudio as ta from chatterbox.tts_turbo import ChatterboxTurboTTS model ChatterboxTurboTTS.from_pretrained(devicecuda) # 副语言标签让语气更真实[laugh] [chuckle] [cough] text Hi there [chuckle], have you got one minute to chat? # 参考音需 5 秒否则 assert 报错不传则用内置音色 wav model.generate(text) ta.save(turbo.wav, wav, model.sr)项目说明副语言标签[laugh][chuckle][cough]原生支持参考音时长必须5秒否则触发断言cfg_weight/exaggeration不被支持传了会被忽略并告警解码步数单步对比原版 10 步速度更快 三个落地场景多语言客服回复需求同一套客服话术按客户语种各生成一条语音。replies { zh: 您好有什么可以帮您, en: Hello, how can I help you?, ja: こんにちは、ご用件は何ですか, } for lang, text in replies.items(): wav model.generate(text, language_idlang) ta.save(freply_{lang}.wav, wav, model.sr)可继续扩展接一个语种识别接口根据用户输入动态决定language_id再生成对应回复。批量有声内容生成需求把分好的章节文本一次性转成音频文件。articles [第一章 引言……, 第二章 背景……, 第三章 方法……] for i, text in enumerate(articles): wav model.generate(text, language_idzh, cfg_weight0.5) ta.save(fchapter_{i}.wav, wav, model.sr)可继续扩展长文按句号切段、逐段生成再拼接避免单次文本过长。声音克隆应用需求把一段已有录音换成目标人物的音色用于虚拟主播。import torchaudio as ta from chatterbox.vc import ChatterboxVC model ChatterboxVC.from_pretrained(cuda) wav model.generate( audioinput.wav, # 原始录音 target_voice_pathtarget.wav, # 目标音色 ) ta.save(vc_out.wav, wav, model.sr)可继续扩展缓存set_target_voice提取的ref_dict多个输入共用同一目标音色省去重复编码。⚙️ 模型选型与参数调优先选型。五个模型参数、语言、用途如下数据来自 README 的 Model Zoo。模型参数量语言核心特性适用场景Chatterbox-Turbo350M英语副语言标签、低显存、单步解码低延迟语音助手、生产环境Chatterbox-Nano110M英语同 Turbo 架构8 核 CPU 3 倍实时端侧 / CPU、紧预算Chatterbox-Multilingual V3500M23说话人相似度更高、幻觉更少全球化、本地化、跨语言克隆Single Language Pack500M×66 项专项语言 / 地区方言质量控制重点语言、方言敏感Chatterbox原版500M英语CFG 与 exaggeration 可调通用零样本 TTS、创意控制再调参。以下默认值与区间取自官方 Tips仅对原版与多语言生效Turbo/Nano 会忽略这些参数。场景cfg_weightexaggeration效果通用 / 日常0.50.5官方默认多数语言适用戏剧化表达~0.30.7更富表现力语速偏快参考音语速快~0.30.5放慢节奏、更从容跨语言口音残留00.5避免继承参考音语言口音 高频问题避坑问题原因解法CUDA 显存不足500M 模型 长文本换 Turbo/Nano或devicecpuMac 报 MPS 错误PyTorch 未开 MPS 或系统过旧参考 example_for_mac.py回退mps/cpuTurbo 传参考音报错参考音不足 5 秒换成5秒的清晰语音克隆音带原语言口音参考音与目标语言不符设cfg_weight0或换同语言参考音权重下载崩溃(xet)HF 存储后端异常Turbo/Nano 类已自动降级重试生成速度慢走的是 CPU 推理优先 GPUNano 在 8 核 CPU 可达 3 倍实时 进阶技巧技巧一批量生成用线程池。import concurrent.futures texts [第一句, 第二句, 第三句] def run(t): return model.generate(t, language_idzh) with concurrent.futures.ThreadPoolExecutor() as ex: wavs list(ex.map(run, texts)) # 逐条落盘技巧二用完整释放显存。import torch model ChatterboxTTS.from_pretrained(devicecuda) wav model.generate(测试) ta.save(t.wav, wav, model.sr) del model # 删除模型引用 torch.cuda.empty_cache() # 清空缓存显存技巧三异常兜底避免单条失败中断整批。try: wav model.generate(text, language_idlang) except ValueError as e: # 语言代码错误等 print(f重试默认参数: {e}) wav model.generate(text) # 去掉语言标签兜底 except Exception as e: # 其它异常降级朗读 wav model.generate(合成失败请稍后重试。) 一页速查核心源码路径src/chatterbox/tts.py原版ChatterboxTTSsrc/chatterbox/mtl_tts.py多语言ChatterboxMultilingualTTSsrc/chatterbox/tts_turbo.pyTurbo / Nanosrc/chatterbox/vc.py语音转换ChatterboxVCsrc/chatterbox/models/T3、S3Gen、声码器常用命令pip install chatterbox-tts # 安装 python example_tts.py # 基础 多语言示例 python example_vc.py # 语音转换示例 python gradio_tts_app.py # 启动 Web 界面关键参数参数类型默认值说明devicestrcuda设备cuda/mps/cput3_modelstrv2多语言检查点v2/v3language_idstr无语言代码多语言必传audio_prompt_pathstrNone参考音频启用克隆exaggerationfloat0.5情感夸张度cfg_weightfloat0.5条件引导强度nanoboolFalse用 Nano(110M) 替代 Turbo下一步运行 example_tts.py再对照 example_vc.py 与 example_tts_turbo.py把你自己的参考音接进去。【免费下载链接】chatterboxSoTA open-source TTS项目地址: https://gitcode.com/GitHub_Trending/chatterbox7/chatterbox创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考