kokoro-coreml

Kokoro 82M TTS -- Surgically Optimized for Apple Silicon

30 seconds of speech in 379 ms on a Mac Studio. 2x faster than MLX on the same hardware. Running on the Apple Neural Engine.

Kokoro-82M compiled to Core ML and cut into five models, each running on the processor that's best at its job. On-device, offline, no API keys, no cents-per-character. This repo is the pre-converted .mlpackage files; you load them with a Swift MLModel(contentsOf:) call.

Source, exporters, Swift runtime: github.com/mattmireles/kokoro-coreml

The numbers

Median warm wall time for one full synthesize call -- tokenize in, 24 kHz PCM out. Measured June 2026, counterbalanced harness in the GitHub repo.

That's 12-79x realtime across the lineup. The M2 Studio synthesizes 30 seconds of audio in 379 ms, but the M1 Mini is the number that matters -- the cheapest Apple Silicon Mac you can buy turns text into speech 14x faster than you can listen to it.

vs MLX

Same machines, same utterances, same voice (af_heart), same timing boundary, median of warm calls. Comparator: Blaizzy/mlx-audio 0.4.3 at commit 862dfbe, running mlx-community/Kokoro-82M-bf16.

Faster on every bucket, on every machine. The gap is widest on the newest silicon -- the Neural Engine keeps scaling while a GPU-bound port doesn't. (The pinned MLX version fails 3-second clips with a broadcast-shape error; no time to report.)

This is not a knock on MLX -- it's a fine framework. It's the surgery. A monolithic port runs wherever the scheduler drops it. A dissected pipeline runs each stage where it belongs.

On iPhone

Same .mlpackage files, deployed to phones (June 2026, iOS 26.5, median of 5 warm calls). Comparator: mlalma/kokoro-ios 1.0.8, the MLX Swift port of Kokoro -- the Python mlx-audio above doesn't run on iOS. Its timing includes its Misaki G2P pass; ours starts from token IDs.

Faster on every bucket on the A17 Pro (4-4.5x realtime). On the 4 GB iPhone 12 Pro it's split: MLX takes the middle buckets, but the memory watchdog kills it on 30-second clips -- this pipeline synthesizes them in 12.3 s. One disclosure: the iPhone ANE compiler (A14 and A17 Pro) rejects the full-ANE plan that every M-series Mac runs (ANECCompile() FAILED), so iPhone rows use the staged policy -- decoder-pre on the ANE, the other stages on CPU+GPU.

Cold start takes a few seconds (Core ML compiles on first load); everything after is steady-state. Benchmarks drift with macOS and hardware -- rerun them on your target machine with the harness in the GitHub repo before you ship a claim of your own.

Why surgery?

Apple Silicon isn't one processor. It's three -- CPU, GPU, and the Neural Engine (ANE) -- each built for different work. The ANE devours fixed-shape convolutions at a fraction of the GPU's power draw. But it has rules: no dynamic shapes, no data-dependent control flow. Shove a whole TTS model through Core ML and the scheduler quietly dumps you on the CPU.

So we cut the pipeline at the joints:

                  ┌────────────────────────────────┐
"Hello world" ──▶ │  DURATION  (kokoro_duration_t*) │ ◀── CPU/GPU
                  │  BERT + LSTMs                   │     branching, variable lengths
                  └──────────────┬─────────────────┘
                                 ▼
                  ┌────────────────────────────────┐
                  │  ALIGNMENT  (Swift)             │ ◀── CPU
                  │  Matrix from durations, ~50 LoC │     small, data-dependent logic
                  └──────────────┬─────────────────┘
                                 ▼
                  ┌────────────────────────────────┐
                  │  F0 / NOISE  (kokoro_f0ntrain)  │ ◀── GPU
                  │  Pitch + aperiodicity contours  │     fixed-shape dense math
                  └──────────────┬─────────────────┘
                                 ▼
                  ┌────────────────────────────────┐
                  │  DECODER PRE (kokoro_decoder_pre)│ ◀── ANE
                  │  Text features → decoder state  │     fixed-shape convolutions
                  └──────────────┬─────────────────┘
                                 ▼
                  ┌────────────────────────────────┐
                  │  HARMONIC SOURCE  (Swift/vDSP)  │ ◀── CPU
                  │  hn-NSF sine + noise excitation │     cheap DSP, exact phase
                  └──────────────┬─────────────────┘
                                 ▼
                  ┌────────────────────────────────┐
                  │  GENERATOR (kokoro_decoder_     │ ◀── GPU
                  │  har_post) convs + iSTFT        │     runs at the real utterance length
                  └──────────────┬─────────────────┘
                                 ▼
                            24 kHz Audio

