researchowl/docs/shortsmith-phases-4-6.md

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:

  "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.