MeloTTS · 多语言多口音轻量文本转语音库 · 中文部署与使用全指南

项目仓库： https://github.com/myshell-ai/MeloTTS

开源协议：MIT License（源码免费用于商业与非商业用途） · 开发语言：Python（基于 PyTorch） · 开发测试环境：Ubuntu 20.04 + Python 3.9 · 容器化：仓库自带 Dockerfile · WebUI 端口：Docker 映射 8888，本地 Gradio 默认 7860（可用 --port 指定） · 推理设备：CPU 即可实时推理，可选 CUDA / MPS 加速

1 项目简介

MeloTTS 是由 MIT 与 MyShell.ai 联合发布的高质量多语言、多口音文本转语音（Text-to-Speech, TTS）库。它在一套模型框架内支持英语（多种口音）、西班牙语、法语、中文、日语与韩语，其中中文音色支持中英混读；官方 README 明确说明模型在 CPU 上即可满足实时推理速度，同时也可以在有 NVIDIA GPU 或 Apple Silicon（MPS）的机器上自动切换到加速设备。

项目实现基于 Coqui TTS、VITS、VITS2 与 Bert-VITS2 的相关工作。作者为清华大学 Wenliang Zhao、清华大学 Xumin Yu，以及 MIT 与 MyShell 的项目负责人 Zengyi Qin。

非官方声明：MeloTTS 是开源研究项目，本文仅依据官方 README、docs/install.md、docs/quick_use.md、docs/training.md 与仓库源码整理部署步骤；模型在各语言上的发音质量、口音表现以官方示例音频与实际合成结果为准。项目内置音色为模型自带的固定说话人，不支持上传任意参考音频进行音色克隆；如需声音克隆能力，请另行选择专门的语音克隆项目。

1.1 核心信息一览

1.2 适用场景

• 需要在本地或自有服务器上把多语言文本批量转成语音，例如有声书、视频旁白、字幕配音、客服话术试听等。
• 希望在没有独立显卡的普通电脑或 CPU 服务器上完成实时语音合成，降低部署硬件门槛。
• 英语内容需要区分美式、英式、印度、澳大利亚等口音，通过同一套工具切换说话人。
• 中文文稿中夹杂英文单词（如 "machine learning"、"artificial intelligence"），希望由中文音色连贯读出。
• 开发者需要把 TTS 能力嵌入自己的 Python 脚本或应用，通过 Python API 传入文本、说话人、语速并输出 WAV 文件。
• 有定制数据集训练需求时，使用仓库自带的预处理与训练脚本训练自己的模型（见第 7.4 节与官方 docs/training.md）。

1.3 能力边界（官方口径）

• 语言范围：官方 README 列出的支持语言为英语（American / British / Indian / Australian / Default）、Spanish、French、Chinese（mix EN）、Japanese、Korean；未列出的语言不在官方支持范围内。
• 中文混读：中文说话人支持中英混读；代码内部中文模型标识为 ZH_MIX_EN。
• 说话人范围：多说话人选择仅对英语生效；docs/install.md 明确英语可用说话人为 EN-Default、EN-US、EN-BR、EN_INDIA、EN-AU，其余语言使用模型自带的默认说话人，CLI 传入 --speaker 时会给出"仅英语有效"的警告。
• 设备口径：官方文档写明 CPU 足以进行实时推理；device='auto' 时在检测到 CUDA 可用时使用 cuda，检测到 MPS 可用时使用 mps，否则使用 cpu。
• 不提供的能力：MeloTTS 不提供参考音频音色克隆、情感参数调节、说话人录音上传；合成语速可通过 speed 参数调节，但不支持官方未列出的情绪、停顿精细控制。
• 官方未在 README 中给出各语言模型的精确显存占用与最低内存数值，硬件余量请结合实际加载日志判断，以官方仓库最新说明为准。

2 功能特性

2.1 多语言与多口音合成

• 英语多口音：内置美式（EN-US）、英式（EN-BR）、印度英语（EN_INDIA）、澳大利亚英语（EN-AU）与默认口音（EN-Default），通过说话人 ID 切换。
• 西 / 法 / 日 / 韩：分别通过语言代码 ES、FR、JP、KR 加载对应模型。
• 中文中英混读：中文模型（ZH，内部 ZH_MIX_EN）可在同一段中文文本中读出夹杂的英文词汇。

2.2 三种使用入口

