ZONOS3-Mini Local Setup: WebGPU, MLX and Common Errors

ZONOS3-Mini can generate speech locally in a WebGPU browser or through native servers, including MLX on Apple Silicon. Start with the browser for a quick listen, then move to a local server if your application needs features the browser lacks. The important choice is the runtime, not just the model.

Zyphra's release overview describes an open-weight, multilingual text-to-speech model with voice cloning and delivery controls. This is a documentation-based setup guide, not a listening test or a claim that every supported device performs equally well.

Choose the ZONOS3-Mini runtime before downloading

The upstream repository separates deployment into four paths. They share a studio and HTTP interface, but that does not make their capabilities identical.

Environment	Starting point	Main reason to choose it
Browser with WebGPU	Hosted local playground	Try synthesis without installing a server
Apple Silicon Mac	MLX server	Run locally with native Apple GPU support
Linux with NVIDIA GPU	CUDA server using Mini-SGLang	Integrate a GPU-backed local service
CPU, CUDA, Metal or Vulkan	C++/ggml server	Avoid Python at runtime

For the CUDA path, the documented prerequisites include CUDA 12.8 and a project-pinned Python 3.12 environment. The default PyTorch weight download is about 9 GB. Do not treat the phrase 100 million active parameters as a download size or a memory requirement: the backbone has about 800 million total parameters, and audio processing adds other networks.

This distinction matters for product planning. A small amount of computation per generated token can help latency without making the complete application a tiny download.

Start with WebGPU, but check its limits

Open Zyphra's local browser playground and begin with a supplied voice and a short sentence. Use your own recording, or a speaker's recording you have permission to use, only after the basic generation path works. That separates a synthesis problem from a reference-audio problem.

The browser runs inference locally, but it still needs to fetch model assets. The WebGPU runtime documentation describes roughly 1 GB for the initial backbone and default decoder in its export path. Reference uploads add substantially more assets, around 2.8 GB for the encoder and teacher, plus the speaker encoder. These are documented asset estimates, not a measurement of your browser's memory use.

Browser support also has a sharp boundary. Without WebGPU, or when the GPU adapter's limits are insufficient, initialization fails. The browser runtime does not provide speech recognition, text normalization or accent adapters. Editing with a supplied transcript is different from automatically transcribing a recording, so a visible editing interface should not be read as evidence that every editing workflow works locally in the browser.

Run the MLX server on Apple Silicon

With Git, uv and the Hugging Face CLI available, use the public repository and the setup documented in the MLX instructions:

git clone --recurse-submodules https://github.com/Zyphra/ZONOS3-Mini.git
cd ZONOS3-Mini
uv sync --locked --package zonos3-mlx
hf download Zyphra/ZONOS3-Mini --include 'gguf/*' --local-dir servers/ggml
servers/mlx/scripts/serve.sh

The launcher serves the interface at http://127.0.0.1:1919/. Start there rather than adding a reverse proxy or exposing the service to the internet before generation works. The model files are public; the repository says a Hugging Face token is not required.

Keep the download directory intact. MLX discovers companion files beside the backbone, including the decoder and speaker components. Downloading one attractive-looking GGUF file is not equivalent to installing the complete speech pipeline.

The separate speech-recognition environment is optional for ordinary synthesis. It becomes relevant for workflows that transcribe clips or verify edits. Avoid installing every optional component to diagnose a basic text-to-speech failure: establish one working voice and sentence first, then add the feature you actually need.

Diagnose errors by capability, not by model name

For an application integration, inspect the local server's /v2/capabilities before enabling controls. The API documentation is the reference for requests, rather than assuming that an OpenAI-compatible speech endpoint makes the entire service interchangeable with another provider.

A missing transcript workflow in the browser is not necessarily a model failure. The runtime explicitly lacks speech recognition and can return a 503 for operations that require it. Switch to a configured native server or supply the transcript for a supported editing workflow instead of repeatedly retrying the same unsupported operation.

On MLX, a requested decoder that the server does not serve produces a 400. Read the available decoders from capabilities and request one of those, rather than copying a decoder identifier from another installation. The response's X-Decoder header helps establish which decoder actually produced the audio.

For evaluation, use one short application-specific script across your candidate runtimes: include names, numbers and the language mix your users will actually hear. Compare cold startup separately from generation after loading. Otherwise, a benchmark can quietly turn a large initial download into an apparently slow model, or hide that download entirely.

Choose the smallest runtime that supports your real workflow. Browser inference is compelling when it removes a server dependency, but a missing transcription or normalization step can move that complexity back into your application. A working product depends on the whole speech path, not the size printed beside the backbone.

I’m Paras. I work at the intersection of AI, engineering and distribution.

I help technical teams turn implementation details and product trade-offs into clear stories developers can use.

Book a 30-minute call