If you need open-weight text-to-speech with voice cloning, natural-language delivery control, and inline laughs or sighs—not just a single static voice—Ming-3.0-tts from inclusionAI is a strong place to start. This guide walks through the official install, weight download, preflight check, and the task modes that matter in practice: zero-shot cloning, freeform instructions, paralinguistic tags, emotion/dialect/attributes, built-in voices, and (on tiny) multi-speaker podcast dialogue. Every command and number below is taken from the project’s GitHub README, infer.py, tts_tasks.py, and Hugging Face model cards, checked on October 20, 2026 (Beijing time).

Key facts (official sources, October 2026):

• Two models: Ming-3.0-tts-0.5B (dense, ~3.0 GB model.safetensors on Hugging Face) and Ming-3.0-tts-tiny (MoE on Ling V3: 7.9B total / 1.3B active, ~18 GB of sharded safetensors).
• License: MIT for code and weights (LICENSE; HF cardData.license: mit).
• Languages: Chinese and English, plus German, Spanish, French, Korean, Japanese; dialects Sichuanese (chuanyu dialect) and Cantonese.
• Artificial Analysis (Oct 2026, ranks change): 1st among open-weights on Controlled Voice (Elo 1069), 1st overall on Pronunciation Robustness (93.2%), 3rd among open-weights on Provider Voice (Elo 1188).
• 0.5B runtime: torch==2.6.0, transformers==4.46.3; tested on NVIDIA H800-80GB and H20-96G. flash-attn is optional (falls back to PyTorch SDPA).
• Tasks are exclusive: each call picks one task mode; controls from another task are rejected.

For more step-by-step model guides on this site, start from the 7minai homepage. If you care about speech recognition on Apple silicon instead of synthesis, see How to Use Apple SpeechAnalyzer. For a different small specialized open-weight stack, compare with running GLM-5.2 locally.

What Ming-3.0-tts is (and when to use it)

Ming-3.0-tts is a speech-generation stack: text and task-specific control tokens condition a language model with a DiT patch head and an audio tokenizer. Both the dense 0.5B and the tiny MoE share that framework. Each released checkpoint bundles the backbone, DiT head, audio tokenizer, speaker encoder (campplus.onnx), and text tokenizer.

Reach for it when you need:

• Zero-shot cloning from a short reference WAV plus matching transcript.
• Natural-language delivery (FREEFORM / freeform) without hand-tuning dozens of attribute knobs.
• Paralinguistic events inline in the text ([Laughter], [Sigh], …)—14 tags in the official vocabulary.
• Multi-speaker scripted dialogue (podcast on tiny only).
• An MIT-licensed open stack you can pin and serve yourself.

Skip it (for now) if you only have a laptop GPU and no access to high-VRAM NVIDIA hardware: the README’s reference environments are H800/H20-class. The authors do not publish a consumer-GPU VRAM table in the README, so this guide will not invent one.

Step 1: Pick 0.5B or tiny

Model	Architecture	Parameters	Hub id (canonical)	Approx. download
Ming-3.0-tts-0.5B	Dense	0.5B	inclusionAI/Ming-3.0-tts-0.5B	~3.0 GB (model.safetensors)
Ming-3.0-tts-tiny	MoE (Ling V3)	7.9B total · 1.3B active	inclusionAI/Ming-3.0-tts-tiny	~18 GB (30 shards)

Notes from the official repo:

• Hugging Face redirects lowercase …-0.5b to …-0.5B. Prefer the capital-B id in scripts.
• 0.5B and tiny use different Python environments (requirements.txt vs requirements-tiny.txt). Do not mix them in one venv.
• Podcast / multi-speaker is tiny-only.
• Roadmap checkbox: vLLM-Omni accelerated inference is marked done in the README; this guide sticks to the reference infer.py / infer_tiny.py path first.

Recommendation: start with 0.5B to validate cloning and freeform. Move to tiny when you need podcast dialogue or the MoE quality on the tasks you care about.

Step 2: Install the 0.5B environment

git clone https://github.com/inclusionAI/Ming-3.0-tts.git
cd Ming-3.0-tts
python -m venv .venv && source .venv/bin/activate   # or conda
pip install -r requirements.txt