• Gradio WebUI：melo-ui 启动浏览器界面，可选择语言、说话人、输入文本、调节语速并试听下载；WebUI 启动时会一次性加载英语、西语、法语、中文、日语、韩语六个模型。
• 命令行 CLI：melo / melotts 一条命令把文本或文本文件合成为 WAV，适合脚本化批量处理。
• Python API：melo.api.TTS 类供程序调用，可指定语言、设备、说话人与语速，输出到文件或内存字节流。

2.3 设备自适应与语速控制

• 设备自动选择：device='auto' 自动探测 cuda、mps、cpu；也可显式指定 cpu、cuda、cuda:0、mps。
• 语速可调：CLI、WebUI 与 Python API 均提供 speed 参数，默认 1.0，可加快或放慢合成语速。
• CPU 实时：官方 README 标注模型在 CPU 上足够快，可用于实时推理。

2.4 模型自动下载与本地训练支持

• 权重自动获取：首次按语言加载模型时，配置文件与检查点从 Hugging Face 官方模型仓库 myshell-ai/* 及官方 S3 托管地址下载；melo/init_downloads.py 可在部署阶段预先把六个语言模型全部下载到位。
• 自定义训练：docs/training.md 给出数据集准备、元数据格式、文本预处理、训练脚本与推理脚本流程，可在自有数据集上训练（训练对 GPU 的要求以官方 docs/training.md 与仓库最新说明为准）。

3 官方界面预览

仓库 README 与 docs/ 目录随附的官方素材仅为项目标识 logo（见开篇图 1），未随附 WebUI 界面截图，因此本节不展示非官方截图。本地或 Docker 启动 melo-ui 后，Gradio 界面包含：语言下拉框、说话人下拉框、文本输入框、语速控制与试听 / 音频输出区域；切换语言时说话人列表会同步刷新为该语言可用的说话人。界面具体布局以本地实际启动版本为准。

4 官方跳转链接汇总

下表列出项目相关的官方入口，均可直接点击访问。

5 前置要求与服务器配置

5.1 软件前提

• 操作系统：官方在 Ubuntu 20.04 上开发与测试；Linux、macOS、Windows 均可通过 Docker 方式运行。源码方式在 macOS 上若遇到安装兼容问题，官方建议改用 Docker 安装。
• Python：源码方式对应 Python 3.9（Dockerfile 基础镜像为 python:3.9-slim）；其他 Python 版本下依赖版本（如 transformers==4.27.4、librosa==0.9.1）的兼容性以官方仓库最新说明为准。
• PyTorch / torchaudio：由 requirements.txt 安装，需与本机 CUDA 版本匹配（有 GPU 时）。
• Docker：Docker 方式需要先安装 Docker Engine，官方文档链接见 docs.docker.com/engine/install。
• 日语文本依赖：安装流程会执行 python -m unidic download 下载日语分词词典；WebUI 启动提示中也提醒必须先完成 unidic 下载，否则日语相关功能无法正常工作。
• 音频处理依赖：pydub、librosa、soundfile、torchaudio 等由 requirements.txt 安装；个别音频格式转换场景可能需要系统提供 ffmpeg，以本机实际报错为准。

5.2 硬件建议（官方口径与说明）

说明：官方 README 未公布逐语言模型的显存占用、精确内存下限与音频采样率清单，本节未补充臆造数值；部署时以本机加载日志与 docs/install.md 最新说明为准。

5.3 端口分配

远程服务器使用 Docker 部署时，可通过 SSH 隧道或带认证的反向代理访问 8888 端口；不要把 WebUI 不加鉴权地直接暴露到不可信公网。

6 方式一：Docker 构建运行（推荐 Windows / macOS 与兼容环境）

官方 docs/install.md 指出，为避免兼容性问题，Windows 用户与部分 macOS 用户建议通过 Docker 运行；仓库根目录提供 Dockerfile。

6.1 构建镜像

# 1. 克隆仓库
git clone https://github.com/myshell-ai/MeloTTS.git
cd MeloTTS

# 2. 构建镜像（官方说明：可能需要几分钟）
docker build -t melotts .

Dockerfile 主要步骤（供排障对照，以仓库最新版本为准）：

1. 基础镜像 python:3.9-slim，工作目录 /app；
2. apt-get 安装 build-essential、libsndfile1；
3. pip install -e . 安装仓库与 requirements.txt 依赖；
4. python -m unidic download 下载日语词典；
5. python melo/init_downloads.py 预下载六个语言模型；
6. 启动命令 python ./melo/app.py --host 0.0.0.0 --port 8888。

6.2 启动容器并访问

普通（CPU）运行：

docker run -it -p 8888:8888 melotts

本机有 NVIDIA GPU 时，官方给出带 GPU 参数的运行方式：

docker run --gpus all -it -p 8888:8888 melotts

启动后在浏览器打开：

http://localhost:8888

6.3 Docker 常用命令

# 查看本地镜像
docker images | grep melotts

# 查看正在运行的 melotts 容器
docker ps | grep melotts

# 停止前台启动的容器：在运行窗口按 Ctrl+C，或另开终端执行
docker stop <容器ID>

# 查看容器日志
docker logs <容器ID>

# 重新构建（修改源码或依赖后）
docker build -t melotts .

Docker 方式把模型预下载、系统依赖与运行环境打包在镜像内，适合环境隔离部署；若需要在脚本中批量调用 CLI / Python API，源码安装方式（第 7 章）更便于集成。

7 方式二：源码 / 本地安装运行

7.1 克隆与安装（Linux / macOS）

官方 docs/install.md 的本地安装步骤：

git clone https://github.com/myshell-ai/MeloTTS.git
cd MeloTTS
pip install -e .
python -m unidic download

• pip install -e . 会按 requirements.txt 安装 PyTorch、torchaudio、transformers==4.27.4、librosa==0.9.1、gradio、pydub、中文分词 jieba、拼音转换 pypinyin、日语文本处理 fugashi / pykakasi / unidic、韩语文本处理 jamo 等依赖；setup.py 安装后同样会触发 unidic 下载。
• 安装完成后可执行命令：melo-ui（WebUI）、melo 与 melotts（CLI）。
• 官方提示：macOS 安装若遇到问题，改用第 6 章 Docker 安装。

7.2 启动 WebUI

# 方式一：入口命令
melo-ui

# 方式二：直接运行脚本
python melo/app.py

可选参数（来自 melo/app.py 的命令行定义）：

# 指定监听地址与端口
melo-ui --host 0.0.0.0 --port 8888

# 生成一个可对外分享的 Gradio 临时链接（官方提示：仅把链接分享给信任的人）
melo-ui --share

默认情况下 Gradio 使用其默认端口；浏览器打开对应地址后选择语言、说话人、输入文本并合成试听。

7.3 CLI 合成命令

官方 docs/install.md 给出的 CLI 示例：

# 1. 默认英语合成
melo "Text to read" output.wav

# 2. 指定语言
melo "Text to read" output.wav --language EN

# 3. 指定英语说话人（美式 / 澳大利亚等）
melo "Text to read" output.wav --language EN --speaker EN-US
melo "Text to read" output.wav --language EN --speaker EN-AU

# 4. 指定语速
melo "Text to read" output.wav --language EN --speaker EN-US --speed 1.5
melo "Text to read" output.wav --speed 1.5

# 5. 中文合成（中英混读）
melo "text-to-speech 领域近年来发展迅速" zh.wav -l ZH

# 6. 从文本文件批量读取
melo file.txt out.wav --file

查看完整参数说明：

melo --help

7.4 Python API 调用

英语多口音示例（官方 docs/install.md）：

from melo.api import TTS

speed = 1.0
# auto：自动探测 GPU / MPS / CPU；也可手动设为 'cpu'、'cuda'、'cuda:0'、'mps'
device = 'auto'

text = "Did you ever hear a folk tale about a giant turtle?"
model = TTS(language='EN', device=device)
speaker_ids = model.hps.data.spk2id

# 美式口音
model.tts_to_file(text, speaker_ids['EN-US'], 'en-us.wav', speed=speed)
# 英式口音
model.tts_to_file(text, speaker_ids['EN-BR'], 'en-br.wav', speed=speed)
# 印度口音
model.tts_to_file(text, speaker_ids['EN_INDIA'], 'en-india.wav', speed=speed)
# 澳大利亚口音
model.tts_to_file(text, speaker_ids['EN-AU'], 'en-au.wav', speed=speed)
# 默认口音
model.tts_to_file(text, speaker_ids['EN-Default'], 'en-default.wav', speed=speed)

中文（中英混读）示例：

from melo.api import TTS

speed = 1.0
device = 'cpu'  # 或 'cuda:0'

text = "我最近在学习machine learning，希望能够在未来的artificial intelligence领域有所建树。"
model = TTS(language='ZH', device=device)
speaker_ids = model.hps.data.spk2id
model.tts_to_file(text, speaker_ids['ZH'], 'zh.wav', speed=speed)

西班牙语、法语、日语、韩语分别把 language 换为 ES、FR、JP、KR，说话人取 speaker_ids 中第一个内置说话人；完整代码以官方 docs/install.md 各语言小节为准。

7.5 自定义数据集训练（官方 docs/training.md）

先以开发模式安装并进入 melo 目录：

pip install -e .
cd melo

1. 数据准备：官方建议使用 44100Hz 音频文件；元数据文件每行格式为：

path/to/audio_001.wav|<speaker_name>|<language_code>|<text_001>
path/to/audio_002.wav|<speaker_name>|<language_code>|<text_002>

转写文本可使用 ASR 模型（如 Whisper）获得；示例元数据见 data/example/metadata.list。

2. 文本预处理：

python preprocess_text.py --metadata data/example/metadata.list

会生成 data/example/config.json；遇到 CUDA 显存不足时可在该配置中调小 batch size。

3. 启动训练：

bash train.sh <path/to/config.json> <num_of_gpus>

官方说明：部分机器上训练可能因 PyTorch gloo 相关问题偶发崩溃，因此 train.sh 内置了自动断点续训包装。

4. 训练后推理：

python infer.py --text "<some text here>" -m /path/to/checkpoint/G_<iter>.pth -o <output_dir>

训练所需 GPU 型号、显存时长等具体指标，官方 docs/training.md 未逐项列出，以官方仓库最新说明为准。

8 配置项说明

8.1 CLI 参数（melo / melotts，来自 melo/main.py）

8.2 Python API 构造参数（melo/api.py）

tts_to_file(text, speaker_id, output_path, speed=1.0, ...) 主要参数：文本、说话人 ID（model.hps.data.spk2id 取值）、输出路径或内存字节流对象、语速；WebUI 调用时还可传入进度条对象与 format='wav'。

8.3 WebUI 参数（melo/app.py）

8.4 模型权重来源

• 默认 use_hf=True：配置与检查点优先从 Hugging Face 仓库 myshell-ai/MeloTTS-English、myshell-ai/MeloTTS-French、myshell-ai/MeloTTS-Japanese、myshell-ai/MeloTTS-Chinese、myshell-ai/MeloTTS-Korean 等下载（完整映射以 melo/download_utils.py 最新版本为准）。
• 备用地址：官方 S3 托管 https://myshell-public-repo-host.s3.amazonaws.com/openvoice/basespeakers/<语言>/checkpoint.pth 与对应 config.json；另有 pretrained/G.pth、D.pth、DUR.pth 训练用预训练权重。
• 网络受限环境可先在有网机器上完成下载，或通过 config_path / ckpt_path 指定本地权重；具体本地权重目录结构以 melo/download_utils.py 为准。

9 常用运维命令

# 源码环境：重新安装依赖（修改 requirements.txt 后）
pip install -e .

# 重新下载日语词典
python -m unidic download

# 预下载全部六个语言模型（Dockerfile 构建时已执行；本地离线环境可手动执行）
python melo/init_downloads.py

# 查看 CLI 全部参数
melo --help

# 重启 WebUI：前台 Ctrl+C 后重新执行 melo-ui
melo-ui --host 0.0.0.0 --port 8888

# Docker：列出镜像、容器
docker images | grep melotts
docker ps -a | grep melotts

# Docker：查看日志 / 停止 / 删除容器
docker logs <容器ID>
docker stop <容器ID>
docker rm <容器ID>

# 清理未使用的 Docker 镜像与构建缓存（谨慎执行）
docker system prune

更新代码：进入仓库目录执行 git pull 后重新 pip install -e .（源码方式）或重新 docker build -t melotts .（Docker 方式）；模型权重若有新版本，按首次加载逻辑自动更新缓存。

10 常见故障排查

10.1 WebUI 启动提示"请先下载 unidic"

现象：melo/app.py 启动时打印 Make sure you've downloaded unidic (python -m unidic download) for this WebUI to work.，日语合成异常。

处理：在源码环境执行：

python -m unidic download

Docker 镜像已在构建阶段执行该步骤；若自定义镜像未执行，重新构建即可。

10.2 模型下载失败 / 卡在下载界面

现象：首次加载某语言模型时网络超时、连接重置或文件校验失败。

排查与处理：

1. 确认本机可访问 Hugging Face 与 myshell-public-repo-host.s3.amazonaws.com；
2. 检查代理 / 网络环境是否需要配置 HF_ENDPOINT 或其他镜像环境变量（镜像变量名称与可用地址以本机 Hugging Face 工具链文档为准）；
3. 删除本地缓存后重新加载，让工具重新下载完整文件；
4. 有现成权重时，通过 Python API 的 config_path、ckpt_path 或 use_hf=False 指定本地模型。

10.3 非英语指定 --speaker 不生效

现象：对 ZH / ES / FR / JP / KR 传入 --speaker，输出仍是默认说话人，并收到警告。

原因：官方 CLI 实现中说话人选择仅对英语生效；其他语言模型只有内置默认说话人，属于预期行为，不是故障。

10.4 合成文本为空报错

现象：CLI 抛出 ValueError: You entered empty text or the file you passed was empty.

处理：检查传入字符串是否为空；使用 --file 时确认文件存在且内容非空白；melo/main.py 在文件不存在时会先抛出 FileNotFoundError，此时确认参数中是否误加了 --file。

10.5 macOS 源码安装依赖冲突

现象：pip install -e . 过程中 librosa==0.9.1、transformers==4.27.4 或语音前端依赖在当前 Python 版本上编译失败。

处理：官方 docs/install.md 明确建议 macOS 遇到安装问题时改用第 6 章 Docker 安装；如需源码运行，先核对 Python 3.9 环境与 PyTorch 对应版本，再按 requirements.txt 逐项定位冲突包。

10.6 训练时 CUDA 显存不足

现象：bash train.sh 训练启动后报 CUDA out-of-memory。

处理：官方 docs/training.md 建议在预处理生成的 data/example/config.json 中调小 batch size；其余训练超参数按该配置文件调整。

10.7 GPU 未被识别

现象：device='auto' 或 --device cuda 下仍走 CPU，或 cuda 相关断言失败。

排查：

python -c "import torch; print(torch.cuda.is_available(), torch.backends.mps.is_available())"

• 返回 False：检查 PyTorch 是否按本机 CUDA 版本安装、驱动是否正确；
• Apple Silicon 设备：确认 PyTorch 版本支持 MPS，设备参数用 mps；
• Docker GPU：宿主机需安装 NVIDIA Container Toolkit，运行时使用 --gpus all。

10.8 端口被占用

现象：WebUI 启动报端口占用。

处理：本地启动时用 --port 指定其他端口；Docker 运行时把宿主机端口改为其他映射，例如 docker run -it -p 9000:8888 melotts，随后访问 http://localhost:9000。

11 风险与合规说明

11.1 许可证范围

• 本仓库源码采用 MIT License，官方 README 明确说明"free for both commercial and non-commercial use"；商用与非商业使用通常均允许，具体条款以仓库 LICENSE 原文为准。
• 实现基于 Coqui TTS、VITS、VITS2、Bert-VITS2 等开源项目，这些上游组件按各自许可证适用；集成分发时请同时核对上游许可证。
• 模型权重分别托管在 Hugging Face myshell-ai/* 与官方 S3 地址，权重适用条款以模型卡片与仓库 LICENSE 说明为准。

11.2 合成内容与声音权益

• MeloTTS 内置为固定说话人模型，不提供任意人声克隆；使用者仍需对自己合成的文本内容负责，不得用于制作违法、诽谤、欺诈、色情、暴力、冒充他人身份等内容。
• 合成语音不得伪装成特定真实人物的声音用于欺骗、诈骗或身份冒充；对外发布含人声的作品时，建议按当地法规标注内容由 AI 合成。

11.3 数据与隐私

• 文本在本地模型上合成，仓库本身不向第三方回传文本；使用在线 Space、MyShell Demo 或其他第三方服务时，需另行阅读对应平台的隐私政策。
• 自定义训练数据集（音频、转写文本）涉及的人声与语音权益，应在取得录音相关权利人授权后再使用与分发。

11.4 免责声明

本指南依据官方公开文档整理，命令、参数与端口均来自仓库 README、docs/install.md、docs/training.md 与源码；官方后续版本可能调整依赖版本、模型渠道与界面参数，部署时以仓库最新说明为准。作者与本文不对因使用、修改或运行本项目产生的直接或间接损失承担责任，法律不得排除或限制的责任除外。