Decoder-pre runs on the ANE (250 of 250 ops in its compute plan at 3, 15 and 30 s); duration, pitch and the generator run on CPU+GPU, where they are fastest; one DSP stage runs in Swift with double-precision phase accumulation. The generator exceeds the ANE's tensor-size limits, so it runs on the GPU as one flexible-length program that computes only the frames the utterance needs.

Redesign the inference pipeline, not the model. That's where the 2x over MLX comes from -- not by fighting the GPU, but by routing around it.

What's in the download

Five fixed-duration buckets: 3s, 7s, 10s, 15s, 30s. Pick the smallest bucket that fits your predicted utterance. That's the whole strategy.

The three multifunction packages plus kokoro_decoder_har_post_range serve every bucket and duration shape in 178 MB instead of ~840 MB of per-bucket packages. Load a function with MLModelConfiguration.functionName; the GitHub repo's KokoroPipeline does this automatically when the packages are present.

The alignment matrix and the hn-NSF harmonic source are not models -- they're a few hundred lines of Swift/vDSP in the GitHub repo's KokoroPipeline.

Hosted manifests and pinning

Two hosted manifests list every file to download, with bytes and SHA-256. Every path is relative to this repo's root, so a file's URL is https://huggingface.co/mattmireles/kokoro-coreml/resolve/<commit>/<path>.

Current full manifest SHA-256: 9af2fd5a5f0cb41a78ff80355b6cba152bbcaed0508165d2d815b1d4c78ce150.

Pin the commit that published the manifest -- the commit that last changed HostedManifest.json / sdk/full/HostedManifest.json (and this card) in the Files history. Every listed file is byte-identical at that commit and the release pipeline verifies it there before announcing it. hf_artifact_revision inside KokoroRuntimeManifest.json is the older commit where the models were verified; it predates the manifests and is not a hydratable pin. Check any pin with python scripts/prepare_hf_sdk_metadata.py --verify <commit> from the GitHub repo.

G2P assets (g2p/)

us_lexicon_cache.json, g2p_vocab.json, G2PEncoder.mlmodelc/, and G2PDecoder.mlmodelc/ are the minimal asset set for the GitHub repo's KokoroG2P library (KokoroEnglishFrontend(assetsDirectory:)): a Misaki lexicon plus a BART G2P fallback for out-of-vocabulary words. They are copied byte-for-byte from FluidInference/kokoro-82m-coreml at commit c032f6d05d2a58179b817201a443fbbcef06f962, which is released under Apache 2.0.

Usage (Swift SDK)

This section is the Swift SDK contract for the matching Git release commit. The KokoroTTS SDK loads the starter profile (top-level manifests, with per-profile metadata under sdk/starter/). The full profile is for KokoroPipeline + KokoroG2P apps. If you are using an older HF snapshot, use the low-level KokoroPipeline snippets from that snapshot instead.

import KokoroTTS

let resources = KokoroResourceProvider.directory(bundleURL)
let tts = try await KokoroTTS.load(resources: resources)
try await tts.prewarm(text: "Hello world.", voice: .afHeart)

let audio = try await tts.synthesize("Hello world.", voice: .afHeart)
let samples = audio.samples        // 24 kHz mono Float PCM
let buffer = try audio.makePCMBuffer()

prewarm proves the duration-to-audio path selected by the supplied text. Full-profile clients using several utterance-length buckets should call it with representative text for each expected path.

