ThreadCast — Android Production Zips

Distributed mirror for the Android app's neural TTS assets. The eight zips here are downloaded by the app at runtime — first install of a neural engine pulls only what's needed (~74 MB for one Piper voice + shared data, ~26 MB for the Plus bundle, or ~145 MB for the full Kokoro bundle), and the user can manage each model individually from inside the app.

Sibling: ../extension/ holds the Chrome extension's neural models in raw HF format. Both subtrees share the same engine families (Piper VITS, KittenTTS-nano, Kokoro StyleTTS2) — only the on-disk packaging differs.

Layout

mobile-android/
└── v1/
    ├── threadcast-piper-shared-v1.zip                    (~11 MB) — espeak phonemizer data, downloaded once
    ├── threadcast-piper-en_US-amy-medium-v1.zip          (~63 MB) — Amy voice
    ├── threadcast-piper-en_US-lessac-medium-v1.zip       (~63 MB) — Lessac voice
    ├── threadcast-piper-en_US-ryan-medium-v1.zip         (~63 MB) — Ryan voice
    ├── threadcast-piper-en_US-hfc_female-medium-v1.zip   (~63 MB) — HFC Female voice
    ├── threadcast-piper-en_US-hfc_male-medium-v1.zip     (~63 MB) — HFC Male voice
    ├── threadcast-kitten-nano-en-v1.zip                  (~26 MB) — KittenTTS nano v0.1 fp16 (all 8 voices; "Local AI Plus")
    └── threadcast-kokoro-int8-en-v1.zip                  (~145 MB) — Kokoro int8 v0.19 (all 11 voices; "Local AI Studio")

Versioning: the v1/ segment is part of the URL the runtime requests. Bumping to v2/ lets future format changes ship without breaking older app builds — old apps keep pulling v1/, new apps pull v2/.

What's inside each zip

The native AssetInstaller extracts each zip directly under filesDir/sherpa-piper/ (Piper) or filesDir/sherpa-kokoro/ (Kokoro), so the zip's internal layout = the on-device layout. No re-rooting, no per-file rules.

Piper — shared espeak data

threadcast-piper-shared-v1.zip
└── espeak-ng-data/
    ├── phontab
    ├── phonindex
    ├── phondata
    ├── intonations
    ├── lang/
    ├── voices/
    └── … (full espeak-ng tree)

Downloaded once on the user's first Piper voice install. Skipped on every subsequent voice install.

Piper — one zip per voice

threadcast-piper-en_US-amy-medium-v1.zip
└── en_US-amy-medium/
    ├── en_US-amy-medium.onnx        (~63 MB)
    └── tokens.txt

Five zips total — one per voice. Users only download the voices they want; selecting Amy doesn't pull Ryan.

Kitten (Local AI Plus) — single bundle, all voices

threadcast-kitten-nano-en-v1.zip
├── espeak-ng-data/                  (separate copy from Piper's / Kokoro's — different on-disk root)
│   └── …
├── model.fp16.onnx                  (~24 MB)
├── voices.bin                       (~30 KB — 8 speaker embeddings)
└── tokens.txt

One download serves all 8 Plus voices — same style-vector-lookup pattern as Kokoro. The 8 speakers are baked into voices.bin in the order documented in packages/mobile/modules/threadcast-neural/index.ts::KITTEN_VOICES. Never write the upstream engine codename in user-facing surfaces — the Android UI labels this engine as "Local AI Plus" everywhere.

Kokoro (Local AI Studio) — single bundle, all voices

threadcast-kokoro-int8-en-v1.zip
├── espeak-ng-data/                  (separate copy from Piper's — different on-disk root)
│   └── …
├── model.int8.onnx                  (~135 MB)
├── voices.bin                       (~5.7 MB — concatenated speaker embeddings, all 11)
└── tokens.txt

One download serves every Kokoro voice — switching speakers is a free style-vector lookup at synth time.

How the runtime fetches these

Mirror-and-fallback — same pattern the extension uses for its Pixel-Labs/threadcast-neural-models/{hf-cpu-mirror,hf-gpu-mirror}/ paths (see extension/src/offscreen/mirror-fetch.ts). Each download is an ordered list of URLs; the installer tries each on failure and only surfaces an error if every URL is unreachable.

urls[0] = PRIMARY_BASE   = https://huggingface.co/Pixel-Labs/threadcast-neural-models/resolve/main/mobile-android/v1
urls[1] = FALLBACK_BASE  = (configurable — sibling HF repo, GitHub Release, private CDN, …)

Both bases need to serve the same filenames (the eight listed above). The fallback host is configured at app build time:

Env var (set at build time)	Default	Purpose
`EXPO_PUBLIC_NEURAL_ASSETS_BASE_URL`	`https://huggingface.co/Pixel-Labs/threadcast-neural-models/resolve/main/mobile-android/v1`	Primary mirror
`EXPO_PUBLIC_NEURAL_ASSETS_FALLBACK_URL`	unset	Optional fallback (omit for primary-only)

The native installer:

Tries urls[0] first. On HTTP 4xx/5xx or transport error, logs a warning and tries urls[1].
Only the LAST URL's failure surfaces to the UI as a download error — transient mirror outages are silent.
Cancellation aborts immediately at any URL boundary.
Verifies post-extract that every required file exists with non-zero size; rejects malformed zips even if the HTTP layer succeeded.

Publishing workflow

Produce the zips from the local sherpa-onnx staging tree:
```
pnpm --filter mobile produce:neural-zips
```
Writes to packages/mobile/dist/neural-assets/. The script reads the locally-staged sherpa-onnx upstream artifacts (Piper voice ONNX files + KittenTTS-nano v0.1 fp16 bundle + Kokoro int8 v0.19 bundle + shared espeak-ng-data) and emits the eight zips with the correct internal layouts.
Upload to Hugging Face — the user-facing primary mirror lives at:

https://huggingface.co/Pixel-Labs/threadcast-neural-models/tree/main/mobile-android/v1

Drop all eight zips into that tree. HF preserves filenames as-is. No build steps, no metadata munging — they're just static assets behind a CDN.
(Optional) Mirror to a fallback host. Same eight filenames at any HTTPS endpoint. Common picks:
- Sibling HF repo (Pixel-Labs/threadcast-neural-models-mirror/v1/...)
- GitHub Release with gh release upload v1 dist/neural-assets/*.zip
- Private CDN (R2, S3, etc.)
Then ship the next app build with EXPO_PUBLIC_NEURAL_ASSETS_FALLBACK_URL set to the mirror's base URL.

Per-engine download cost (user-facing)

User intent	Files pulled	Network
Install first Local AI Lite voice (e.g. Amy)	`threadcast-piper-shared-v1.zip` + `threadcast-piper-en_US-amy-medium-v1.zip`	~74 MB
Install another Local AI Lite voice (e.g. Lessac)	`threadcast-piper-en_US-lessac-medium-v1.zip`	~63 MB
Install Local AI Plus	`threadcast-kitten-nano-en-v1.zip`	~26 MB
Install Local AI Studio	`threadcast-kokoro-int8-en-v1.zip`	~145 MB
Install every engine, all 5 Lite voices + Plus + Studio	every zip in `v1/`	~496 MB

The whole-bundle worst case is comparable to Spotify's "download an album for offline" workflow. Most users will pick one tier and stop there — Plus is the sweet spot at 26 MB for an 8-voice multi-speaker model.

License

Per-project licenses retained from upstream — see the parent README for the consolidated summary.