# PokéPapi Video Editor + TTS — User Guide

**Last updated:** 2026-04-18 (v1.17.0)
**Primary URLs:**
- Video editor:        `https://pokepapi.com/videoeditor/`
- TTS studio:          `https://pokepapi.com/tts/`
- Chatterbox Extended (local, PC only):  `http://localhost:7860`
- Chatterbox Extended (remote, auth):    `https://pokepapi.com/chatterbox/` (user: jeff, password stored in 1Password / your notes)

---

## 1. Daily workflow (TL;DR)

**Happy path — one click:**
1. Open the video editor → click **"New Dex Batch"** → pick type (`short-N` or `long-N`), generate
2. Click **"Browse Server"** → import the newly created batch folder
3. Verify voice is set to **"Jeff - Narrator (Chatterbox)"** (default)
4. Click **Render** → done. Pronunciation fixes applied automatically.

**Preview-first path (when you want to QA audio):**
1. Generate the batch as above
2. Open `pokepapi.com/tts/` → **🎮 Dex Quiz Batch** tab
3. Pick the batch folder + voice → **Generate All Narration**
4. Skim `/var/www/vhosts/pokepapi.com/battle/tools/dexgame/<batch>/audio/*.wav` — spot-check 3 clips
5. Hit a bad pronunciation? Add it to `/poke/shared/pronunciations.json`, re-run step 3 for that clip only
6. Back to the video editor → Browse Server → import → render. The editor **reuses the audio you approved** (no re-generation).

**Per-slide surgical edits (after loading a project):**
- Click **✏️** next to a slide to edit narration text in place (writes to session `narration.json`)
- Click **🔄** to re-render just that slide's audio (pronunciation dict applied automatically)
- Full Render reuses all clips you've already regenerated — no re-doing good clips

---

## 2. Components & where they run

| Component | Host | Port | Purpose |
|---|---|---|---|
| Chatterbox TTS server | Jeff's PC | 8080 (CUDA) | Voice cloning model (ResembleAI) |
| SSH reverse tunnel | PC → Server | 8384 on server → 8080 on PC | Exposes Chatterbox to the server |
| Video editor | Server (Plesk) | HTTPS | UI + render pipeline (`/poke/videoeditor/`) |
| TTS studio | Server | HTTPS | Single-clip + batch TTS UI (`/poke/tts/`) |
| Edge TTS | Server | 5566 | Free fallback voices |
| Shared pronunciation dict | Server | — | `/poke/shared/pronunciations.json` |

**Autostart:** `C:\Users\jeff\AppData\Roaming\Microsoft\Windows\Start Menu\Programs\Startup\ChatterboxTTS.bat` runs on Windows boot with a 45s delay:
1. SSH tunnel watchdog (auto-reconnects)
2. Chatterbox-TTS-Extended Gradio UI on port 7860 (local experimentation)
3. Chatterbox TTS API on port 8080 (production pipeline)

Logs:
- `C:\Users\jeff\chatterbox\startup.log` — base API server + tunnel
- `C:\Users\jeff\chatterbox-extended\startup.log` — Extended UI

## Chatterbox-TTS-Extended (Gradio UI)

**URL:** `http://localhost:7860` (PC only — not exposed via tunnel)
**What it's for:** interactive experimentation with the same model your production pipeline uses. Useful for:
- Tuning `exaggeration` / `cfg_weight` / `temperature` live before committing a voice reference
- Denoising your voice reference recordings (`pyrnnoise`) before uploading
- Auto-trimming silences / stutters from generated clips
- Voice Conversion (different tab) — take existing audio and re-render in a reference voice
- Listening to candidate generations + Whisper auto-validation for quality control

**Important:** the Extended UI does NOT replace the production pipeline — the video editor + /tts studio still call the `api_server.py` on port 8080. Think of Extended as your "workshop" for prepping voice references; your "assembly line" is the production tools.

**To open:**
- **From the PC:** `http://localhost:7860`
- **From anywhere else (phone, another computer):** `https://pokepapi.com/chatterbox/` — prompts for HTTP basic auth (user: `jeff`, password in your notes)

**How remote access works:**
1. The Extended Gradio UI binds to `127.0.0.1:7860` on your PC (not exposed to LAN or internet)
2. `tunnel-watchdog.bat` maintains a reverse SSH tunnel forwarding **server port 7862 ← PC port 7860**
3. nginx on pokepapi.com has a `/chatterbox/` location that proxies to `127.0.0.1:7862` with HTTP basic auth
4. Gradio is configured with `root_path=/chatterbox` so URLs emit correctly through the proxy
5. PC stays closed to the internet — only the SSH tunnel carries traffic in; nginx validates auth before letting anything reach Gradio

