# episodes/ — Per-episode reference mode

This is the new reference mode, forked off batch1. The layout is **flat**, not
nested per-episode:

```
episodes/
├── Individual Episodes/      # one video file per episode
│   ├── 01.mp4
│   ├── 02.mp4
│   └── …                      (pad to 2 digits so they sort)
└── Script/                   # one master script file covering all episodes
    └── Script - Casamento da família Flores (2).xlsx
```

The **join key** is the episode number: the `Ep ` column in the script
(string, zero-padded: `"01"`, `"02"`, …) matches `NN.mp4` in
`Individual Episodes/`.

## Script columns

The master .xlsx has 24 columns — many are hidden or legacy. The booth only
reads these six:

| Cue field (glossary)              | Spreadsheet column |
|-----------------------------------|--------------------|
| `episode`                         | col 1 — `Ep ` (string, `"01"` …) |
| `line`                            | col 2 — `Line` (int) |
| `character`                       | col 5 — `Character` (includes `"/"` as a valid character name) |
| `phrase`                          | col 6 — `Subtitles` |
| `start_ms` (Focus Gate start)     | col 18 — `START TC` (SRT string, `"00:00:00,980"`) |
| `end_ms` (Focus Gate end)         | col 19 — `END TC` (SRT string) |

START TC → END TC defines the **green focus zone** (the cue-span core of the
[Focus Gate](../../../build-notes/glossary.md)). Pre-roll and post-roll are
added around it by the booth.

Ignore: `Salida` (col 17), `Personajes` (col 16 — Spanish duplicate), the
`Batch Timecode` datetime pair (cols 3–4), and everything unnamed.

Every row with a character is a recordable cue — including rows whose
character is `"/"`. That's a real character name in this show, not a filler
marker.

## Adding a new episode

1. Drop the video into `Individual Episodes/` as `NN.mp4`
   (zero-padded, no spaces, no show title).
2. Run the HTDemucs batch runner to produce voice + music stems:

   ```bash
   admin-cli/.venv/bin/python admin-cli/run_htdemucs_batch.py
   ```

   It processes every `NN.mp4` in this folder and drops the stems alongside
   as `NN_voice.wav` + `NN_music.wav`. Skips episodes already done, so it's
   safe to run anytime after new episodes are pasted in.
3. Make sure the corresponding `Ep = "NN"` rows exist in the master script.

The booth can then stream that episode against its reference.

## What's *not* in this folder

- No per-episode `script.json` — the .xlsx is authoritative.
- No per-episode `corrections.json` here either; corrections remain
  non-destructive overrides written by the booth as the actor works. Where
  they land per-episode is still an open question in the feature spec.

## Git

`.mp4` / `.wav` / `.mov` / `.mp3` are globally gitignored. The master .xlsx
**will** be tracked — it's the cue sheet source of truth.