# Pokedex voice spike — scripts

De-risking spike for the Pokédex app's robotic voice output. Full pipeline:
text -> TTS -> optional DSP "robot" filter -> mp3.

## Files

- `generate_samples.sh` — end-to-end driver: installs are documented at the
  top, then runs espeak-ng and Piper TTS, then the DSP filters, then
  converts everything to mp3. Run it from this directory (`./generate_samples.sh`).
- `robot_filter.py` — heavy/original robot filter: square-wave ring
  modulation, bitcrush (sample-and-hold + bit-depth reduction), narrow
  band-pass, hard drive. This is what "too robotic" was generated with.
- `robot_filter_light.py` — barely-there version: sine-wave ring mod at
  low mix, wide band-pass, mild soft-clip. Meant to add a hint of
  synthesized edge to an already-natural neural voice without disturbing
  cadence.
- `robot_filter_v2.py` — the current one: parameterized, takes an
  `intensity` argument from 0.0 (untouched) to 1.0 (full heavy filter) and
  interpolates ring-mod mix/carrier, bandpass width, bitcrush, and drive
  along that scale. Usage: `python3 robot_filter_v2.py in.wav out.wav 0.45`.
  This is the one to keep tuning going forward — texted intensity numbers
  ("try 0.6") map directly to its third argument.

## Voice model

TTS engine is [Piper](https://github.com/OHF-Voice/piper1-gpl) — a small,
fully offline neural TTS with real Android ports available, which matters
for the app's "works with no signal" requirement.

The voice used is `en_US-joe-medium.onnx`, fine-tuned from Piper's stock
"lessac" voice on a CC0-licensed dataset (see MODEL_CARD if you unpack the
wheel) — no attribution/licensing issue to ship it.

**How I got the model file in this sandbox:** the sandbox's network
allowlist didn't reach huggingface.co, where Piper's official voices are
hosted, only package registries. I found a community-published PyPI wheel
(`joe-us-piper-voice`) that bundles the .onnx file directly, so a plain
`pip install` pulled it down. That's a workaround specific to *this*
sandbox — for the real project, get voices the normal way from Piper's
official releases/voice list, which gives you far more voice choices
(different speakers, accents, quality tiers) than this one bundled option.

## What's still open

- Pronunciation of individual Pokémon species names hasn't been
  systematically checked — only "Pokémon," "Bulbasaur," "Charizard,"
  "Pikachu" were tested. Expect to need a pass listening to all ~1000+
  species names and hand-fixing the ones the phonemizer (espeak-ng, under
  Piper's hood) gets wrong, either by respelling in the source text or via
  espeak's phoneme-override escape syntax.
- Robot filter intensity (`robot_filter_v2.py`'s `intensity` arg) needs to
  land wherever the actual desired "amount of robotic" ends up — currently
  parked at 0.45 pending feedback.
- This whole pipeline is meant to run once, offline, over every dex entry
  ahead of time (batch pre-generation), not live on-device — see the
  earlier discussion in this conversation for why.