Upload README.md

mobile-android/README.md

@@ -0,0 +1,147 @@
+# ThreadCast — Android Production Zips
+
+Distributed mirror for the Android app's neural TTS assets. The seven 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, or ~145 MB for the full Kokoro bundle), and the user can manage each model individually from inside the app.
+
+> Sibling layout:
+>
+> - **`../extension/`** — Chrome extension models (raw HF format, published).
+> - **`../android/`** — local dev staging for sherpa-onnx upstream artifacts (not published).
+> - **`./mobile-android/` (you are here)** — the zips actually shipped to users (published to HF).
+
+---
+
+## 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-kokoro-int8-en-v1.zip                  (~145 MB) — Kokoro int8 v0.19 (all 11 voices)
+```
+
+**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.
+
+### Kokoro — 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 seven 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 `../android/`:
+
+   ```sh
+   pnpm --filter mobile produce:neural-zips
+   ```
+
+   Writes to `packages/mobile/dist/neural-assets/`. The script reads sherpa-onnx upstream artifacts in `../android/{neural-28m,neural-82m}/` and emits the seven zips with the correct internal layouts.
+
+2. **Copy into this folder** (for local convenience and snapshotting):
+
+   ```sh
+   cp packages/mobile/dist/neural-assets/*.zip "AI Neural Models/mobile-android/v1/"
+   ```
+
+3. **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 seven zips into that tree. HF preserves filenames as-is. No build steps, no metadata munging — they're just static assets behind a CDN.
+
+4. **(Optional) Mirror to a fallback host.** Same seven 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** Piper voice (e.g. Amy) | `threadcast-piper-shared-v1.zip` + `threadcast-piper-en_US-amy-medium-v1.zip` | ~74 MB |
+| Install **another** Piper voice (e.g. Lessac) | `threadcast-piper-en_US-lessac-medium-v1.zip` | ~63 MB |
+| Install Local AI Studio (Kokoro) | `threadcast-kokoro-int8-en-v1.zip` | ~145 MB |
+| Install both engines, all 5 Piper voices + Kokoro | every zip in `v1/` | ~470 MB |
+
+The whole-bundle worst case is comparable to Spotify's "download an album for offline" workflow. Most users will probably pick one Piper voice OR Kokoro and stop there.
+
+---
+
+## License
+
+Per-project licenses retained from upstream — see the [parent README](../README.md#license) for the consolidated summary.