企业官网建设流程全解析

MeloTTS 安装与使用完整指南：本地、Docker、WebUI、CLI 与 Python API 实战

【免费下载链接】MeloTTSHigh-quality multi-lingual text-to-speech library by MyShell.ai. Support English, Spanish, French, Chinese, Japanese and Korean.项目地址: https://gitcode.com/GitHub_Trending/me/MeloTTS

MeloTTS 是 MyShell.ai 开源的高质量多语言文本转语音（TTS）库，支持英语（多种口音）、西班牙语、法语、中文（中英混读）、日语和韩语，并宣称在 CPU 上即可进行实时推理。本文以 docs/install.md 为核心骨架，结合仓库源码，系统讲解在 Linux/macOS 上的本地安装、Windows 用户的 Docker 部署，以及 WebUI、CLI、Python API 三种使用方式，帮助你快速在本地跑通多语言语音合成。

一、环境要求与安装前准备

官方文档明确说明：仓库在Ubuntu 20.04 与 Python 3.9环境下开发与测试。从 Dockerfile 可以看到，官方镜像同样基于python:3.9-slim，因此建议本地环境尽量对齐 Python 3.9，避免依赖编译或运行时兼容问题。

MeloTTS 的依赖体量较大，requirements.txt 中涵盖了文本处理、音素化和深度学习等各类库，其中值得注意的几个关键依赖：

• torch/torchaudio：模型推理与音频处理的核心框架；
• transformers==4.27.4：中文/英文等语言的 BERT 特征提取；
• unidic/unidic_lite/fugashi/mecab-python3：日语的形态素分析（MeCab + UniDic 词典）；
• gruut[de,es,fr]==2.2.3：西班牙语与法语的字素到音素（G2P）转换；
• g2p_en/g2pkk/pypinyin/jieba/cn2an：英语、韩语、中文的发音、分词与数字转换；
• librosa==0.9.1/soundfile/pydub：音频处理与保存；
• gradio：WebUI 界面的底层框架。

注意：由于日语的音素化依赖 UniDic 词典，安装过程中必须单独执行python -m unidic download下载词典数据，否则运行时会报错。这一点在后文会反复出现。

二、Linux 与 macOS 本地安装

2.1 安装步骤

在 Linux 或 macOS 终端中，依次执行以下命令：

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

各步骤的作用如下：

1. git clone：将仓库克隆到本地；
2. cd MeloTTS：进入项目根目录；
3. pip install -e .：以可编辑（开发）模式安装项目。从 setup.py 可以看到，该命令会安装requirements.txt中的全部依赖，并注册三个命令行入口：melotts、melo（指向melo.main:main）和melo-ui（指向melo.app:main）；
4. python -m unidic download：下载日语 UniDic 词典。实际上这一步并非可选项——从 setup.py 的PostInstallCommand和PostDevelopCommand可以看到，安装过程本身就会自动执行一次python -m unidic download，此处单独再执行一次是为了确保词典完整可用。

安装完成后，可通过pip show melotts确认版本（当前仓库setup.py中版本号为0.1.2），并通过melo --help查看 CLI 的全部参数。

2.2 模型文件的自动下载机制

MeloTTS 采用「首次运行时自动下载模型」的设计。从 melo/download_utils.py 可以看到：

• 模型权重：每种语言对应一个checkpoint.pth，默认通过huggingface_hub.hf_hub_download从 Hugging Face 仓库（如myshell-ai/MeloTTS-English、myshell-ai/MeloTTS-Chinese等）下载；
• 配置文件：每种语言对应一个config.json，同样默认从 Hugging Face 下载；
• 备用地址：代码中还保留了 S3 的直链地址（DOWNLOAD_CKPT_URLS/DOWNLOAD_CONFIG_URLS），当use_hf=False时走cached_path从 S3 下载。

因此，第一次调用 TTS 时会自动拉取对应语言的权重与配置，需要保证网络可以访问 Hugging Face。下载后的模型会缓存在本地，后续使用不再重复下载。

2.3 macOS 安装常见问题