Pinned core deps from requirements.txt (0.5B):

• torch==2.6.0, torchaudio==2.6.0
• transformers==4.46.3, accelerate==1.3.0
• diffusers==0.33.0, x_transformers==2.9.2
• soundfile==0.12.1, onnxruntime (for CAM++ speaker embeddings)

Optional Docker (README: torch 2.6, CUDA 12.4, transformers==4.46.3):

docker build -f docker/Dockerfile -t ming-tts .

Text normalization (pynini)

Numbers, dates, units and symbols use FST grammars via pynini. There is no universal wheel:

conda install -c conda-forge pynini==2.1.6
# or: pip install pynini==2.1.6

It loads lazily. To skip TN entirely:

python infer.py ... --no_text_normalization

Optional flash-attn

Inference falls back to PyTorch SDPA without it. The README points at a specific flash-attn 2.7.4.post1 wheel for torch 2.6 / CUDA 12 / Python 3.10 / cxx11abiFALSE on Linux x86_64—only install a wheel that matches your ABI.

Step 3: Download weights

pip install "huggingface_hub[cli]"
hf download inclusionAI/Ming-3.0-tts-0.5B --local-dir Ming-3.0-tts-0.5B

In mainland China, ModelScope is usually faster (README):

pip install modelscope
modelscope download --model inclusionAI/Ming-3.0-tts-0.5B --local_dir Ming-3.0-tts-0.5B

Replace 0.5B with tiny for the MoE checkpoint. The 0.5B layout includes model.safetensors, campplus.onnx, tokenizer files, and config.json (model_type: dense). Tiny uses sharded weights plus model.safetensors.index.json.

Step 4: Preflight (no full weight load)

python tools/preflight.py --model_path /path/to/Ming-3.0-tts-0.5B
# later, for tiny:
python tools/preflight_tiny.py --model_path /path/to/Ming-3.0-tts-tiny

Use this before a long download finishes copying, or after you move checkpoints between machines.

Step 5: Zero-shot voice clone (0.5B)

Official CLI (from README / infer.py docstring):

python infer.py \
  --model_path inclusionAI/Ming-3.0-tts-0.5B \
  --task TTS \
  --language_id Chinese \
  --text "傍晚的风从山口吹过来，远处的云慢慢染成了金色。" \
  --prompt_wav_path data/voice_presets/voice_audio/lingguang.wav \
  --prompt_text "诶，你今天有空吗？我们能不能聊聊这件事啊？" \
  --use_spk_emb \
  --output output/tts.wav

Same call from Python:

from ming_tts import MingTTS

model = MingTTS("inclusionAI/Ming-3.0-tts-0.5B")
model.synthesize(
    task="TTS",
    language_id="Chinese",  # use English for English text
    text="傍晚的风从山口吹过来，远处的云慢慢染成了金色。",
    prompt_wav_path="data/voice_presets/voice_audio/lingguang.wav",
    prompt_text="诶，你今天有空吗？我们能不能聊聊这件事啊？",
    use_spk_emb=True,
    output_path="output/tts.wav",
)

Useful CLI defaults from infer.py (do not change unless you know why):

Flag	Default	Role
--device	cuda:0	CUDA device
--seed	1895	Determinism helper
--cfg	2.0	Classifier-free guidance scale
--sigma	0.25	Flow-matching noise
--temperature	0.0	Sampling temperature
--max_length	50	Semantic length per fragment
--max_decode_steps	1000	Decode cap

For English cloning, set --language_id English and supply an English prompt_text that matches the reference audio.

Step 6: Freeform delivery (no reference recommended)

FREEFORM takes a natural-language instruction. The README says both models default to generation without reference audio; adding a reference is not recommended. Do not combine freeform with voice design, built-in IP, emotion, dialect, or attribute controls in the same call.

model.synthesize(
    task="FREEFORM",
    text="The old radio crackled softly as the storm moved across the valley.",
    instruction="Speak in a warm, intimate storytelling voice, with a gentle pace and a hint of nostalgia.",
    use_zero_spk_emb=True,
)

