Troubleshooting

The first initialization is slow

Model and phonemizer assets download once, then ONNX initializes. Check KittenTTS.isModelCached() before showing a download UI and call prewarm() earlier in the app lifecycle when appropriate.

A bundled manifest is not found

Confirm manifest.json is in a copied folder resource named kittentts, belongs to the correct target, and preserves its subdirectory. Use a custom assetRoot if the bundle layout differs.

Model or voices file not found

Both onnxURL and voicesURL must point to readable files. A configured modelFiles value skips downloads and fails instead of silently falling back.

eSpeak fails on iOS

Use .builtin. The .espeak option runs a system process and is macOS-only. On macOS, install espeak-ng with Homebrew and verify the binary is in the process path.

Playback fails

On iOS, confirm the app's audio-session policy permits playback. Handle audioSessionFailed separately from playbackFailed so the UI can explain interruptions or route issues.

Word timings are empty

Generate shorter input. Timings require duration output and are not guaranteed for multi-chunk text.

ONNX or package build errors

Use the documented platform minimums, Xcode 15+, and a clean Swift Package cache when binary dependency resolution is stale. Include Xcode version, OS, target, model, and complete error in reports: Swift issues.