docs(short): roadmap de fases 4-6 — audio, material de archivo, short_es
Build & Deploy ResearchOwl / build-and-push (push) Successful in 7s
Build & Deploy ResearchOwl / build-and-push (push) Successful in 7s
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
ChemaVX
co-authored by
Claude Fable 5
Claude Fable 5
parent
960990327a
commit
1fd0c1b3d6
@@ -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.
|
||||
Reference in New Issue
Block a user