CLI shape:

python infer.py \
  --model_path inclusionAI/Ming-3.0-tts-0.5B \
  --task FREEFORM \
  --text "The old radio crackled softly as the storm moved across the valley." \
  --instruction "Speak in a warm, intimate storytelling voice, with a gentle pace and a hint of nostalgia." \
  --use_zero_spk_emb \
  --output output/freeform.wav

Step 7: Paralinguistic tags

Tags are part of the text, not separate controls. Official vocabulary in frontend/toolkit.py:

[Breathing], [Cough], [Sigh], [Laughter], [Surprise-ah], [Surprise-oh], [Dissatisfaction-hnn], [Uhm], [Confirmation-en], [Question-ei], [Question-ah], [Question-en], [Question-oh], [Question-huh].

Example (README cookbook):

model.synthesize(
    task="TTS",
    text="[Sigh]雨还是没有停，[Cough]我们恐怕只能把活动改到室内了。",
    prompt_wav_path="data/voice_presets/voice_audio/lingguang.wav",
    prompt_text="诶，你今天有空吗？我们能不能聊聊这件事啊？",
    use_spk_emb=True,
)

The text frontend protects these tags so normalization does not turn [Laughter] into punctuation soup. Still: avoid stuffing many tags into one sentence if stability matters—the README limitations section notes multi-tag lines trail single-tag quality on NVBench.

Step 8: Emotion, attributes, dialect, voice design, built-ins

These are separate tasks. Values below are from tts_tasks.py for the 0.5B CLI.

Emotion

Allowed: 高兴, 悲伤, 愤怒, 恐惧, 厌恶, 惊讶, 中性.

model.synthesize(
    task="EMOTION",
    text="所有测试都顺利通过了，我们终于可以把这个好消息告诉大家！",
    controls={"emotion": "高兴"},
    prompt_wav_path="data/wavs/emotion_prompt.wav",
    use_spk_emb=True,
)

Speed / pitch / volume (BASIC)

• speed: 慢速 / 中速 / 快速
• pitch, volume: 低 / 中 / 高

model.synthesize(
    task="BASIC",
    text="今晚的观测将在云层散开后开始，请耐心等待下一次通知。",
    controls={"speed": "慢速", "pitch": "中", "volume": "中"},
    spk_emb_path="/path/to/speaker_embedding.pt",
    use_spk_emb=True,
)

Dialect (DIALECT)

0.5B CLI values: chuanyu dialect, cantonese. This task does not take language_id.

model.synthesize(
    task="DIALECT",
    text="今日天气几好，我哋食完饭一齐去海边行下啦。",
    controls={"dialect": "cantonese"},
    prompt_wav_path="data/wavs/yue_prompt.wav",
    use_spk_emb=True,
)

Voice design (VOICE_DESIGN)

Describe the voice; no reference audio:

model.synthesize(
    task="VOICE_DESIGN",
    text="冰川在漫长岁月中缓缓移动，也悄悄记录着气候变化的痕迹。",
    controls={"style": "成熟沉稳的男性纪录片旁白，吐字清晰，节奏舒缓，语气理性而有厚度。"},
    use_zero_spk_emb=True,
)

Built-in voices (IP)

English premium names in code: US_Emma, US_James, UK_George, UK_Charlotte. The README also recommends Chinese voices such as 灵小柔 and 灵楷 (full catalog in cookbooks/instruction_en.md / cookbooks/instructions.md).

model.synthesize(
    task="IP",
    text="The garden will remain open until sunset, provided the weather stays clear.",
    controls={"ip": "US_James"},
    use_zero_spk_emb=True,
)

Multilingual

For German / Spanish / French / Korean / Japanese, use task MULTILINGUAL (aliases to the TTS path) with an explicit language_id (ja / Japanese, etc.). Short codes and full names both work. Japanese with kanji bypasses Chinese/English text normalization so kana is not mangled (preserve_multilingual_text in tts_tasks.py).

Step 9: Tiny MoE + podcast dialogue

Separate environment (README):

