programus/moss-tts-nano

By programus

•Updated 6 months ago

A simple TTS API image based on MOSS-TTS-Nano

Image

Machine learning & AI

2.8K

Overview Tags

programus/moss-tts-nano repository overview

https://gist.github.com/programus/72911a6b1c169707afd650709254b59f⁠

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

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

This guide explains how to use the supplemental files from the Gist alongside the original 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

文件 / File	说明 / Description
`Dockerfile`	构建镜像所需。已发布到 Docker Hub，通常无需自行构建。 / Needed only if you build the image yourself. A pre-built image is available on Docker Hub.
`docker-compose.yml`	定义三个服务，日常使用只需这一个文件。 / Defines all three services. This is the only file you need day-to-day.
`tts_api_server.py`	通用 TTS REST API 服务器（OpenAI 兼容 + 简单 GET/POST 接口）。 / Generic TTS REST API server (OpenAI-compatible + simple GET/POST).
`.dockerignore`	构建镜像时的排除规则，与 `Dockerfile` 配套使用。 / Build exclusion rules, used together with `Dockerfile`.

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

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

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

mkdir -p models generated_audio custom_voices

⁠4. 启动服务 / Start Services

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

docker compose up -d

仅启动 API 服务 / API server only:

docker compose up -d tts-api

仅启动 Web Demo / Web demo only:

docker compose up -d tts-onnx

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

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

服务 / Service	端口 / Port	说明 / Description
`tts-onnx`	18083	ONNX 后端 Web Demo（浏览器界面）/ ONNX web demo UI
`tts-api`	18084	通用 TTS REST API / Generic TTS REST API
`tts-pytorch`	18083	PyTorch 后端 Web Demo（`--profile pytorch`）/ PyTorch web demo

⁠API 使用 / API Usage

⁠查看可用声音 / List Available Voices

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

响应示例 / Example response:

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

⁠OpenAI 兼容接口 / OpenAI-Compatible Endpoint

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

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.

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",

# 仅构建 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):

系统库：libsndfile1、ffmpeg、git、build-essential
pynini==2.1.6.post1
WeTextProcessing（从 GitHub 安装）
CPU-only PyTorch + torchaudio
其余 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

# 查看运行状态 / 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）

Tag summary

Recent tags

Content type

Image

Digest

sha256:b04a32ce1…

Size

791.2 MB

Last updated

6 months ago

docker pull programus/moss-tts-nano:onnx-20260418.2