The SDK is in the GitHub repo's swift-tts package. It owns raw-text preparation, Misaki phonemization, Botnet-compatible chunking, model loading, and AVFoundation PCM buffer creation. Current hosted SDK contract: iOS 18.0+, macOS 15.0+, sample rate 24000, starter voice af_heart, fixed duration token size 128, full buckets 3,7,10,15,30, max caller chunk tokens 450, voice embedding dimension 256.

Build a starter bundle:

python3 scripts/download_models.py \
  --repo-id mattmireles/kokoro-coreml \
  --revision <hf-artifact-revision> \
  --sdk-profile starter \
  --manifest-out /tmp/kokoro-download-manifest.json

node scripts/build_sdk_bundle.mjs \
  --profile starter \
  --compile-models 1 \
  --output /tmp/kokoro-sdk-starter \
  --repo-id mattmireles/kokoro-coreml \
  --revision <hf-artifact-revision> \
  --download-manifest /tmp/kokoro-download-manifest.json

node scripts/validate_sdk_bundle.mjs /tmp/kokoro-sdk-starter

Downloaded-resource apps can hydrate the top-level starter HostedManifest.json with KokoroDownloadedModelStore. Pass expectedManifestSHA256 for the exact manifest bytes (current public starter digest: 8d1f6dfa4904a9a1183fb9dcd5a93ed841b22f2315a5e4d7928ef75992dbd5cd; pin the commit that published it, as above). Production apps must serve manifests over HTTPS. Bundled-resource apps can use KokoroResourceProvider.directory, .appBundle, or .packageBundle, and should supply a writable compiledModelsDirectory so compilation does not write into the app resource tree.

Previous snippets that used KokoroPipeline directly are now low-level examples. Keep them for benchmarking and graph work; use KokoroTTS for app integration.

Tensor shapes (3s bucket)

kokoro_duration_t128:
  in   input_ids       [1, 128]        int32     phoneme token IDs (padded)
  in   attention_mask  [1, 128]        float16
  in   ref_s           [1, 256]        float16   voice embedding
  in   speed           [1]             float16
  out  pred_dur        [1, 128]                  per-token frame counts
  out  t_en, d, s, ref_s_out                     encodings for downstream stages

kokoro_f0ntrain_t120:
  in   en [1, 640, 120]  s [1, 128]  mask [1, 1, 120]
  out  F0_pred [1, 240], N_pred [1, 240]

kokoro_decoder_pre_3s:
  in   asr [1, 512, 120]  f0 [1, 1, 240]  n_input [1, 1, 240]  ref_s [1, 256]  mask [1, 1, 120]
  out  x_pre [1, 512, 240]

kokoro_decoder_har_post_3s:
  in   x_pre [1, 512, 240]  ref_s [1, 256]  har [1, 22, 14401]  mask [1, 1, 240]
  out  waveform [1, 1, 72000]   -- 3s @ 24 kHz

mask marks the valid frames of a padded bucket (1 = real, 0 = padding) and is required. Everything is static and float16 except the optional flexible generator (kokoro_decoder_har_post_range, RangeDim, GPU only, macOS 15 / iOS 18). No dynamic ops. No non_zero kernels.

Requirements

• iOS 18.0+ / macOS 15.0+ for the drop-in raw-text KokoroTTS SDK
• Apple Silicon (M1+) or A15+ for Neural Engine acceleration
• macOS arm64 and x86_64 build targets are supported; Intel Macs run without ANE acceleration and should be treated as CPU/GPU Core ML targets
• watchOS is not supported in this SDK snapshot because the MisakiSwift/MLX raw-text dependency does not build for the watchOS SDK

License

Apache 2.0, inherited from Kokoro-82M. Ship it. Sell it. Fork it. The g2p/ assets are Apache 2.0 from FluidInference/kokoro-82m-coreml.

Credits

• @hexgrad -- Kokoro-82M weights, training, and the Apache release
• @yl4579 -- StyleTTS 2 architecture
• FluidInference -- the English G2P lexicon and BART G2P Core ML models in g2p/
• Apple's coremltools team -- for maintaining the PyTorch-to-Core ML path

---

Kokoro (心) -- Japanese for "heart."