conda create -n ming-tiny python=3.10.15 -y && conda activate ming-tiny
pip install -r requirements-tiny.txt
# PyTorch/torchaudio 2.7.1+cu118 and transformers==4.46.3 per README

One-click scripts:

bash examples/one_click/run_seed.sh
MODEL=/path/to/Ming-3.0-tts-tiny OUT=outputs/yue.wav bash examples/one_click/run_dialect.sh

Python API (ming_tiny.MingTinyTTS). Defaults documented in the README for generate(): cfg_scale=2.0, temperature=0, flow_steps=10, sigma=0.25, seed 1234 (1235 for podcast):

from ming_tiny import MingTinyTTS

tts = MingTinyTTS.from_pretrained("inclusionAI/Ming-3.0-tts-tiny", device="cuda:0")

tts.generate(
    task="seed",
    text="傍晚的风从山口吹过来，远处的云慢慢染成了金色。",
    prompt_wav="data/voice_presets/voice_audio/lingguang.wav",
    prompt_text="诶，你今天有空吗？我们能不能聊聊这件事啊？",
    target_language="Chinese",
    output_path="outputs/seed.wav",
)

tts.generate(
    task="podcast",
    text="speaker_1: 你最近是不是又去那家面馆了？\nspeaker_2: 对啊，排了半个小时的队，不过真的值得。",
    prompt_wav=[
        "data/voice_presets/voice_audio/lingguang.wav",
        "data/voice_presets/voice_audio/db30.wav",
    ],
    prompt_text=[
        "诶，你今天有空吗？我们能不能聊聊这件事啊？",
        "感谢你的认可。",
    ],
    output_path="outputs/podcast.wav",
)

Tiny task names are lowercase (seed, paralinguistic, podcast, …). See the README table for which tasks need reference audio vs instruction / dialect controls. Tiny dialect labels in the README one-click docs use Chinese forms (川渝话 / 广粤话); the 0.5B CLI uses the English strings above—match the API you call.

0.5B vs tiny: API map

Keep this table nearby when you port a recipe between models. Names differ; capabilities mostly overlap except podcast.

Ability	0.5B (ming_tts.MingTTS / infer.py)	tiny (ming_tiny.MingTinyTTS / infer_tiny.py)
Zero-shot clone	task="TTS" + prompt_wav_path + prompt_text + use_spk_emb	task="seed" + prompt_wav + prompt_text + target_language
Freeform	task="FREEFORM" + instruction + use_zero_spk_emb	task="freeform" + instruction (omit prompt wav)
Paralinguistic	inline tags inside TTS text	task="paralinguistic" (or tags per tiny docs)
Emotion / BASIC / dialect / IP / design	uppercase tasks + controls={...}	lowercase twins; dialect labels may be Chinese forms in one-click scripts
Multilingual	MULTILINGUAL + language_id	multilingual + target_language
Multi-speaker	not available	task="podcast" with parallel prompt_wav / prompt_text lists
Preflight	tools/preflight.py	tools/preflight_tiny.py

infer.py uppercases --task and accepts aliases listed in _TASK_ALIASES (SEED→TTS, VOICE_DESIGN→STYLE, FREEFORM→STYLE, and so on). Prefer the names in the README cookbook examples so your scripts match demos on the project site.

Architecture in one paragraph (why tasks are exclusive)

Text and task-specific control tokens condition the LM; a DiT patch head plus audio tokenizer produce the waveform. Structured tasks build an ordered caption (Chinese or English field schema in build_structured_instruction) that was part of SFT. Mixing emotion + freeform + dialect in one request would produce a caption the checkpoint was never trained to interpret, so the library rejects cross-task controls instead of silently ignoring them. That is why this guide runs separate synthesize / generate calls per mode.

Reproducibility knobs

For 0.5B, infer.py calls seed_everything(1895) by default (random, numpy, torch, cuda, and sets cudnn.deterministic=True). Flow defaults --cfg 2.0, --sigma 0.25, --temperature 0.0 bias toward stable rather than exploratory sampling. Tiny’s README documents generate() defaults including seed 1234 (podcast 1235) and flow_steps=10. When you file a quality bug upstream, include: model id + commit, task name, full text, instruction/controls, prompt wav hash if any, seed, cfg/sigma/temperature, and whether TN was on.

