| # 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`](https://github.com/Pixel-Labs/Reddit-Reader/blob/main/packages/mobile/modules/threadcast-neural/android/src/main/java/app/threadcast/neural/AssetInstaller.kt) 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`](https://github.com/Pixel-Labs/Reddit-Reader/blob/main/packages/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 |
|
|
| 1. **Produce the zips** from the local sherpa-onnx staging tree: |
|
|
| ```sh |
| 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. |
|
|
| 2. **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. |
|
|
| 3. **(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](../README.md#license) for the consolidated summary. |
|
|
