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

Corrected after reading the shortsmith source (the first draft of this section assumed silent renders and proposed royalty-free tracks on disk — both wrong). shortsmith has synthesized audio by design: numpy only, no samples, no licensing exposure, deterministic to the sample, with the spec's audio: {preset, silence} block and the validated sonar composition guarded by a reference gate. The right 4a for that architecture is a wider palette of synthesized presets, not files.

4a. The preset palette — shipped 2026-08-06

• shortsmith: pulse (sub-bass heartbeat tightening past the midpoint — tension, for debunks) and static (shortwave noise bed, seeded crackles, faint drone — document drops) joined sonar and none. Same arc grammar (nothing starts inside a silence window, closing swell, same limiter chain); static's noise comes from seeded legacy RandomState streams, which NEP 19 froze — deterministic on any numpy. GET /audio publishes the palette with one-line mood notes.
• researchowl: the client fetches the palette (404 → the baseline pair, fallback convention), validate_spec takes it as the live source of truth for audio.preset, and the prompt offers it with the mood notes so the model matches preset to narrative shape. The edit loop accepts it too: changing audio.preset in the /short_spec file and re-sending is the free way to audition the palette.

Deferred from 4a: shot-boundary transition accents

A synthesized whoosh at each cut. Deliberately not done yet: audio.py's presets are fixed compositions that know nothing about the shots, and that one-way line is worth keeping until the palette itself proves its value. If it happens, it is an opt-in Audio.transitions flag with boundaries passed alongside silence — additive, and sonar's reference gate must not notice.

4b. Narration (TTS) + burned-in captions — shipped 2026-08-06

What actually landed, and where it differs from the plan below:

• Piper as a standalone binary, not the PyPI package: piper-phonemize is a compiled extension whose wheels chase the interpreter version, and the image's Python is pinned by digest. Binary, voice and config are all pinned by sha256 — the voice model is the channel's sound.

• --noise_scale 0 --noise_w 0 is load-bearing. Measured before building anything: the same line twice gave 5.668 s and 5.796 s with different hashes. With the flags, three runs and one hash. Without that probe the phase would have shipped a renderer that quietly stopped being deterministic.

• Declared duration became a floor, as planned — plus a consequence the plan missed: audio.silence windows are written in absolute seconds, so a stretched shot slides them onto the wrong line. They are now remapped through the shot they pointed at.

• One caption size for the whole video, fitted against the longest group. Per-group fitting made the type jump between cues, which is the clearest tell of an auto-captioned video.

• researchowl got the grounding extension first, as the order below demanded, and one thing that order revealed: with the voice repeating on-screen figures, claims had to be de-duplicated by canonical unit ("35,000 FT" and "35,000 feet" are one claim) or every narrated Short would double its own review report.

• researchowl's estimate of the voice had to be measured, not assumed (2026-08-12). It shipped with 14.2 characters per second, taken from a single line, and that overshot every narration by about a fifth — four to six seconds on a whole Short, enough to make the spec writer rewrite videos that were already inside the target. Every generation since narration shipped had spent all three attempts on it. Synthesizing the 28 narration lines the bot had actually written gave 18.5 char/s plus 0.25 s at every full stop, which is the term that matters: Piper's SENTENCE_SILENCE is per sentence, so "Witness identities. Sensor details. Locations redacted." costs three quarters of a second that a characters-only model gives away. Estimates now land within half a second of the three rendered MP4s. The lesson is the older one restated: a constant taken from one sample is a guess with a decimal point.

• The spec writer was under-declaring because the prompt asked for three things that could not all be true (2026-08-13). Every narrated spec the bot had written declared less time than its own narration needed on three or four shots out of five or six — 3.8 to 8.2 seconds of drift per Short. The video still came out the right length, because plan() grows the shot; what was wrong was that the spec described a visual rhythm that never rendered. The cause was not a lazy model. The prompt asked at once for lines of up to 18 words, shots of at most 6 seconds, and enough declared time for the line — and 18 words need 7.3 s, so the set is unsatisfiable. The model broke the only one of the three that nothing checked. Three fixes, all deterministic and none costing a generation to find: the taught rule got the per-sentence term it was missing (words/2.75 + 0.5 fell short on 14 of the 28 measured lines, by up to 2.27 s — so even perfect obedience under-declared); the word cap is now derived from the shot cap rather than written by hand, so the contradiction cannot come back; and the worked example, which violated its own rule on two of its six lines, was cut to obey it. That last one is the lesson worth keeping: the example is the strongest signal in the prompt, so an example that breaks a rule teaches the breakage, whatever the prose says. It is the same finding as "el ejemplo del prompt habla, y por eso los specs vuelven a hablar", arriving a second time.

• A validation rule that fires too late costs a whole generation, not a retry (2026-08-13). researchowl deliberately did not replicate shortsmith's cross-field @model_validators — they are not in the published JSON Schema, and the reasoning was that the server's 422 covers them. It does, but at the wrong moment: the 422 arrives at render time, after the spec loop has finished, so the spec is not rewritten, it is handed back to a human. Session 162 (Trans-en-Provence) died exactly there — valid on the first attempt, 39 claims grounded, and no video because a scale_bars shot had three bars and a quote. Replicated locally, the same spec cost one retry and rendered. The rule to carry forward: where a check runs decides what it costs, and "the server will catch it" is only true if the server catches it while you can still act. The error strings are copied from shortsmith word for word, because they are handed to the model verbatim and two wordings of one failure is how an error message stops being useful.

• A check can be defeated by the shape of the thing it checks (2026-08-13). The grounding checker joins a quote list before looking for it, which is what closed the Socorro hole in August: “LIKE ALUMINUM + SMOOTH, NO WINDOWS” join into one sentence, no source contains it, rejected. But the join is defeated by giving each line its own pair of quote marks — then they are two quotes, each grounded on its own, and the spec passes in silence while the frame draws a sentence nobody said. Two of the five Shorts generated that day had it. The rule now checks the shape rather than the content — two opening marks are two quotes, whatever the sources say — and it runs in validate_spec, so it costs a retry. It is a hard error and not an editorial note on purpose: a fabricated quote attributed to a named witness is the worst failure this system has, and a retry is cheap against it. Worth watching: given the choice between picking a shorter verbatim span and dropping the quote marks, both rewrites dropped the marks. Truthful, but a paraphrase is weaker than a quote — if that becomes the habit, the fix is in the prompt, not the check.

Original plan, kept for the record:

4b (as planned). 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 — done (the preset palette, see above; the user chose to skip the gate for the mechanism and let the published Shorts test the palette itself).
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.