ChatTTS_colab: a one-click WebUI for ChatTTS with streaming, voice sampling and role-play reading

The gap ChatTTS_colab fills between the model and a usable interface

Upstream ChatTTS is a text-to-speech model repository. Getting speech out of it means installing Python dependencies, downloading weights from Hugging Face, and writing your own inference loop before you hear a single sentence. ChatTTS_colab is the wrapper layer: a Gradio WebUI, a CLI, and an API file that sit on top of a pinned copy of the upstream project. The README describes it as one-click deployment with no complex installation, and the repository layout backs that up: webui_mix.py for the browser interface, cli.py for command-line use, api.py for programmatic calls, tts_model.py for the model glue, and llm_utils.py for the script generation used by the role-play mode.

The intended audience is people who want to hear ChatTTS output today rather than build a pipeline around it. The README lists four capabilities that the upstream repository does not ship as a product: streaming output, voice sampling (the README calls it 音色抽卡, drawing voice cards), long audio generation, and role-tagged reading where different characters in a script get different voices. A companion project, ChatTTS_Speaker, is linked for a curated speaker library with gender and age labels, and the README points to ModelScope and Hugging Face Spaces demos of that library. The wrapper is not a fork of the model. It is an application around it.

How the wrapper, the pinned ChatTTS copy and the normalisation layer fit together

The macOS instructions reveal the architecture more clearly than any diagram would. You clone ChatTTS_colab, then clone 2noise/ChatTTS inside it, check out commit e6412b1, and move the inner ChatTTS directory up so the model code lives at ./ChatTTS alongside webui_mix.py. That pinned commit is the dependency contract: the wrapper is written against one specific revision of the upstream model, not against a version range.

On top of that sits a text normalisation layer. requirements.txt lists cn2an, pypinyin, openai and WeTextProcessing, and the repository contains a zh_normalization directory. cn2an converts Chinese numerals to Arabic digits and pypinyin supplies pronunciation hints, which addresses the README's claim that numbers and mis-read punctuation get preliminary handling. The openai entry exists because the role-play mode can call a large language model to turn text into a script, and llm_utils.py is where that call lives. The inference path itself runs through tts_model.py, which webui_mix.py and cli.py both use, so the browser UI and the command line share one code path. Streaming is a property of that shared path rather than a separate mode.

Installing ChatTTS_colab on macOS with conda

The README gives an explicit macOS walkthrough. Create a Python 3.11 environment first, because the pinned ChatTTS revision and the normalisation packages are sensitive to interpreter version.

conda create -n "ChatTTS_colab" python=3.11
conda activate ChatTTS_colab

Then clone the wrapper and place the pinned model code inside it. The move dance exists because the upstream repository is named ChatTTS and would otherwise collide with the directory the wrapper imports from.

git clone git@github.com:6drf21e/ChatTTS_colab.git
cd ChatTTS_colab
git clone -q https://github.com/2noise/ChatTTS
cd ChatTTS
git checkout -q e6412b1
cd ..
mv ChatTTS temp
mv temp/ChatTTS ./ChatTTS
rm -rf temp

Install the macOS requirements and start the WebUI. The README notes that the model downloads automatically on first run and that the browser opens by itself.

pip install -r requirements-macos.txt
python webui_mix.py
# Loading ChatTTS model...

On Colab the README's route is shorter: open the notebook linked at the top of the repository, then use Runtime, Run all. When the log prints a line like Running on public URL: https://**********.gradio.live, that address is the public Gradio endpoint. Those are the only two install paths the README documents; there is no Docker or Linux section.

When the first run fails: model download, cache and the local fallback

The README's troubleshooting section is unusually honest about the most common failure. ChatTTS downloads its weights from Hugging Face on first run, and if that download is interrupted, the model does not retry by itself. The documented symptom is a FileNotFoundError pointing at a Vocos.pt file under ~/.cache/huggingface/hub/models--2Noise--ChatTTS/snapshots/. The fix is to delete the partial cache and run the WebUI again.

rm -rf ~/.cache/huggingface/hub/models--2Noise--ChatTTS
python webui_mix.py

