docs/DEMO_VIDEO_SCRIPT.md

# Phantom Grid — Demo Video Script & Production Reference

> **Purpose:** A complete, hand-off-ready reference for an editor/agent to assemble a
> ~90–120 second demo video for **Phantom Grid** (the local, browser-based London
> investigation game) and its new first-run tutorial.
>
> This document is the **single source of truth** for the video. It lists every shot,
> what asset to use, exactly what voiceover/on-screen text goes with it, and — where a
> static screenshot is not enough — a clearly marked **`[CAPTURE NEEDED]`** placeholder
> with precise instructions for recording the missing footage.

---

## 1. Format & delivery specs

| Field | Value |
| --- | --- |
| Target length | 90–120 s (trailer-paced) |
| Resolution | 1920×1080, 30 fps (screenshots were captured at 1680×945 @2x → crop/scale to fit) |
| Aspect | 16:9 |
| Output | `docs/demo/phantom_grid_demo.mp4` (H.264, ~10–12 Mbps), plus a 1080×1080 square cut for social if time allows |
| Captions | Burn-in optional; also export an `.srt` from the voiceover script in §6 |
| Audio | One music bed + light UI SFX from the game; voiceover optional (script provided) |

**Tone:** noir detective / "Lantern Watch Bureau" period-dossier framing. Warm gold on deep
teal-green (the game's own palette). Confident, brisk, a little mysterious.

**Brand palette (for lower-thirds / titles):**
- Gold text `#ffe39a`, accent gold `#d9ae50`
- Crimson accent `#d4513e` / `#a73a29`
- Deep background `#071f21`, panel border `#9a6926`
- Display font: a serif close to Georgia / "Cinzel" for titles; UI text is system serif.

---

## 2. Assets already captured (ready to use)

All under [`ui/web/static/assets/tutorial/`](../ui/web/static/assets/tutorial/). Real frames
from the running game, 1680×945 @2x (≈3360×1890 px):

| File | Shows | Best used for |
| --- | --- | --- |
| `01_board_overview.png` | Full game board: Wanted poster, units, map, notepad, turn counter | Establishing shot / "the board" |
| `02_briefing.png` | Case briefing dossier (crime, suspect, last-seen trail) | "Every case starts with a briefing" |
| `03_map_layers.png` | Map on the **Taxi** transport layer | Transport layers / routes |
| `04_tactics_tray.png` | The 5 tactics with unit counts (Roadblock, Junction Lockdown, Patrol Unit, Search Team, Lookout Board) | Tactics explainer |
| `06_notice.png` | "Issue Public Notice" composer dialog | Public-notice mechanic |
| `07_witness_interview.png` | Witness interview panel (profile, statement, chat input, voice controls) | Witness interview |
| `08_witnesses_map.png` | Map in Witness Mode covered with witness pins | "Read the city" / leads |

> **Note:** `05_placed_tactic.png` was intentionally removed; the tactics story is told
> better with the tray (`04`) plus the **`[CAPTURE NEEDED]`** drag clip (Shot 6).

**To re-capture or refresh any still:** run the project app + AI backend, then
`tools/shotenv/Scripts/python.exe tools/capture_tutorial_shots.py`
(see [`tools/capture_tutorial_shots.py`](../tools/capture_tutorial_shots.py)). Output lands
back in `assets/tutorial/`.

---

## 3. How to capture the MISSING footage (`[CAPTURE NEEDED]`)

The demo needs **motion** that stills can't convey. Two ways to record:

**Option A — Playwright video (deterministic, no narrator cursor):**
Playwright can record a context to webm. Reuse the working selectors/flows in
[`tools/capture_tutorial_shots.py`](../tools/capture_tutorial_shots.py). Minimal recorder:

```python
# tools/record_clips.py  (to be written by the video agent)
from playwright.sync_api import sync_playwright
with sync_playwright() as pw:
    b = pw.chromium.launch(headless=False)          # headed = smoother cursor
    ctx = b.new_context(viewport={"width":1680,"height":945},
                        record_video_dir="docs/demo/clips",
                        record_video_size={"width":1680,"height":945})
    page = ctx.new_page()
    page.goto("http://127.0.0.1:7860")
    # ...drive the exact interaction for the shot (see per-shot notes below)...
    ctx.close(); b.close()                          # video is flushed on context close
```

Prerequisites (same as the screenshot tool): the app is running at
`http://127.0.0.1:7860` and the AI backend reports healthy
(`GET /api/omni/status` → `"ready": true`). Starting a case and advancing turns
**requires** the local model to be up.

**Option B — OBS / native screen capture:** record a real play session at 1080p, 30 fps,
hiding the OS cursor trail. Use this for anything with audio (the witness voice reply).

**Selector cheat-sheet (verified working):**
- Start a case from the ready overlay: `#setupStartButton` (force-click; it pulses)
- Dismiss briefing: `#beginInvestigationButton`
- Layer tabs: buttons in `#layerTabs` (text "Normal/Taxi/Bus/Subway")
- Tactics in tray: `#tacticTray > *`; drag onto `#mapCanvas`
- Lookout board placement opens `#noticeDialog`; publish with `#raiseLookoutButton`
- Witness Mode toggle: `#witnessModeButton`; pins in `#witnessLayer [data-witness-id]`
- Advance a turn: `#advanceButton`
- Tutorial: auto-opens first run; replay via `#helpButton`; nav `#tutorialNext`/`#tutorialBack`

---

## 4. Shot list (the actual edit, in order)

Legend: 🟢 = asset ready · 🔴 = `[CAPTURE NEEDED]`

| # | Len | Visual | On-screen text | Source |
| --- | --- | --- | --- | --- |
| 1 | 0:00–0:06 | Title card: logo "PHANTOM GRID" over a slow push-in on the board, vignette | **PHANTOM GRID** / "A London manhunt, played on your desk." | 🔴 **[CAPTURE NEEDED: title animation]** built over `01_board_overview.png` (Ken Burns zoom 100%→108%) |
| 2 | 0:06–0:14 | The case briefing dossier reveals (cards slide/stamp in) | "Every case opens with a dossier." | 🟢 `02_briefing.png` (animate the three cards in; or 🔴 record the real reveal — see Shot notes) |
| 3 | 0:14–0:22 | Full board establishing; subtle callouts pop on Wanted / Map / Turn counter | "You're the Commissioner. Catch the thief before time runs out." | 🟢 `01_board_overview.png` + motion-graphic callout arrows |
| 4 | 0:22–0:32 | Map layers switching Normal→Taxi→Bus→Subway | "The suspect can only move along the transport grid." | 🔴 **[CAPTURE NEEDED: layer-switch clip]** (fallback still: `03_map_layers.png`) |
| 5 | 0:32–0:40 | Witness Mode: city fills with witness pins | "Sightings light up across the city — some true, some false." | 🟢 `08_witnesses_map.png` (push-in) or 🔴 record the toggle |
| 6 | 0:40–0:50 | Dragging a tactic chip from the tray onto a junction; pin lands | "Deploy your units: roadblocks, patrols, search teams." | 🔴 **[CAPTURE NEEDED: tactic drag clip]** + cutaway to 🟢 `04_tactics_tray.png` |
| 7 | 0:50–0:58 | Issue Public Notice dialog; type wording; Publish | "Issue a public appeal to draw out fresh leads." | 🟢 `06_notice.png` or 🔴 record the type+publish |
| 8 | 0:58–1:12 | Witness interview: type a question, AI witness replies (ideally with voice audio) | "Interview witnesses — ask what they saw, where it went, when." | 🔴 **[CAPTURE NEEDED: live interview clip w/ audio]** (fallback still: `07_witness_interview.png`) |
| 9 | 1:12–1:20 | Advance Turn → suspect moves; tension beat; a Search Team triggers the catch | "Close the net. One move too slow and they vanish." | 🔴 **[CAPTURE NEEDED: advance-turn + win/lose moment]** |
| 10 | 1:20–1:30 | The first-run tutorial flips through 2–3 slides | "New here? A built-in tutorial walks you through it." | 🔴 **[CAPTURE NEEDED: tutorial slide flips]** (stills available as fallback: the 7 tutorial slides render the assets in §2) |
| 11 | 1:30–1:40 | End card: logo + setup line + URL | "Runs locally. Your case, your machine." / `127.0.0.1:7860` | 🔴 **[CAPTURE NEEDED: end card]** |

> Trim to 90 s by dropping Shots 7 and 10 and tightening 8–9. Extend to 2 min by letting
> the interview (Shot 8) breathe with real audio.

---

## 5. Per-shot capture notes for `[CAPTURE NEEDED]` items

- **Shot 1 / 3 (title + callouts):** pure motion-graphics over the ready still
  `01_board_overview.png`. No new game capture required.
- **Shot 2 (briefing reveal, optional live):** start a case via `#setupStartButton`; the
  briefing `#caseIntroDialog` animates open. Record ~3 s, then it can be sped up.
- **Shot 4 (layer switch):** after `#beginInvestigationButton`, click the `#layerTabs`
  buttons in order with ~1 s between. Record the map area (`.map-shell`).
- **Shot 6 (tactic drag):** mouse-down on a `#tacticTray` chip, move over `#mapCanvas`
  to a junction, mouse-up. Headed mode (Option A) shows the cursor; or use OBS. Capture
  the "pin lands + event ticker confirms" beat (~3–4 s).
- **Shot 8 (interview, highest value):** open a witness (`#witnessLayer [data-witness-id]`
  → interview dialog), type a question in `#witnessMessage`, hit Send, wait for the AI
  reply to render in `#witnessTranscript`. If demonstrating **voice**, enable voice output
  in Settings and use OBS (Option B) so the audio reply is recorded. Note: surfacing an
  *interviewable* witness depends on crowd density — if pins show "crowd too dense",
  advance a turn or two, or (dev-only) raise `PHANTOM_GRID_INDIVIDUAL_WITNESS_THRESHOLD`
  to make all reports interviewable for the recording, then revert.
- **Shot 9 (advance + outcome):** press `#advanceButton` to show the turn tick and suspect
  movement. For the **win moment**, place a `search_team` on the suspect's likely junction
  and advance; the case ends and the story reveal becomes available. Capture the result
  banner / `#storyDialog` opening as the payoff. (A loss/"vanished" beat also works for
  tension — director's choice.)
- **Shot 10 (tutorial flips):** fresh browser (clears `localStorage` so it auto-opens), or
  click `#helpButton`. Record clicking `#tutorialNext` through 2–3 slides; the dots and
  "1/7 … Start Playing" progression read well on camera.
- **Shot 11 (end card):** motion-graphics card; reuse logo + palette from §1.

---

## 6. Voiceover script (timed to §4)

> Keep delivery measured; ~135 wpm. Lines map 1:1 to the shot numbers.

1. "London. A thief is loose on the grid — and you're the one they sent to catch him."
2. "Every case begins with a dossier: the crime, the suspect, the last place they were seen."
3. "You're the Commissioner. Read the trail, and move before the clock runs out."
4. "Your quarry can only travel the transport grid — taxi, bus, and underground lines."
5. "Across the city, sightings surface. Some are real. Some are decoys."
6. "Deploy your units — roadblocks, patrols, and search teams — onto the junctions that matter."
7. "Post a public notice, and the right words will draw out fresh witnesses."
8. "Then question them. What did they see? Which way did it go? Every answer narrows the net."
9. "Advance the turn… and hope you've closed the gap. One move too slow, and he's gone."
10. "New to the Bureau? A built-in tutorial walks you through your first case."
11. "Phantom Grid. It runs entirely on your machine. Open the file. Start the hunt."

---

## 7. Music & SFX

- **Music:** one cinematic-noir/spy bed, ~110–120 bpm, builds at Shot 8→9. License-clear.
- **SFX (from the game where possible):** the app emits cues such as `lookout_raise`,
  `witness_popup`, `blockade_set`, `map_select`, `turn_advance` — pull matching beats for
  pin-drops, notice-publish, tactic-place, and turn-tick. A soft "stamp" on the briefing
  card and a low "snare/impact" on the catch (Shot 9).

---

## 8. Pre-flight checklist for the video agent

- [ ] App running at `http://127.0.0.1:7860`; `GET /api/omni/status` → `ready: true`.
- [ ] Confirm the 7 stills in §2 exist; re-run `tools/capture_tutorial_shots.py` if stale.
- [ ] Record the 6 `[CAPTURE NEEDED]` clips (Shots 1/3 are graphics-only) → `docs/demo/clips/`.
- [ ] Build the edit per §4; lay voiceover (§6) and music/SFX (§7).
- [ ] Export `docs/demo/phantom_grid_demo.mp4` (1080p) + `.srt`.
- [ ] If a dev-only setting was changed for Shot 8, revert it (check `.env`).