Checklist before you ship audio

1. Consent and labeling. Voice cloning and character IPs are for research and legitimate creative use only (project Usage Disclaimer). Label synthetic speech when listeners could mistake it for a real person.
2. Pin the Hub revision. Prefer hf download … --revision <commit> (same idea as other local stacks) so main cannot silently swap weights under you.
3. Separate envs. Never install requirements.txt and requirements-tiny.txt into one environment.
4. One task per call. If you need emotional Cantonese with laughs, plan a pipeline of specialized calls or accept that some combinations are unsupported.
5. Listen on headphones for dialect and multilingual SIM issues called out in Limitations before you put the audio in a product path.

Troubleshooting FAQ

pynini fails to install. Use conda-forge as the README recommends, or pass --no_text_normalization / skip TN in the Python constructor (text_normalization=False via the CLI flag path).

Japanese output looks wrong / kanji mishandled. Set an explicit non-zh/en language_id so text normalization does not treat kanji as Chinese.

Dialect call ignores language_id. Expected: DIALECT does not use a language ID (tts_tasks.py warns and ignores it).

Controls from two tasks in one call. Rejected by design. Run separate synthesizes.

Need more VRAM headroom. Official testing cites H800-80GB / H20-96G for 0.5B and recommends H800 for tiny. If you are on smaller GPUs, check the project’s issues/discussions rather than assuming a quantization path exists in the first release.

Speaker similarity weak on new languages. Documented limitation: neither model tops the SIM leaderboards on most of the five new languages; French SIM is called out explicitly in Limitations.

flash_attn import errors after a random wheel install. Uninstall it and rely on SDPA, or install only the ABI-matched wheel the README links for torch 2.6 / cu12 / cp310 / cxx11abiFALSE. A mismatched wheel is worse than no flash-attn.

CLI --prompt_wav_path with multiple files. infer.py accepts nargs="+"; a single path is unwrapped to a string before synthesize. Podcast-style multi-prompt lists are a tiny concern—use infer_tiny.py / MingTinyTTS there.

Hub id case. Always write inclusionAI/Ming-3.0-tts-0.5B (capital B). Lowercase works via redirect today but is not the canonical id returned by the Hugging Face API.

Want cloud-free agents that also need STT? Ming is synthesis-only. On Apple platforms, pair with SpeechAnalyzer; on CUDA boxes, keep a separate ASR model in your stack rather than stretching Ming beyond the README.

Misuse / cloning real people. Follow the project’s Usage Disclaimer: do not impersonate without consent; label synthetic speech where it could be mistaken for a real recording.

Quality and leaderboard context

Treat leaderboard ranks as snapshots. Artificial Analysis numbers above are from the README’s October 2026 table. Seed-tts-eval, NVBench, dialect CER/ACC, and emotion tables are published as images and HTML tables in the README Performance section—use those pages when you need exact WER/SIM figures for a paper or procurement note rather than copying stale ranks from a secondary summary.

Demos and sample audio: Blog & Demos. End-to-end notebook: cookbooks/cookbook.ipynb.

What to do next

1. Clone the repo, install requirements.txt, download Ming-3.0-tts-0.5B.
2. Run tools/preflight.py, then the official infer.py TTS clone command with the bundled lingguang.wav preset.
3. Try one FREEFORM and one tagged TTS line so you see delivery control vs paralinguistics.
4. Only then create the tiny conda env if you need podcast.

If you are wiring speech into a larger agent stack, pair synthesis here with Gemini 3.6 Flash for planning text, or keep an eye on Copilot-side tooling costs via GitHub Copilot AI credits billing. For time-series rather than audio, we also have a Timestral CPU forecast guide.

Sources

• inclusionAI/Ming-3.0-tts (README, LICENSE, requirements, infer.py, tts_tasks.py, frontend/toolkit.py)
• Hugging Face: Ming-3.0-tts-0.5B
• Hugging Face: Ming-3.0-tts-tiny
• ModelScope 0.5B / tiny
• Artificial Analysis TTS (ranks cited via the project README)
• Blog & demos