If repeated downloads fail, the README offers a local path: copy the models directory out of the offline bundle into the project directory and point the loader at it. The flag names below are exactly as the README writes them.

python webui_mix.py --source local --local_path models

For slow downloads the README suggests the hf-mirror.com endpoint, credited to @padeoe, set through an environment variable before launching.

export HF_ENDPOINT=https://hf-mirror.com

This is the practical boundary of the project. Everything before the weights land on disk is handled for you; the download itself is a hard dependency on network access to either Hugging Face or a mirror.

Streaming, voice sampling and role tags in practice

The four advertised features are not independent. Streaming means audio starts playing while the rest of the utterance is still being generated, which matters for long text because waiting for a full render of a multi-minute passage is unpleasant. Voice sampling generates a batch of candidate voices so you can keep the ones you like; the repository ships slct_voice_240605.json, a saved selection dated 2024-06-05, which is what a saved voice set looks like on disk. Long audio generation is the mode where streaming and voice persistence pay off, since a single voice has to stay consistent across a long passage.

Role-tagged reading is the most opinionated feature. It splits a script across characters and assigns a voice per character, and it can call a language model to produce that script from plain text, which is why openai appears in requirements.txt. That dependency is worth noticing: the role-play path is the only part of the wrapper that expects an external API. If you only want single-voice synthesis, you never touch llm_utils.py, and the openai package sits unused. The README does not document which models the script generation was tested against, so treat that path as the least specified part of the tool.

What the wrapper does not solve

The repository has no licence file at the top level, even though the README's final section states that the project uses the MIT licence. That mismatch matters more than usual here, because the wrapper also vendors a pinned copy of 2noise/ChatTTS, whose own terms are not reproduced in this repository. If you plan to ship generated audio or redistribute the bundle, the licence situation for the model code and weights is something you have to check at the upstream source, not here.

Maintenance is the second constraint. The last push was on 2026-05-31, and the newest tagged release, v0.0.6, is from 2024-06-21, with the Windows offline bundles at v0.0.5 and v0.0.4 in June 2024. The gap between the release tags and the last commit means the offline bundles are not obviously rebuilt on every change. The README also documents no rollback procedure, no version pinning for the Python dependencies beyond the ChatTTS commit, and no Docker path, so reproducing a working environment on a new machine depends on the conda steps above still resolving. Finally, the project is a UI around a model: it does not add voice cloning of your own recordings, and the README never claims it does.

ChatTTS_colab against the upstream ChatTTS repository and its Spaces demos

The real alternative is 2noise/ChatTTS itself, and the difference is one of scope rather than quality. Upstream gives you the model, the tokenizer and a Python API; you decide how text is normalised, how voices are sampled and how audio is played. ChatTTS_colab gives you a Gradio interface, a CLI, an HTTP API file, a Chinese normalisation layer built on cn2an and pypinyin, and the four features above, at the cost of a pinned upstream commit you do not control. If you are embedding speech into your own service, the upstream package is the smaller dependency. If you want to evaluate voices by ear this afternoon, the wrapper is faster.

The README also links hosted demos of the separate ChatTTS_Speaker project on ModelScope and Hugging Face Spaces. Those are a different trade-off again: no installation at all, but a curated speaker library rather than your own sampling, and no local control over the model. The three options sit on a line from least setup to most control, and ChatTTS_colab is deliberately in the middle.

Editorial conclusion

Adopt ChatTTS_colab if you want a browser-based ChatTTS interface without assembling the upstream model, its tokenizer and its text normalisation yourself, and if you accept that the last push was on 2026-05-31 and the newest tagged release, v0.0.6, dates from 2024-06-21. Skip it if you need a maintained API surface, a documented licence for the bundled model weights, or anything beyond what the Gradio UI and cli.py expose. Before committing, verify that the ChatTTS commit pinned in the macOS instructions, e6412b1, still resolves, and confirm whether the offline bundle you download matches the current requirements.txt.

Frequently asked questions

Official sources

1. 6drf21e/ChatTTS_colab on GitHub
2. Issues
3. README
4. Releases