🗣️ Supertonic-ZH — v0.1.0-preview

Unofficial Mandarin (Chinese) text-to-speech · built on Supertonic-3.

Supertonic-3 is a fast, lightweight, on-device TTS family that does not synthesize Mandarin out of the box. Supertonic-ZH ships Mandarin as optimized, fused ONNX graphs (text encoder / duration predictor / vector estimator) that run in pure ONNX Runtime — no PyTorch. The vocoder is the frozen, unmodified upstream Supertonic-3 graph.

🔊 Hear it first — demos + benchmark: github.com/wuxuedaifu/supertonic_cn (Mandarin, plus retained English / Russian / Arabic / French / Japanese / Korean from the base model).

🔐 Gated / access

These weights are gated and provided on request under an evaluation license. Click "Request access" above. The current build is non-commercial only (Baker/CSMSC training data). Commercial licensing (a Baker-free build) is available separately — contact the author.

📦 What's in this repo

Not included — obtain from upstream:

• vocoder.onnx — the frozen base vocoder, from the upstream Supertone/supertonic-3 release (OpenRAIL-M).

Usage

1. Request access

Open this repository on Hugging Face, review the license conditions, and click Request access.

This release is for evaluation and non-commercial use only.

2. Install dependencies

pip install huggingface_hub onnxruntime numpy soundfile

For NVIDIA GPU inference, install ONNX Runtime GPU instead:

pip install huggingface_hub onnxruntime-gpu numpy soundfile

Do not install both onnxruntime and onnxruntime-gpu in the same environment.

3. Authenticate with Hugging Face

hf auth login

Use a Hugging Face access token belonging to an account that has been granted access to this repository.

4. Download Supertonic-ZH

hf download dove88/supertonic-zh \
  --local-dir ./supertonic-zh

Alternatively, download it from Python:

from huggingface_hub import snapshot_download

model_dir = snapshot_download(
    repo_id="dove88/supertonic-zh",
    local_dir="./supertonic-zh",
)

print(f"Model downloaded to: {model_dir}")

5. Obtain the upstream vocoder

This repository does not redistribute vocoder.onnx.

Download vocoder.onnx from the official upstream repository:

Supertone/supertonic-3

Place it inside the downloaded model directory:

supertonic-zh/
├── text_encoder_zh.onnx
├── duration_predictor_zh.onnx
├── vector_estimator_zh.onnx
├── unicode_indexer_zh.json
├── voice_zh.json
├── example_infer.py
└── vocoder.onnx

6. Generate speech

cd supertonic-zh

python example_infer.py \
  "今天天气很好，我们一起去公园散步吧。"

The generated audio is saved as:

out.wav

Python example

import subprocess
import sys
from pathlib import Path

model_dir = Path("./supertonic-zh")
script_path = model_dir / "example_infer.py"

required_files = [
    "text_encoder_zh.onnx",
    "duration_predictor_zh.onnx",
    "vector_estimator_zh.onnx",
    "unicode_indexer_zh.json",
    "voice_zh.json",
    "vocoder.onnx",
    "example_infer.py",
]

missing_files = [
    filename
    for filename in required_files
    if not (model_dir / filename).exists()
]

if missing_files:
    raise FileNotFoundError(
        "Missing required files: " + ", ".join(missing_files)
    )

subprocess.run(
    [
        sys.executable,
        str(script_path),
        "欢迎使用 Supertonic 中文语音合成模型。",
    ],
    cwd=model_dir,
    check=True,
)

Included files

The upstream vocoder.onnx file is required but is not included in this repository.

See example_infer.py for the full ~60-line pipeline (tokenize → text encoder → duration → flow-matching loop → vocoder). No PyTorch required.

🎙️ Voice

Ships a single preset voice (voice_zh.json). Custom voice / voice cloning is a separate capability, not part of this release.

⚠️ Limitations

1. Residual high-frequency artifact — bounded by the frozen upstream vocoder (never fine-tuned); a ceiling, not a bug.
2. Chinese⇄English code-switching is currently unreliable — embedded English words can be unclear (the Chinese fine-tune had no English data). On the roadmap.
3. Tone / polyphone / erhua accuracy are model-inherent to the character-level acoustic model.
4. Single preset voice.

Treat this as a feasibility preview, not a finished product.

🧾 License & attribution

• Base model: Supertonic-3, BigScience Open RAIL-M — its use-based restrictions (Attachment A) apply to this derivative and must be passed on to any downstream user.
• This build: additionally non-commercial only because of the Baker/CSMSC training data.
• Training data: AISHELL-3 (OpenSLR SLR93, Apache-2.0) + Baker/CSMSC (non-commercial).

Built on the publicly released Supertonic-3 model and sample code by Supertone Inc. This is an independent, unofficial extension.