personal-agent-os/memory-systems/agent-os/Video Stack/Lessons Learned.md

tags, updated

tags	updated
video-stack lessons	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.