---
license: apache-2.0
language:
- zh
base_model:
- hexgrad/Kokoro-82M-v1.1-zh
pipeline_tag: text-to-speech
tags:
- coreml
- kokoro
- apple-silicon
- ane
---

# Kokoro ANE v3 — Mandarin

Mandarin speech with `zf_001`, using a hybrid ANE + GPU pipeline on
macOS 15 / iOS 18 or newer. Albert and masked decoder request CPU+ANE; native source
and STFT use CPU Accelerate; the optimized generator requests CPU+GPU.

This is a full transfer of the separate v1.1-zh checkpoint into the optimized
generator graph, including learned Snake alphas and folded reciprocals. Its
Albert, decoder, source parameters, voice and vocabulary are Mandarin-specific.
The pinned base dependency is `ANE-zh`.

The base model and pretrained weights are **[hexgrad/Kokoro-82M-v1.1-zh](https://huggingface.co/hexgrad/Kokoro-82M-v1.1-zh)**, created by [hexgrad](https://huggingface.co/hexgrad). This variant converts and optimizes those weights for Core ML.

## FluidAudio SDK v0.17.6

Use `KokoroAneManager(version: .v3)` for English,
`KokoroAneManager(variant: .japanese, version: .v3)` for Japanese, or
`KokoroAneManager(variant: .mandarin, version: .v3)` for Mandarin.
All three accept native text and variant voices. Existing callers retain
`.legacy`. See [SDK usage, voices and platform limits](https://github.com/FluidInference/FluidAudio/blob/d7931323eebea4e39874b0d2e75d1b0e90e13084/Documentation/TTS/KokoroAne.md).
Requires macOS 15 / iOS 18; physical iOS inference remains unvalidated.

The SDK pins model release `6c0750dd02ef9d981fb82f147d784a3f171755ee` and base
revision `006395f65025af251858b1ab0a7178a6a1e73f9f`, adopting fp32
`KokoroProsody_v2` and COLA-corrected `KokoroTail_v2`. The bundled standalone
conversion runtime and its historical measurements below are separate from this
SDK integration. This documentation update does not change model bytes or pins.

### SDK compute routing and selected measurements

Hybrid is **not `.all` or ANE-only**. Albert, PostAlbert, Alignment, Prosody and
masked decoder request `.cpuAndNeuralEngine`; the fast generator requests
`.cpuAndGPU`; native source/STFT runs on CPU/Accelerate. Fallback Vocoder requests
CPU+ANE, Noise/Tail CPU+GPU. Core ML chooses actual placement within each policy.

| Policy | English | Japanese | Mandarin |
| --- | ---: | ---: | ---: |
| Current hybrid | **49.45 ms** | **35.85 ms** | **53.97 ms** |
| CPU+ANE throughout | 511.40 ms | 474.45 ms | 584.19 ms |
| `.all` throughout | SIGABRT | SIGABRT | SIGABRT |
| CPU+GPU throughout | SIGABRT | SIGABRT | SIGABRT |

Apple M5 Pro, 24 GiB, macOS 27.0 (26A428); October 7, 2026 (Toronto).
Median of five calls after two warmups on one selected demo input per language;
3.350 / 3.050 / 3.675 seconds of output. Timer covers prepared tokens/style to
complete PCM, excluding text processing, loading and WAV IO. Identical inputs
per policy, serial isolated processes, native DSP unchanged. These are local
exploratory checks, not corpus or cross-device results. Global overrides were
applied in a local harness; the public v3 API retains its fixed hybrid routing.
Both `.all` and CPU+GPU aborted during Prosody on the second warmup with Apple's
`GPURNNOps: JIT not supported`. CPU+ANE permits CPU fallback; it is not ANE-only.

Live-demo screenshots instead time raw text through complete audio and showed
57.8–79.8 ms in selected serial runs. Their 1.88× / 5.29× / 2.25× speedups versus
legacy are individual observations, not a benchmark average. Concurrent demo
mode also includes shared-resource contention.
See [inputs, ranges, protocol and raw records](https://github.com/FluidInference/FluidAudio/blob/d7931323eebea4e39874b0d2e75d1b0e90e13084/Documentation/TTS/Benchmarks.md#kokoro-ane-v3-selected-m5-pro-measurements).

Compute plans prefer ANE for static Albert/decoder and GPU for the generator,
but plan estimates and system-wide asitop power samples do not establish actual
per-process execution. See [ANE profiling and telemetry limits](https://github.com/FluidInference/FluidAudio/blob/d7931323eebea4e39874b0d2e75d1b0e90e13084/Documentation/ANE_Profiler.md#kokoro-ane-v3).

## Initial standalone conversion checks

Two short real inputs with 1.975 / 2.475 seconds of audio: warm medians
**24.48 / 28.42 ms**, versus **111.05 / 135.42 ms** for the published baseline.
Apple M5 Pro, 24 GiB, macOS 27.0; optimized Swift; three discarded warmups,
five measurements per input/model, rotating serial order. Tokens/style to PCM;
G2P, model loading and file IO excluded. This is a bounded local development
check, not a corpus or cross-device benchmark.

The Swift integration and numerical checks pass. With reference decoder
features, native source plus generator relative waveform RMSE is 0.07762 / 0.07649.
Full-chain phase-sensitive waveform statistics are reported separately and
are not a perceptual equivalence claim. A pinned multilingual Whisper base
model recovered both sentences from baseline and candidate audio, allowing
punctuation and Chinese orthographic variation; no transcript prompt was used.
See `validation/` for raw measurements, transcripts and fidelity results.

## Download and run

Set `KOKORO_REVISION` to the 40-character Hugging Face commit containing this
bundle. The helper verifies its manifest and downloads the pinned seven-stage
base dependency from the same repository.

```sh
python tools/download-fast-pipeline.py --revision "$KOKORO_REVISION" \
  --language zh --output-dir assets
swift run --package-path runtime -c release kokoro-fast-check \
  assets/base assets/fast assets/decoder
python tools/validate-fast-pipeline.py --models-dir assets/fast
```

Install the `conversion/` project's `multilingual` extra to prepare arbitrary
text with `tools/prepare-fast-input.py --assets-dir assets --text 'TEXT' --output input.json`.
The output supplies `ids` and a 256-value `style` for
`KokoroFastPipeline.synthesize(inputIds:style:speed:)`. Voice data is little-endian
Float32 `[510,1,256]`; the helper selects row `len(phonemes)-1`. Misaki 0.9.4 supplies
G2P; Japanese uses UniDic-lite 1.0.8. Split long passages into sentences. The initial standalone checks used the listed default voice; later SDK checks
cover alternate voices. Mixed Mandarin/English text is outside these checks.

Both `.mlpackage` and `.mlmodelc` are included. Use downloader `--format mlpackage`
to recompile on the deployment platform; compiled bundles were built on macOS
27.0. Above 64 tokens, the runtime uses dynamic Albert. Above 200 acoustic
frames (5 seconds), it uses the original vocoder. Output is 24 kHz PCM; inputs
are limited to 512 tokens and 2,000 predicted acoustic frames.

The package contains full conversion/runtime sources, pinned vocabulary and
voice, validation fixtures and actual runtime WAVs in `samples/`. See
`conversion/docs/multilingual-fast-pipeline.md` for reproduction and scope.

## Provenance

Checkpoint/voice pin is in `language.json`; all release files are hashed in
`manifest.json`. Base models use `FluidInference/kokoro-82m-coreml` revision
`006395f65025af251858b1ab0a7178a6a1e73f9f`. The optimized graph derives from
[mattmireles/kokoro-coreml](https://huggingface.co/mattmireles/kokoro-coreml/tree/9183566f294ca3f31a63fd2767cf5848bfebfd50)
(Apache-2.0), adapted to the selected checkpoint. Kokoro weights are Apache-2.0;
the original conversion is MIT. Retain `NOTICE`, `mattmireles-LICENSE` and
`conversion-LICENSE` when redistributing.