---
tags: [video-stack, lessons]
updated: 2026-10-15
---
# Lessons Learned
Back to [[Video Stack - Overview]]

- A Kokoro-made reference makes Chatterbox clones flat with odd pauses. Use a real human reference (the user's recording worked well; leave more headroom, it peaked at -0.1 dBFS).
- Generate one sentence at a time (best of several seeds, ~200 ms gaps) to avoid strange pauses.
- Copywriting: short spoken sentences, numbers written as spoken words, ~105 words per 45 s, leave ~2 s spare. Number-heavy long lines made Prop 1 sound awkward.
- Gemini reads directions aloud unless they go in the style field.
- Music must add feel: civic_tension and piano B were rejected; option A (dark low strings, slow heartbeat pulse) chosen for Prop 1. If code-composed music misses twice, use a richer generator.
- ElevenLabs free tier was blocked for TTS ("unusual activity"); not retried.
- HyperFrames is easier for local models than Remotion (plain HTML per scene).
- Pick an authoritative male voice for political ads.


## Prop 39 critique: lessons (2026-10-16)

Source: Hermes's "Yes on 39" 1:38 16:9 draft (`C:\video\prop39`). Length 1:38 was intended — not a defect.

### 1. Captions lost every space ("areyou?Many", "governmentissuedID")
**Root cause:** `C:\video\prop39\build_hf.py` line 35 built word spans separated by a space, but the `.cap` CSS rule (line 171) was `display:flex;justify-content:center`. In a flex container each `<span>` becomes a flex item and whitespace-only text between items is discarded, so the words render glued together.
- [ ] `.cap` is `display:block` (never flex/grid). Center with `text-align:center`.
- [ ] Word spans joined with `' '.join(...)` — real space text nodes.
- [ ] Run `python scripts/qa/check_captions.py hf/ad/index.html vo/words.json` — must print `CAPTION CHECK OK`.
- [ ] Look at 3 stills with captions on screen and read them aloud.

### 2. Safe zones
- 16:9 1920x1080: title-safe 5% → 96px left/right, 54px top/bottom. Nothing (DRAFT tag, logos, header) outside it.
- Captions bottom edge ≥ 12% from the bottom (≥130px at 1080p), so player bars don't cover them.
- 9:16 1080x1920: top 250px, bottom 430px, right 90px are UI zones. Content and captions stay inside.
- [ ] Export stills of first scene, a caption-heavy scene and end card; check against the zones.

### 3. Voice was flat (uniform pauses)
- Political = Gemini **Charon**; business = **Kore**. Steer delivery in `--style`, never in the text.
- Natural punctuation, contractions ("it's", "don't"), mix short and long sentences.
- Vary gaps between sentences 150–400ms (longer before the big point, shorter in lists). Never one fixed gap.
- [ ] Listen to the whole VO once, start to finish, before building visuals.

### 4. Persuasive copy — pick the mode first
- Decide: **neutral explainer** or **advocacy ad**. Write it in the brief and stick to it.
- Advocacy ("Yes on X") argues from line 1. No hedges like "other access concerns remain debated" or "laws vary" — those belong only in neutral explainers.
- Lead with the strongest lines (e.g. "When the process feels loose, people stop trusting it", "A secure election is a fair election").
- Cut procedural scenes (e.g. "best-efforts" data/reporting) that kill momentum.

### 5. Pacing
- 10–12s static slides feel like a deck. Something visible changes every 3–5s: a build, kinetic number, highlight, camera push, or cut.
- [ ] No scene element is static >5s (check the timeline).

### 6. Facts and disclosure
- Every stat (e.g. "36 states", Gallup/Pew numbers) has a source URL in `vo_review.md` / `sources.md`.
- No chart labeled "illustrative" presented as data: use real numbers with citation, or remove.
- A real "Paid for by ..." line replaces any "sponsor disclosure pending" placeholder before publishing.

## Pre-render QA checklist (Hermes must run all, every video)
1. [ ] **Captions:** `check_captions.py` passes; 3 stills read correctly with spaces.
2. [ ] **Safe zones:** stills checked (16:9: 96/54px, captions ≥12% up; 9:16: 250/430/90).
3. [ ] **Voice:** full listen; varied pauses; Whisper check has no misreads.
4. [ ] **Facts:** every number/claim has a source in `vo_review.md`; no "illustrative" data.
5. [ ] **Mode:** brief says neutral or advocacy; no copy contradicts it.
6. [ ] **Pacing:** visual change every ≤5s.
7. [ ] **Disclosure:** real "Paid for by" end card (political); DRAFT tag inside safe zone or removed for final.
Report each item's result to the user before delivering.