**If Gradio isn't up after reboot:**
- Check `C:\Users\jeff\chatterbox-extended\startup.log`
- Manually run `C:\Users\jeff\chatterbox-extended\start-extended.bat`

---

## 3. Creating dex batches

**From the video editor:**
- Click **"New Dex Batch"** button (opens modal)
- Choose type: `short-N` (10 Q/A pairs, ~60s videos) or `long-N` (30+ pairs, ~3-5 min)
- Count: how many batches to pre-generate (useful for a week's content in one go)

**What gets generated per batch** (`/battle/tools/dexgame/<name>/`):
- `NNN_N_Q_<pokemon>_<game>.jpg` — question cards
- `NNN_N_A_<pokemon>_<game>.jpg` — answer cards
- `narration.json` — per-slide narration + dex text
- `subtitles.srt` + `subtitles.vtt` — subtitle files
- `audio/*.wav` — only if you've run TTS via `/poke/tts` batch tab

---

## 4. Narration & subtitles

- **Source of truth:** `narration.json` in each batch folder
- **Subtitle files:** SRT/VTT are generated at render time based on actual TTS audio durations (regenerated even if the files already exist)
- **Narration text priority in worker:** `narration.json[name].narration` → `narration.json[name].dexText` → cleaned filename

**Editing narration text:**
- Edit `narration.json` directly in the batch folder — changes take effect on the next render/TTS run
- For one-off pronunciation fixes in a specific clip, phonetic respelling in `narration.json` works (e.g., `"Groudon"` → `"Grow-don"`)
- For systematic/repeating issues, use the dictionary (section 5) — fixes every future batch

---

## 5. Pronunciation dictionary (the important one)

**File:** `/var/www/vhosts/pokepapi.com/poke/shared/pronunciations.json`

**Used by:** `process_worker.php` (video editor render) AND `api.php` (TTS studio) — one edit, everywhere.

**Format:**
```json
{
  "FIRERED": "Fire Red",
  "OMEGARUBY": "Omega Ruby",
  "CUSTOMNAME": "Phonetic Respell"
}
```

**Rules:**
- Keys are matched case-insensitive with word boundaries (so `"OMEGARUBY"` won't accidentally match inside another word)
- Longer keys match first (so `"OMEGARUBY"` beats `"OMEGA"`)
- Unicode is normalized before dict lookup: **é→e**, curly quotes→straight, em-dash→hyphen. That's why `POKéMON`/`Pokémon` both become `Pokemon` automatically.

**Adding a new fix (easy — inline editor):**
- **Video editor:** expand the **🗣️ Pronunciation Dictionary** card (right under Speech & Narration). Click **+ Add row**, type Word + Pronounce As, click **💾 Save Dictionary**.
- **TTS app:** click the **🗣️ Pronunciations** tab, same flow.
- Both apps share the same dictionary — edit in either, both pick it up on the next TTS call. No restart.
- Bulk editing: click **+ Add row** repeatedly, fill multiple rows, save once. Click **−** on any row to delete.

**Adding a new fix (advanced — SSH):**
1. Edit `/poke/shared/pronunciations.json` directly
2. Save. Preprocessor reads fresh on each TTS call — no cache.

**Seeded entries (as of 2026-04-18):**
Pokemon game name compounds (`FIRERED`, `LEAFGREEN`, `HEARTGOLD`, `SOULSILVER`, `OMEGARUBY`, `ALPHASAPPHIRE`, `ULTRASUN`, `ULTRAMOON`, `BLACK2`, `WHITE2`), combo names (`HGSS`, `ORAS`, `BDSP`), and `POKéMON`/`POKÉMON` → `Pokemon`.

---

## 6. Voice references (and styles)

**Where:** server-side `/poke/tts/voice-references/` (shared by both apps via symlink).

**Adding a new voice or style:**
- Open `pokepapi.com/tts/` → **Voice Manager** tab → upload a 20-40s WAV/MP3
- Name it descriptively: `jeff-narrator`, `jeff-hype`, `jeff-chill`, `jeff-whisper`, etc.
- The video editor's voice dropdown auto-populates on next page refresh — style names derived from filename (`jeff-hype.wav` → "Jeff - Hype")

**How styles work in Chatterbox:**
- Chatterbox is a voice *cloner* — it matches the tone/energy of your reference clip
- If you record a 30s hype/excited take as `jeff-hype.wav`, outputs using that reference sound excited
- If you record calm/narrator tone as `jeff-narrator.wav`, outputs sound calm
- **This is more reliable than any "style" param** — Chatterbox does have `exaggeration`/`cfg_weight`/`temperature` but they don't change pitch/speed cleanly
- No SSML / per-word style tags in Chatterbox. For per-sentence style shifts, split the script and render separately.

**Where to upload style files:**
- Via UI: `pokepapi.com/tts/` → Voice Manager → Upload
- Direct server path: `/var/www/vhosts/pokepapi.com/poke/tts/voice-references/<name>.wav`
- Direct PC path (local Chatterbox reference dir, not strictly required but useful): `C:\Users\jeff\chatterbox\voice-references\<name>.wav`

**Quality tips:**
- Reference audio shapes *timbre and style*, not pronunciation. For pronunciation, use the dictionary.
- 30-35s max; anything longer gets auto-trimmed to 30s
- Clean mono audio, 24kHz+, no background music
- Record each style in the same acoustic environment so only the expression differs — helps the voice stay recognizable

---

## 7. Troubleshooting

### "My voice isn't generating, only Edge TTS works"
1. **Is Chatterbox up on PC?** `netstat -ano | grep 8080` — should show LISTENING
2. **Is the tunnel up?** SSH to server: `ss -tln | grep 8384` — should show LISTENING on 127.0.0.1
3. **End-to-end test:** on server: `curl -X POST http://127.0.0.1:8384/v1/tts -H 'Content-Type: application/json' -d '{"text":"test","format":"mp3"}' -o /tmp/t.mp3` — expect HTTP 200 + MP3 bytes
4. **Restart everything manually:** run `C:\Users\jeff\chatterbox\start-chatterbox.bat` in a visible terminal

### "Chatterbox didn't come up after reboot"
- Check `C:\Users\jeff\chatterbox\startup.log` — shows exactly what failed
- If the log ends at "Loading Chatterbox model on cuda..." and nothing after: GPU probably wasn't ready. Increase the boot delay in `ChatterboxTTS.bat` from 45s → 90s.
- Manually run `start-chatterbox.bat` to confirm the install still works

### "Wrong pronunciation even though I added it to the dict"
- JSON syntax error? Run `jq . /poke/shared/pronunciations.json` — should parse without error
- Word boundary problem? If your word is stuck next to punctuation like `POKeMON,` it still matches. If it's inside another word like `GROUDONSAURUS` it won't — use the longer form as the key.

### "Video rendered but no audio on slides"
- Check worker log for `POKEPAPI WORKER TTS FAIL` or `POKEPAPI WORKER TTS CURL ERR` lines
- Tail: `ssh PokePapi "tail -100 /var/log/php-fpm/error.log | grep POKEPAPI"`

---

## 8. Posting cadence strategy

For the target of ~1 short/day + 3 longs/week:

**Sunday / Monday:** Batch-generate 7 shorts + 3 longs via the video editor. Output: 10 batch folders ready in `/battle/tools/dexgame/`.

**Then for each day:** Open editor → browse server → pick the day's batch → render. ~2-3 min of active time per short once the dictionary is mature.

**When to use the preview path** (`/poke/tts` batch tab first):
- New content type you haven't rendered before
- After adding a new Pokemon generation or game name that might have weird spellings
- Any time you want to spot-check before committing to a render

**When to skip it:**
- Pure routine batches in a content type you've already validated

---

## 9. Quick reference — file paths

```
/poke/shared/pronounce.php               — Pronunciation preprocessor (PHP)
/poke/shared/pronunciations.json         — The dictionary (edit this to add fixes)
/poke/videoeditor/index.php              — Video editor UI
/poke/videoeditor/process.php            — Web entry / batch import
/poke/videoeditor/process_worker.php     — Async render worker (TTS + FFmpeg)
/poke/videoeditor/config.php             — VIDEO_EDITOR_VERSION constant, paths
/poke/videoeditor/voice-references       — Symlink → /poke/tts/voice-references
/poke/tts/index.html                     — TTS studio UI
/poke/tts/api.php                        — TTS API (generate, batch, upload voice)
/poke/tts/voice-references/              — Master voice reference dir (shared)
/battle/tools/dexgame/<batch>/           — Generated batches (imgs, narration, audio)
/battle/tools/create-random-batch.js     — Batch generator (run via editor button)

C:\Users\jeff\chatterbox\                — Chatterbox install (PC side)
C:\Users\jeff\chatterbox\startup.log     — Autostart diagnostic log
Startup\ChatterboxTTS.bat                — Windows autostart entry
```