programus/moss-tts-nano

https://gist.github.com/programus/72911a6b1c***afd650709254b59f

MOSS-TTS-Nano — Docker 部署指南 / Docker Deployment Guide

本文件说明如何将 Gist 中的附加文件与 https://github.com/OpenMOSS/MOSS-TTS-Nano 原始仓库配合使用，在 Docker 中运行 TTS 服务。

This guide explains how to use the supplemental files from the Gist alongside the original https://github.com/OpenMOSS/MOSS-TTS-Nano repository to run the TTS service inside Docker.

⚠️ 注意 / Note
本文件内容基于 2026-04-18 时原始仓库的状态编写，仅保证对该时间点的版本有效。若原始仓库日后有所更新，部分步骤或依赖可能不再适用，请以最新仓库内容为准。
This guide is written against the state of the original repository as of 2026-04-18. It is only guaranteed to work with that version. If the upstream repository is updated in the future, some steps or dependencies may no longer apply — please refer to the latest repo for authoritative information.

---

Gist 包含的文件 / Files in the Gist

---

快速开始（使用 Docker Hub 预构建镜像）/ Quick Start (Pre-built Docker Hub Image)

1. 克隆原始仓库 / Clone the Original Repo

bash
git clone https://github.com/OpenMOSS/MOSS-TTS-Nano.git
cd MOSS-TTS-Nano

2. 下载 Gist 文件 / Download Gist Files

将 Gist 中的以下文件放入仓库根目录（覆盖或新增均可）：

Place the following files from the Gist into the repository root (add or overwrite):

MOSS-TTS-Nano/
├── docker-compose.yml      ← 来自 Gist / from Gist
├── tts_api_server.py       ← 来自 Gist / from Gist
├── Dockerfile              ← 来自 Gist（仅自行构建时需要 / only needed for self-build）
└── .dockerignore           ← 来自 Gist（仅自行构建时需要 / only needed for self-build）

3. 创建运行时目录 / Create Runtime Directories

bash
mkdir -p models generated_audio custom_voices

4. 启动服务 / Start Services

启动全部默认服务（Web Demo + API）/ Start all default services (Web Demo + API):

bash
docker compose up -d

仅启动 API 服务 / API server only:

bash
docker compose up -d tts-api

仅启动 Web Demo / Web demo only:

bash
docker compose up -d tts-onnx

使用 PyTorch 后端的 Web Demo（需要更多内存）/ PyTorch-backend web demo (requires more RAM):

bash
docker compose --profile pytorch up -d tts-pytorch

首次启动说明 / First-run note
首次启动时，容器会自动从 Hugging Face 下载模型权重（约 400 MB），下载结果会缓存到 ./models 目录，下次启动无需重新下载。
On first start, the container automatically downloads model weights from Hugging Face (~400 MB) into the ./models directory. Subsequent starts reuse the cache.

---

服务说明 / Service Overview

---

API 使用 / API Usage

查看可用声音 / List Available Voices

bash
curl http://localhost:18084/v1/voices

响应示例 / Example response:

json
{
  "object": "list",
  "data": [
    {
      "id": "Junhao",
      "object": "voice",
      "source": "onnx_builtin",
      "display_name": "CN 欢迎关注模思智能",
      "group": "Chinese Male",
      "language": "zh",
      "gender": "male"
    },
    ...
  ]
}

OpenAI 兼容接口 / OpenAI-Compatible Endpoint

bash
curl http://localhost:18084/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"input": "你好，世界！", "voice": "Junhao"}' \
  --output output.wav

简单 GET 接口（适合 Home Assistant）/ Simple GET (ideal for Home Assistant)

http://localhost:18084/tts?text=你好世界&voice=Junhao

Home Assistant rest_command 示例 / Example

yaml
rest_command:
  moss_tts:
    url: "http://<HOST_IP>:18084/tts?text={{ text | urlencode }}&voice=Junhao"
    method: GET

固定输出（可复现）/ Deterministic Output

追加 seed 参数或使用 sample_mode=greedy 可获得完全相同的输出：

Append a seed or use sample_mode=greedy for reproducible results:

http://localhost:18084/tts?text=你好&voice=Junhao&seed=42
http://localhost:18084/tts?text=你好&voice=Junhao&sample_mode=greedy

交互式 API 文档 / Interactive API Docs

http://localhost:18084/docs

---

自定义声音 / Custom Voices

将任意 WAV / MP3 / FLAC / OGG / M4A 音频文件放入 custom_voices/ 目录，无需重启即可使用。文件名（去掉扩展名）即为 voice ID。

Drop any WAV / MP3 / FLAC / OGG / M4A file into custom_voices/. It becomes available immediately without restart. The filename stem is used as the voice ID.

bash
cp my_voice.wav ./custom_voices/alice.wav
# → voice ID: alice
curl "http://localhost:18084/tts?text=Hello&voice=alice" --output out.wav

M4A 支持 / M4A Support
容器内已安装 ffmpeg，M4A（iPhone 录音等）会自动转换后使用。
ffmpeg is pre-installed in the container. M4A files (e.g. iPhone recordings) are auto-converted on the fly.

---

自行构建镜像 / Building the Image Yourself

如果需要修改代码或无法访问 Docker Hub，可以自行构建：

If you need to modify the code or cannot access Docker Hub, build locally:

构建前准备 / Pre-build requirement
原始仓库的 requirements.txt 和 pyproject.toml 中需要包含 python-dateutil 依赖，否则构建会失败。
The original repo's requirements.txt and pyproject.toml must include the python-dateutil dependency, otherwise the build will fail.

请确认两个文件中均包含以下行（如缺失请手动添加）：
Make sure both files contain the following (add manually if missing):

requirements.txt：

python-dateutil>=2.9.0.post0

pyproject.toml（dependencies 列表内）：

"python-dateutil>=2.9.0.post0",

bash
# 仅构建 tts-api 镜像 / Build only the tts-api image
docker compose build tts-api

# 构建全部镜像 / Build all images
docker compose build

构建过程会依次安装以下依赖（时间较长，约 10–20 分钟）：

The build installs dependencies in the following order (takes ~10–20 min on first build):

1. 系统库：libsndfile1、ffmpeg、git、build-essential
2. pynini==2.1.6.post1
3. WeTextProcessing（从 GitHub 安装）
4. CPU-only PyTorch + torchaudio
5. 其余 requirements.txt 依赖（含 python-dateutil）

---

目录结构 / Directory Layout

MOSS-TTS-Nano/
├── models/             ← 模型权重（首次启动自动下载）/ Model weights (auto-downloaded)
├── generated_audio/    ← Web Demo 生成的音频 / Audio generated by web demo
├── custom_voices/      ← 自定义声音样本 / Custom voice samples
│   └── alice.wav       ← 示例：voice ID = "alice" / Example: voice ID = "alice"
├── docker-compose.yml
├── tts_api_server.py
└── ...（原始仓库文件）/ ...original repo files

---

常用命令 / Useful Commands

bash
# 查看运行状态 / Check status
docker compose ps

# 查看日志 / View logs
docker compose logs -f tts-api

# 停止服务 / Stop services
docker compose down

# 更新镜像 / Pull latest image
docker compose pull
docker compose up -d

---

镜像信息 / Image Info

• Docker Hub: programus/moss-tts-nano:onnx-20260418
• 基础镜像 / Base image: python:3.12-slim
• 后端 / Backend: ONNX CPU（适合无 GPU 部署 / suitable for CPU-only deployment）