make-viral-video

Files (9)

• SKILL.md
• manifest.json
• asset_cache.py · scripts/
• build.sh · scripts/
• codex-prompt.md · scripts/
• render.py · scripts/
• test_source_tag.py · scripts/
• validate_asset.py · scripts/
• verify_video.py · scripts/

SKILL.md (first lines)

# make-viral-video

Build a short (~30-60s, 1280×720 landscape, h264+aac) news-explainer video around a single source URL or news event. Designed for shareability via the **specificity-shape** framing (Chi's pick 2026-05-09): one striking number, image, or quote — not a comprehensive overview.

Distinct from Lucy's `recursive-meta-explorer` v8-v12 lineage (which optimized for completeness). This skill optimizes for *the one moment that makes someone share*.

## Usage

```bash
bash "$SKILL_DIR/scripts/build.sh" --topic "DoW UAP file release" --source "https://war.gov/UFO" --out results/
```

Produces:
- `results/viral-{ts}/video.mp4` — the rendered video
- `results/viral-{ts}/script.md` — the narration script
- `results/viral-{ts}/assets/` — fetched images with hash + validation log
- `results/viral-{ts}/build.log` — full build trace (codex iterations + validation results)
- `results/viral-{ts}/verify.sh` — script to independently re-validate the build

## Required tools

- `python3 ≥ 3.10` (PIL for frame composition)
- `ffmpeg` (encode + ffprobe gate)
- `gemini` API key (free tier, default) **OR** `openai` API key (fallback)
- Codex CLI (for script generation per pass)

## Architecture

### Three-phase build with self-heal

**Phase 1 — Source ingestion + script generation**
- Fetch the source URL (curl + Playwright fallback for JS-rendered pages)
- Codex generates a narration script + asset manifest with the **specificity-shape framing**:
  - One striking opening fact (the hook)
  - 3-5 supporting details (context)
  - One closing twist or open question (the share moment)
- Asset manifest is JSON: `[{"url": "...", "alt": "...", "purpose": "hook|support|closer"}]`

**Phase 2 — Asset validation (the self-heal loop)**

For each asset URL:
1. Fetch
2. Hash check: refuse duplicates (catches the v12 PR46-404-dupe pattern)
3. Content-type check: must be image/* or fall back
4. 404 detector: known-404-page hash list + OCR keywords ("404", "page not found", "Not Found")
5. Resolution check: ≥600×400 (sub-thumb assets are not viral-grade)
6. Re-fetch on failure with up to 2 retries
7. **If validation still fails** → script regen with that asset removed, NOT a silent skip

If 3+ assets fail validation, escalate to user (don't ship a video with placeholder content).

**Phase 3 — Render + pre-publish gate**

1. Compose frames via PIL (templates: hook-card / asset-with-caption / closer-card)
2. TTS narration via Gemini Flash (free) → fall back to OpenAI on rate-limit / error
3. ffmpeg encode
4. **ffprobe gate**: confirm h264 video stream + aac audio stream + 1280×720 dimensions + duration within ±5s of script estimate
5. If gate fails → report what's missing + don't post

## Visual constraints (specificity-shape)

Per Chi's "visual needs improvement too":

- **Hook card** (0-3s): single bold claim in large type (≥120pt), brand color background, no other text
- **Support cards** (3-X seconds before closer): real fetched image fills frame; caption overlay (semi-transparent strip, 36pt) with the *one* attributable fact about that image
- **Closer card** (last 3-5s): the share-moment text — not a recap. A pointed question, surprising number, or open-ended provocation.
- Aspect: 1280×720 (16:9). NOT vertical 9:16 (Lucy's v10/v11 cropped pictures because of this; landscape preserves news-photo composition).
- Typography: max 2 fonts (one display, one body). Body font must read at 36pt against any image (test: bottom-third of the frame must contain text or be black-strip overlay).

## TTS provider + voice selection

Default: `GEMINI` (free tier, 1500 req/day quota) → `OPENAI` (sage voice, ~$0.02/min) fallback.

Voice flags (per `render.py --help`):
- `--gemini-voice {Aoede,Charon,Kore,Puck}` (default `Aoede`)
  - **Aoede** — alto/neutral, default, fits documentary tone
  - **Charon** — baritone news-anchor; per Susan/Lucy 2026-05-10: matches news-explainer shape
  - Kore (mid expressive), Puck (high conversational)
- `--openai-voice` — free-text (used only on OpenAI fallback path)

## Series branding (Mini Wire)

The skill ships an end-card slate (last 2s) for series identity. Per Chi 2026-05-10:

```
MINI WIRE
by Echo Act IV · Sutando   (optional byline)
ep. 001 · 2026.05.10
```

Slate flags:
- `--series-title "Mini Wire"` — wordmark in brand red. Empty string skips the slate entirely.
- `--episode 001`
- `--date 2026.05.10` (defaults to today)
- `--byline "by Echo Act IV · Sutando"` — free-text, between title and episode line. Empty omits byline. **Caller controls every word — no hardcoded identity in render.py.**
- `--slate-duration 2.0` — seconds

The slate is **silent** — narration runs over the prior frames; slate gets a `apad=pad_dur=2` audio tail so AV streams stay synced through the silent end-card.

## Multi-image visual support

`render.py` reads `asset_manifest.json` and maps each entry's `purpose` to its frame:
- `purpose=hook` → HOOK frame bg
- `purpose=support` (idx N) → SUPPORT[N] frame bg
- `purpose=closer` → CLOSER frame bg
- Falls back to first non-`data-card-*` real image if no explicit asset

Manifest entries have shape:
```json
{
  "url": "https://example.com/photo.jpg",
  "local_file": "photo.jpg",
  "alt": "...",
  "purpose": "hook|support|closer",
  "badge": "Optional upper-strip badge text",
  "is_video": false,
  "source_tag": {
    "event_id": "pursue-release-01-2026-05-08",
    "case_id": "apollo-17-vm6-1972",

From sonichi/sutando, MIT.

More from sonichi/sutando