From 1fd0c1b3d60861a0e34ee08dd5772e3234b65278 Mon Sep 17 00:00:00 2001 From: ChemaVX Date: Thu, 6 Aug 2026 14:12:10 +0000 Subject: [PATCH] =?UTF-8?q?docs(short):=20roadmap=20de=20fases=204-6=20?= =?UTF-8?q?=E2=80=94=20audio,=20material=20de=20archivo,=20short=5Fes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5 --- docs/shortsmith-phases-4-6.md | 181 ++++++++++++++++++++++++++++++++++ 1 file changed, 181 insertions(+) create mode 100644 docs/shortsmith-phases-4-6.md diff --git a/docs/shortsmith-phases-4-6.md b/docs/shortsmith-phases-4-6.md new file mode 100644 index 0000000..737aace --- /dev/null +++ b/docs/shortsmith-phases-4-6.md @@ -0,0 +1,181 @@ +# 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.