feat(tts): expose Kokoro CoreML compute units through the binding

[drakulavich]

Problem

KokoroAneManager already takes a computeUnits: argument, but the bridge constructs it with only variant:/defaultVoice: (FluidAudioBridge.swift:168), and the Rust entry point is init_kokoro(&self, default_voice, lang). So every Rust caller is pinned to KokoroAneComputeUnits.default, which puts Albert / PostAlbert / Alignment / Vocoder on the Neural Engine.

That is the right default on real Apple Silicon and fatal without an ANE. On a virtualised macOS guest — a GitHub-hosted macos-14 runner is one — the ANE is not exposed, and CoreML refuses to prepare exactly those stages.

Worth being precise about when that surfaces, because it is not at init. KokoroAneManager.initialize only runs store.loadIfNeeded(), the G2P assets and the voice packs — it never issues a prediction — and KokoroAneError.predictionFailed is thrown from exactly one place, KokoroAneSynthesizer.predict wrapping model.prediction(from:). So the model loads happily with its ANE configuration and the first synthesize is what fails:

Kokoro synthesize error: predictionFailed(stage: "vocoder", underlying:
  Error Domain=com.apple.CoreML Code=0 "Failed to prepare the model for predictions.
  ML program was KokoroVocoder and the function name was main."
  NSUnderlyingError=... "E5RT: Output rank has changed after reshaping espresso network
  for blob = anchor_classic_cpu (11)")

Not an asset problem: the same binary and voice synthesize fine on an M2 with the same staged bundle. The ASR path is unaffected because FluidAudioBridge.swift:401 sets cfg.computeUnits = .all for ASR, leaving CoreML free to pick CPU/GPU. Kokoro has no equivalent freedom from Rust.

Documentation/TTS/KokoroAne.md already documents the escape hatch (KokoroAneManager(computeUnits: .cpuAndGpu)) — this PR just plumbs it.

Change

• fluidaudio_initialize_kokoro gains a compute_units C string, parsed with FluidAudio's own TtsComputeUnitPreset(cliValue:) so spellings stay in one place. NULL/empty keeps the empirical mapping; an unrecognised value fails init rather than silently synthesizing on units the caller did not ask for.
• New KokoroComputeUnits enum (Default / AllAne / CpuAndGpu / CpuOnly) with FromStr + as_str, and init_kokoro_with_compute_units.
• init_kokoro keeps its signature and delegates on Default — no existing caller changes.
• examples/kokoro.rs takes the preset as an optional 4th argument.

Verification

M2, macOS 26.5.2, staged ANE bundle, am_michael, same sentence through all four presets:

preset	exit	output
default	0	24 kHz mono, 2.75 s, RMS 3593
all-ane	0	24 kHz mono, 2.75 s, RMS 3552
cpu-and-gpu	0	24 kHz mono, 2.77 s, RMS 4038
cpu-only	0	24 kHz mono, 2.75 s, RMS 3552

cargo test --lib passes, including two new tests. They cover what a Rust unit test honestly can: that as_str emits the literal kebab-case spellings transcribed from TtsComputeUnitPreset.swift at the pinned 0.14.8, that every alias init?(cliValue:) accepts also parses here, and that an unknown preset is rejected with an error naming both the bad value and the accepted spellings. The Swift parser itself cannot be executed from this crate — there is no Swift test target — so that table is manual sync, and the test says so rather than implying it is enforced. The literal assertion was mutation-checked: renaming as_str's cpu-and-gpu output fails the test.

One finding worth recording for other callers: on cpu-and-gpu CoreML writes E5RT "Data-dependent shapes were disabled" diagnostics to stdout (436 bytes in the run above) and falls back internally — synthesis still succeeds, but anything streaming WAV bytes to stdout has to silence fd 1 around the bridge, as the example's callers already do.

Measured on the runner: premise confirmed, lever not sufficient

That measurement has now been taken, by the temporary macos-14 job in this branch (run). The host reports Apple M1 (Virtual), macOS 14.8.7 — the virtualised guest this PR is about.

All four presets fail, at the vocoder, in two clean groups:

preset	vocoder error
default	Code=0 — Failed to prepare the model for predictions … KokoroVocoder, E5RT: Output rank has changed after reshaping espresso network for blob = anchor_classic_cpu (11)
all-ane	same
cpu-and-gpu	Code=1 — Invalid shape for output feature 'anchor' … must be of rank 1, instead got a multi-array value of rank 2
cpu-only	same

Two things follow, and they pull in opposite directions.

The premise is confirmed. The failure this PR was opened for is now observed in CI rather than inferred from a downstream report, and it is exactly the quoted error. It also lands where the docs in this PR now say it does: init succeeds, the first synthesize fails. The split is explanatory rather than coincidental — the two ANE-targeting presets share one failure, the two non-ANE presets share a different one, so the compute-unit setting demonstrably changes what CoreML does.

The lever is not sufficient on this host. Moving the vocoder off the ANE clears the prepare failure and then hits a second, independent bug: the vocoder returns rank 2 where the model description demands rank 1. cpu-only fails identically to cpu-and-gpu, so this is not GPU-specific. Plausibly the same data-dependent-shape issue behind the E5RT "Data-dependent shapes were disabled" diagnostics noted above — which an M2 recovers from and this virtual M1 does not — but that link is not established here.

So compute-unit selection is necessary but not sufficient for a virtualised host. The API is still the right thing to expose — a caller cannot even attempt the workaround without it, and it is the documented escape hatch — but it does not on its own make Kokoro work on a GitHub-hosted macos-14 runner, and this PR should not be read as claiming it does.

The second failure is upstream, not this binding — filed as FluidInference/FluidAudio#836. Worth noting there: Package.swift declares .macOS(.v14) and KokoroAne carries no @available gate (Qwen3 does, at macOS 15), yet every upstream workflow runs on macos-15 — so the declared floor is not exercised anywhere.

The probe job that produced this has been removed again; ci.yml is byte-identical to main. Keeping it would have left a permanently red check that re-measures a known result, when the thing that must change lives in FluidAudio. The evidence stays in the run linked above.

Pre-existing, untouched

cargo test --doc fails on init_qwen3_streaming's example (undeclared capture_audio_chunk) and cargo clippy --all-targets flags needless_borrows_for_generic_args in build.rs. Both reproduce on unmodified main; left alone to keep this diff to one subject. cargo fmt also rewrites several unrelated files on main — those reverts are excluded here too.

Refs drakulavich/kesha-voice-kit#678

🤖 Generated with Claude Code

https://claude.ai/code/session_01UU2vgxhrf56CN8YDqbg3q1

[Alex-Wengg]

  ## PR #21 — Kokoro compute units

  1. P2 — The public documentation contradicts both probe outcomes.

     The API docs promise that CpuAndGpu or CpuOnly “keeps synthesis working” on virtualized macOS
     (src/lib.rs L507–520

     (https://github.com/FluidInference/fluidaudio-rs/blob/ec2a2d75781946d278f77626dd13b26c7694b6f7/src/lib.rs#L507-L520));
     the example and Swift comments make similar claims.

     However:
      - Attempt 1: all four presets failed.
      - Attempt 2, rerun today
        (https://github.com/FluidInference/fluidaudio-rs/actions/runs/31007985381/attempts/2): all
        four presets succeeded, including default.

     Both attempts used the same commit, macOS 14.8.7, runner-image version, virtual M1, and Xcode
     16.2. The differing result likely came from an external model artifact, though that needs
     confirmation. Update the PR body with both outcomes and describe compute-unit selection as an
     API/debugging control—not a proven macOS-14 workaround. Recording the model artifact digest
     would make future reproduction meaningful.

  2. P2 — The documented example can corrupt its WAV output.

     The example recommends:

     ... cpu-and-gpu > out.wav

     It performs synthesis while stdout is already redirected, then writes the WAV to that same
     stream (example L26–36

     (https://github.com/FluidInference/fluidaudio-rs/blob/ec2a2d75781946d278f77626dd13b26c7694b6f7/examples/kokoro.rs#L26-L36)).
     The PR body says CoreML emitted 436 bytes of diagnostics to stdout on this path. Those bytes
     would precede RIFF and corrupt out.wav.

     Prefer an explicit output-file argument, or suppress/redirect fd 1 around initialization and
     synthesis before writing the WAV.

  The ABI design itself looks good: the original three-argument symbol remains intact, the new
  preset gets its own symbol, invalid strings fail explicitly, and the Rust enum mapping is
  straightforward.

  ## PR #22 — cache isolation

  The previous findings remain unresolved; its head has not changed:

  1. P2 — Add Rust’s toolchain digest to the target cache key. stable moves, but the key only
     identifies Swift. Use id: rust and ${{ steps.rust.outputs.cachekey }}.

  2. P3 — Remove .build and correct the rationale. build.rs uses $OUT_DIR/swift-build, and OUT_DIR
     is already under target (build.rs L9–26