# Phases 4–6 — more elaborate Shorts **Roadmap document.** Phases 1–3 are live: spec generation with grounding (phase 2), render via shortsmith, YouTube upload as private with a human publish click (phase 3). Today shortsmith renders **silent** vector motion graphics from 8 templates (`radar_sweep`, `track_map`, `data_card`, `scale_bars`, `orbit_track`, `signal_strips`, `document_quote`, `counter_close`). - **Repos touched:** mostly `git.chemavx.xyz/chemavx/shortsmith`. researchowl changes are small and called out explicitly per phase — the live-contract design (`GET /templates` injected into the prompt at generation time) means new templates and new spec fields reach the generator with little or no code here. - **Contract rule for every phase:** additive and optional. An existing valid spec must stay valid; a pod running old researchowl must keep producing renderable specs. No breaking field renames, ever. --- ## 0. The gate — data before work Do not start phase 4 until 3–4 real Shorts are published and have a week of YouTube Analytics. The decision is not aesthetic, it is a retention curve: | Signal in Analytics | Diagnosis | Order | |---|---|---| | Viewers swipe in the first 1–2 s | Silent open kills the hook | Phase 4 first | | Retention holds, then decays evenly | Format works, ceiling is production value | Phase 5 first | | Retention fine, views low | Distribution problem, not video problem | Neither — titles/tags/posting time | Four videos of data beat any amount of a priori taste. The phases below are ordered by the expected outcome (audio first), but the gate can reorder them. --- ## Phase 4 — sound The largest single lever. A silent Short is penalised de facto: retention is the algorithm's primary signal and silence invites the swipe at second one. Three deliverables, shipped in this order because each is useful without the next. ### 4a. Music bed + transition SFX - shortsmith: new **optional** top-level spec block: ```json "audio": { "track": "static_dread", "volume_db": -14 } ``` A small curated set of royalty-free tracks (3–5, matching the channel's tone) baked into the shortsmith image as assets. Track names are advertised in the `GET /templates` response (a new `audio.tracks` key) so the prompt can list them without hardcoding — same reasoning as the template schemas. ffmpeg mixes at final assembly; a short whoosh on each shot boundary comes free from the same mix. - researchowl: **zero code**. The prompt gains one line ("pick a track from: …", fed from the contract fetch). Old specs without `audio` render silent, as today. - Determinism holds: same spec, same output. ### 4b. Narration (TTS) + burned-in captions These two ship together: most Shorts are watched muted, so the captions matter more than the voice — but both come from the same new field. - Spec: each shot gains an optional `narration` string. **When present, the shot's duration is derived from the synthesized audio length plus padding** (clamped to the template's min/max) — voice-first timing, not text-squeezed-into-a-window. `duration` stays valid for shots without narration. - shortsmith: TTS engine local and free — Piper or Kokoro, CPU-realtime, **model version pinned in the image** so renders stay reproducible. One voice, always the same: the voice is channel identity, not a per-video choice. Captions burned from the narration text, word-grouped, styled like the existing typography. - Fallback (repo convention): if TTS fails, render with music only and report it — degrade, don't die. The job must not fail because a phoneme did. - researchowl — two small, real changes: 1. **Grounding must cover `narration`.** It is exactly the field an LLM fills with confident paraphrase. `grounding.py` extracts from spec props today; add the narration strings to the extraction. Same deterministic path, no LLM. 2. Prompt: narration guidance (spoken register, ≤ ~25 words per shot, hook in the first line — the first two seconds decide the swipe). - Optional later upgrade: ElevenLabs behind an env var (~$0.10–0.30/Short) if the local voice grates. Start local; the constraint on volume is review time, not money. ### Phase 4 tests | Area | Assert | |---|---| | Contract | Spec without `audio`/`narration` still validates and renders (today's golden spec passes untouched) | | Timing | Narrated shot duration == audio length + padding, clamped to template bounds | | Fallback | TTS failure produces a music-only render plus a warning, not a failed job | | Grounding (researchowl) | A fabricated figure placed only in `narration` is flagged | | Determinism | Same spec twice → byte-identical audio track (pinned model) | --- ## Phase 5 — archival assets (the Ken Burns template) The most differentiating work for this niche: real declassified documents, newspaper clippings and official photos, panned and zoomed with a highlight box. It is what separates the channel from generic AI slop — and it extends the grounding philosophy to imagery, which is why the editorial rule below is load-bearing. **The rule: only assets that come from the session's own sources.** No stock, no image search, no "looks right". If the scraper didn't see it, the Short doesn't show it. - shortsmith: - New template `archive_pan`: props = asset reference, start/end crop keyframes, optional highlight rectangle, mandatory `credit` line (rendered small, always). - New endpoint `POST /assets` — content-addressed upload (sha256 as the id), so specs reference immutable hashes and re-renders can't silently swap an image. - researchowl: - Asset extraction during scraping: `og:image`, inline images above a size floor, PDF pages rendered to PNG. Stored under `/data/assets/{session_id}/` with **the source URL persisted per asset** — provenance is the whole point. - Spec generation: the prompt receives the asset list (id, source URL, dimensions, nearby text) and may use `archive_pan` shots. - The claims report grows an assets section: every asset used, with its origin URL, so the human gate reviews imagery the same way it reviews figures. - Rights posture: US federal government works (Blue Book, NARA scans, official releases) are public domain — the bulk of this channel's material. Anything else the human reviewer judges at the gate that already exists; the credit line renders regardless. - This is the largest phase. It is two deliverables in truth (asset pipeline; template) and the pipeline is useful alone — extracted assets improve the *blog* posts too. ### Phase 5 tests | Area | Assert | |---|---| | Assets | Content-addressing: same bytes → same id; spec referencing an unknown hash is rejected at validation with the exact path | | Provenance | Every stored asset carries a source URL; claims report lists all used assets | | Template | Keyframe interpolation renders deterministically; missing `credit` fails validation | | Editorial | A spec referencing an asset from another session is rejected | --- ## Phase 6 — `short_es` for Zona de Exclusión Nearly free once the format is proven (phase 2 doc, §11, still true): shortsmith draws whatever strings it gets and does not care about language; with phase 4, TTS needs a Spanish voice (Piper has good ones — pin it like the English one). The work is the prompt, the narrative shapes, and the stopword list — all researchowl, all small. Do it only after the EN format has produced retention worth copying. A bad format in two languages is twice the bad format. --- ## Explicitly out — generative video No Veo, no Sora, no Runway. Not primarily for cost: a documentary channel whose premise is *"the numbers come from primary sources"* cannot mix in fabricated "recreations" without undermining exactly what the grounding pipeline protects. If ever revisited, it would need an on-screen RECREATION label and a very good reason. There is no current reason. --- ## Free work — no phase required Available any time, zero researchowl changes, because the contract is fetched live: - **New vector templates** in shortsmith: `timeline`, `before_after`, `map_zoom`. Same discriminated-union pattern as the existing eight; they appear in the prompt automatically on the next generation. - **Narrative tuning** in the prompt: sharper first-shot hook, the hook → evidence → unresolved question → CTA arc. Costs one commit, no deploy risk beyond a prompt change. --- ## Implementation order One change at a time, verified before the next — and phase-gated by the Analytics data from §0. 1. Publish 3–4 Shorts with the current pipeline. Read the retention curves. 2. Phase 4a (music). Smallest change, immediate feel upgrade, proves the `audio` contract extension end to end. 3. Phase 4b (narration + captions), grounding extension in researchowl **first** — build the check before the thing it checks, same reasoning as phase 2 §12. 4. Free-work templates whenever convenient; they ride along. 5. Phase 5, asset pipeline before template — the pipeline is useful alone. 6. Phase 6 last, and only if the numbers say the format earned a second language.