官方文档特别提示：如果在 macOS 安装过程中遇到问题，请尝试下方的 Docker 安装方式。常见的 macOS 问题多与librosa、torchaudio等涉及原生编译的依赖、以及 MeCab/fugashi 等 C 扩展的编译环境有关。如果本机安装了 Apple Silicon 芯片，也可以关注 PyTorch 对mps后端的支持（见后文 Python API 部分）。

三、Docker 安装（Windows 与部分 macOS 用户推荐）

为了避免本地环境的兼容性问题，官方文档建议 Windows 用户和部分 macOS 用户通过 Docker 运行。前提是系统已经安装好 Docker（请参照 Docker 官方安装文档完成安装）。

3.1 构建镜像

在项目根目录执行：

git clone https://github.com/myshell-ai/MeloTTS.git cd MeloTTS docker build -t melotts .

构建过程需要几分钟。从 Dockerfile 可以看到镜像的构建逻辑：

FROM python:3.9-slim WORKDIR /app COPY . /app RUN apt-get update && apt-get install -y \ build-essential libsndfile1 \ && rm -rf /var/lib/apt/lists/* RUN pip install -e . RUN python -m unidic download RUN python melo/init_downloads.py CMD ["python", "./melo/app.py", "--host", "0.0.0.0", "--port", "8888"]

几点关键信息：

• 基础镜像为python:3.9-slim，与官方开发环境对齐；
• 额外安装了build-essential（编译依赖）和libsndfile1（音频文件读写库，librosa/soundfile 的底层依赖）；
• 构建时预先执行pip install -e .、python -m unidic download和python melo/init_downloads.py，其中 melo/init_downloads.py 会依次初始化全部 6 种语言（EN/ES/FR/ZH/JP/KR）的 TTS 模型，相当于在镜像内预下载好所有模型与权重，避免容器运行时再联网下载；
• 默认启动命令是python ./melo/app.py --host 0.0.0.0 --port 8888，即直接以 WebUI 形式对外提供服务。

3.2 运行容器

docker run -it -p 8888:8888 melotts

如果你的本机有 NVIDIA GPU，可以改用：

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

容器启动后，在浏览器中打开 http://localhost:8888 即可使用 WebUI。-p 8888:8888将容器内的 8888 端口映射到宿主机，--gpus all让容器内的 PyTorch 可以使用宿主机的 CUDA GPU 加速推理。

四、WebUI 图形界面使用

安装完成后，只需一条命令即可启动 WebUI：

melo-ui # 或者： python melo/app.py

melo-ui是 setup.py 注册的控制台入口，实际指向melo.app:main。

4.1 WebUI 的功能设计

从 melo/app.py 源码可以了解界面的完整交互逻辑：

• 语言选择：提供EN / ES / FR / ZH / JP / KR六种语言单选（对应代码中的gr.Radio），切换语言时会同步更新说话人（Speaker）下拉框的候选项，并把文本示例自动切换为该语言的默认句子；
• 说话人选择：下拉框列出当前语言的全部 speaker id（英语为多种口音，其他语言一般为单一说话人）；
• 语速调节：Speed滑杆范围0.1～10.0，步长 0.1，默认 1.0；
• 合成按钮：点击Synthesize后调用tts_to_file生成 wav 音频，并通过 Gradio 的gr.Audio组件播放；
• 分享链接：melo-ui -s或python melo/app.py -s可开启--share参数，生成一个可公开访问的 Gradio 共享链接（仅应分享给信任的人）。

启动 WebUI 时同样需要保证 UniDic 词典已下载（melo/app.py启动时会打印相关提示），且首次使用某种语言时会自动下载对应模型。

五、CLI 命令行使用

MeloTTS 提供了melotts和melo两个等价的 CLI 命令（两者都指向melo.main:main）。运行melo --help可查看完整参数说明。

5.1 基础用法示例

直接朗读一段英语文本：

melo "Text to read" output.wav

指定语言（--language/-l）：

melo "Text to read" output.wav --language EN

指定英语说话人（口音）（--speaker/-spk）：

melo "Text to read" output.wav --language EN --speaker EN-US melo "Text to read" output.wav --language EN --speaker EN-AU

指定语速（--speed/-s）：

melo "Text to read" output.wav --language EN --speaker EN-US --speed 1.5 melo "Text to read" output.wav --speed 1.5

使用中文（含中英混读）：

melo "text-to-speech 领域近年来发展迅速" zh.wav -l ZH

从文件读取文本（--file/-f）：

melo file.txt out.wav --file

5.2 参数与说话人说明

从 melo/main.py 的 click 定义可以看出完整的参数约束：

英语可用的说话人（口音）为：EN-Default、EN-US（美式）、EN-BR（英式）、EN_INDIA（印度式）、EN-AU（澳式）。

CLI 内部实现要点（见 melo/main.py）：

• 开启--file时若文件不存在会抛出FileNotFoundError，空文本会抛出ValueError；
• 对非英语语言指定--speaker会触发警告（源码中的 warning 提示信息为"specified a speaker but the language is English"），实际忽略该参数，自动使用该语言spk2id中的第一个说话人；
• 最终统一调用model.tts_to_file(text, spkr, output_path, speed=speed)完成合成。

六、Python API 使用

Python API 是功能最完整的接入方式，核心类是 melo/api.py 中的TTS。通过TTS(language=..., device=...)加载模型后，使用tts_to_file即可生成语音。

6.1 TTS 类核心要点

从源码看，TTS.__init__支持四个关键参数：

• language：必填，语言代码EN/ES/FR/ZH/JP/KR；
• device：默认'auto'，会自动探测：优先 CUDA，其次 Apple Silicon 的mps，否则回退到cpu（见 melo/api.py）。也可以手动指定'cpu'、'cuda'、'cuda:0'、'mps'；
• use_hf：默认True，控制模型从 Hugging Face 下载还是从 S3 直链下载；
• config_path/ckpt_path：可手动指定本地配置文件与权重路径，跳过自动下载。

tts_to_file的关键参数与默认值：

从实现上看（melo/api.py），tts_to_file的完整流程为：

1. 通过split_sentences_into_pieces调用 melo/split_utils.py 中的split_sentence对长文本进行分句——拉丁语系走split_sentences_latin，中日韩走split_sentences_zh，并在分句时合并过短的句子；
2. 逐句调用utils.get_text_for_tts_infer完成文本到音素序列、音调序列、语言 id 与 BERT 特征的转换；
3. 在torch.no_grad()下调用self.model.infer(...)，其中length_scale=1./speed就是语速参数的实际作用点（speed越大，length_scale越小，输出越短越快）；
4. 将各分句的音频通过audio_numpy_concat拼接，段间插入 50ms（sr * 0.05 / speed）的静音间隔；
5. 使用soundfile.write写入文件（output_path=None时直接返回音频数组）。

6.2 英语（多种口音）

from melo.api import TTS # Speed is adjustable speed = 1.0 # CPU is sufficient for real-time inference. # You can set it manually to 'cpu' or 'cuda' or 'cuda:0' or 'mps' device = 'auto' # Will automatically use GPU if available # English text = "Did you ever hear a folk tale about a giant turtle?" model = TTS(language='EN', device=device) speaker_ids = model.hps.data.spk2id # American accent output_path = 'en-us.wav' model.tts_to_file(text, speaker_ids['EN-US'], output_path, speed=speed) # British accent output_path = 'en-br.wav' model.tts_to_file(text, speaker_ids['EN-BR'], output_path, speed=speed) # Indian accent output_path = 'en-india.wav' model.tts_to_file(text, speaker_ids['EN_INDIA'], output_path, speed=speed) # Australian accent output_path = 'en-au.wav' model.tts_to_file(text, speaker_ids['EN-AU'], output_path, speed=speed) # Default accent output_path = 'en-default.wav' model.tts_to_file(text, speaker_ids['EN-Default'], output_path, speed=speed)

通过model.hps.data.spk2id可以拿到该语言的全部说话人 id 及其数值映射，然后按需选择口音合成。

6.3 西班牙语

from melo.api import TTS # Speed is adjustable speed = 1.0 # CPU is sufficient for real-time inference. # You can also change to cuda:0 device = 'cpu' text = "El resplandor del sol acaricia las olas, pintando el cielo con una paleta deslumbrante." model = TTS(language='ES', device=device) speaker_ids = model.hps.data.spk2id output_path = 'es.wav' model.tts_to_file(text, speaker_ids['ES'], output_path, speed=speed)

6.4 法语

from melo.api import TTS # Speed is adjustable speed = 1.0 device = 'cpu' # or cuda:0 text = "La lueur dorée du soleil caresse les vagues, peignant le ciel d'une palette éblouissante." model = TTS(language='FR', device=device) speaker_ids = model.hps.data.spk2id output_path = 'fr.wav' model.tts_to_file(text, speaker_ids['FR'], output_path, speed=speed)

6.5 中文（支持中英混读）

from melo.api import TTS # Speed is adjustable speed = 1.0 device = 'cpu' # or cuda:0 text = "我最近在学习machine learning，希望能够在未来的artificial intelligence领域有所建树。" model = TTS(language='ZH', device=device) speaker_ids = model.hps.data.spk2id output_path = 'zh.wav' model.tts_to_file(text, speaker_ids['ZH'], output_path, speed=speed)

中文是 MeloTTS 的特色能力：内部将ZH映射为ZH_MIX_EN模型（见 melo/api.py），即中文语音合成同时支持英文单词的嵌入混读，非常适合中英夹杂的自然场景。上面的示例文本就同时包含了中文与英文片段。

6.6 日语

from melo.api import TTS # Speed is adjustable speed = 1.0 device = 'cpu' # or cuda:0 text = "彼は毎朝ジョギングをして体を健康に保っています。" model = TTS(language='JP', device=device) speaker_ids = model.hps.data.spk2id output_path = 'jp.wav' model.tts_to_file(text, speaker_ids['JP'], output_path, speed=speed)

6.7 韩语

from melo.api import TTS # Speed is adjustable speed = 1.0 device = 'cpu' # or cuda:0 text = "안녕하세요! 오늘은 날씨가 정말 좋네요." model = TTS(language='KR', device=device) speaker_ids = model.hps.data.spk2id output_path = 'kr.wav' model.tts_to_file(text, speaker_ids['KR'], output_path, speed=speed)

七、运行验证与常见问题

7.1 通过测试脚本验证安装

仓库的 test/test_base_model_tts_package.py 提供了批量验证脚本：它接收一个语言参数（en/es/fr/zh/jp/kr），从 test/basets_test_resources 目录读取对应的示例文本（每种语言一个*_egs_text.txt），然后对每个说话人、每个句子、以speed=1.0合成 wav 到basetts_outputs_package目录。可以以此确认安装与模型加载是否正常。

7.2 常见问题排查

7.3 补充：模型配置参考

仓库内的 melo/configs/config.json 是训练/推理使用的通用配置模板，其中与推理直接相关的数据配置包括：采样率sampling_rate: 44100、filter_length: 2048、hop_length: 512、mel 通道数n_mel_channels: 128、说话人容量n_speakers: 256等。实际运行时，每种语言会使用各自独立的config.json（自动从 Hugging Face 或 S3 下载），仓库中的这份配置可作为理解模型结构的参考。

八、总结

MeloTTS 的接入路径非常清晰：Linux/macOS 用户走pip install -e .本地安装，Windows 及部分 macOS 用户推荐 Docker；安装后可通过melo-ui（WebUI）、melo（CLI）和 PythonTTSAPI 三种方式使用。全流程的关键节点包括：

1. 安装后必须执行python -m unidic download（日语词典）；
2. 首次使用某种语言会自动下载对应模型权重与配置；
3. 英语支持 5 种口音，中文支持中英混读，语速可通过--speed/speed参数调节；
4. tts_to_file底层完成「分句 → 文本转音素/BERT 特征 → 模型推理 → 分段拼接 → 写 wav」的完整链路。

如果只是快速体验，推荐使用 Docker（镜像内已预置全部模型）或直接运行melo-ui；如果需要集成到自己的应用，推荐使用 Python API，其tts_to_file既能写文件，也能在output_path=None时直接返回音频数组，方便后续做流式或二次处理。

【免费下载链接】MeloTTSHigh-quality multi-lingual text-to-speech library by MyShell.ai. Support English, Spanish, French, Chinese, Japanese and Korean.项目地址: https://gitcode.com/GitHub_Trending/me/MeloTTS