---
title: "How X Works — explain how something works with clean diagram visuals"
tier: hero
format: short-form-video
theme: explainer | education | how-it-works | edutainment
persona: science educator, product explainer, edutech creator, technical writer
duration: "1 topic → 45–90s vertical short in ~3–6 min"
budget_usd: "$0.40–$3.00 per short (4–7 scene images/clips + TTS + music + finishing)"
caps: ["gpt-image", "ideogram-v4", "recraft-v4", "flux-dev", "seedance-i2v", "ltx-q-i2v", "inworld-tts", "music", "hyperframes-caption", "ffmpeg-burn-subtitles", "ffmpeg-concat", "ffmpeg-mux", "ffmpeg-export"]
skills: ["short-form-video"]
showcases: []
status: "playbook (2026-06-08) — ported from the Pixelle-Video format study; runs on existing Storyboard caps. Showcase render pending."
reliability: 3.7 # 5 − image gen .3 − i2v .6 (1-2 animated steps; stills-only run scores 4.3) − tts .2 − music .2; finishing deterministic; captions/subtitles optional; no proven E2E showcase yet
---

# How X Works — explain a mechanism in 90 seconds

Point this at anything mechanical or conceptual — "how a microwave heats food", "how RSA encryption works", "how a hurricane forms" — and it builds a **clean explainer short**: a question hook, a simple analogy, a 3-step walkthrough of the mechanism, and a "so that's why…" payoff. Clear, calm, diagram-driven. Runs entirely on Storyboard's existing Livepeer caps.

## What you'll get

> **A finished reel = vertical 9:16 + voiceover + music + ~45–90s.** Pass `aspect_ratio: "9:16"` to `generate_project` (it now threads to every scene), set the i2v `duration` to 8–15s **on EVERY scene** and animate **all** of them, add `inworld-tts` narration (not the chatterbox default voice) + `music`, and **mux the bed with `audio_fill:"loop"`** so the score covers the whole reel. A silent landscape montage — or one whose music cuts out partway — is a draft, not a deliverable. See the `short-form-video` skill's *definition of done*.

A 45–90s **vertical (9:16)** explainer: 4–7 clean diagram / isometric / labeled scenes, a friendly clear narrator, light upbeat music, captions, and a finished MP4.

## The cap chain

```
topic ("how X works")
  → agent writes the explainer script + 4–7 scene beats (question → analogy → 3 steps → payoff)
  → generate_project           # clean diagram / isometric / labeled visuals per beat
       image: gpt-image | ideogram-v4 (best when in-image labels matter) | recraft-v4 | flux-dev
  → (optional) motion          # ltx-q-i2v (or seedance-i2v, resolution:"auto") for ONE or two animated steps (flow/rotation), 8–11s
  → inworld-tts                # friendly, clear narrator (NOT the chatterbox default voice)
  → music                      # "[Instrumental] light upbeat background, gentle, curious" — a 15s bed is fine; you loop it
  → hyperframes-caption        # step labels / number badges as overlays
  → ffmpeg-burn-subtitles      # spoken-word captions in post
  → ffmpeg-concat                                      # stitch the per-scene clips
  → ffmpeg-mux  audio_fill:"loop"                      # lay the looped, ducked score under the FULL reel
  → ffmpeg-export                                      # 9:16, 1080×1920
  # audio_fill:"loop" repeats a short bed over the whole reel — else the score cuts out, last third silent.
```

## Script structure (beats)

1. **Question hook (0–4s)** — pose it plainly. "How does your microwave heat food without a flame?"
2. **Analogy (1 beat)** — anchor it to something familiar. "Think of it like millions of tiny hands shaking water molecules."
3. **3-step mechanism (3 beats)** — Step 1 → Step 2 → Step 3, one scene each, labeled. This is the spine.
4. **Payoff (last beat)** — "…and that's why the edges stay cold but the middle's molten."

## Pacing & aspect

- **Calm and clear** — 8–11s per scene; the viewer needs time to read a diagram. 9:16, 1080×1920.
- Number badges / step labels via `hyperframes-caption` so each step is unmistakable.
- Music light and unobtrusive; never let it compete with the explanation: mux narration + looped bed via `ffmpeg-mux` (`audio_fill: "loop"`), bed ducked under the VO.

## Watch-outs

- **Render in WAVES — never fire every clip at once (tested the hard way, 2026-06-08).** Animating a whole reel by firing all its scene i2v jobs simultaneously — ×N reels — overwhelmed the SDK `/inference` worker (BYOC video caps have capacity ~2 each behind a single dispatch worker); a ~30-clip burst crashed it and most renders failed. Cap in-flight **video** renders at **≤4–5**, animate **one reel at a time**, and poll each batch to *done* before firing the next. Images are cheaper (cap ~4) but still wave large sets.

- **In-image text and labels are the trap.** Even though `gpt-image` and `ideogram-v4` are the *least bad* at readable text, they still misspell and mangle technical labels. Strategy: if a diagram needs precise labels, render it clean (no text) and add labels in post via `hyperframes-caption`. If you do let the model render text, **verify every word** before shipping.
- **Diagram accuracy.** A clean wrong diagram teaches the wrong thing confidently. Verify the mechanism is actually correct — the model will invent plausible-looking but false steps.
- **`gpt-image` is slow (tested).** It gives the cleanest explainer art but runs ~140–180s/scene and can hit the render deadline on 5 scenes — in testing a 5-scene `gpt-image` project timed out (the images still landed, but the job flagged it). For speed use `flux-dev` or `recraft-v4` (~10–20s/scene); reserve `gpt-image` for the few scenes that truly need its cleanliness, run them async, or keep the project to ≤3–4 `gpt-image` scenes.
- **Don't over-animate.** A How-X-Works reel reads better as crisp stills with one or two animated steps than as everything wobbling. Use `ltx-q-i2v` sparingly.
- **The multi-link quality ceiling.** If the script's analogy is weak or a step is confusing, gorgeous visuals won't save it. Read the 3 steps aloud — if you stumble, simplify.

## Cross-surface (MCP / CLI / Webapp)

- **MCP:** `generate_project` (diagram scenes) → `create_media` (TTS, music) → `hyperframes-caption` step labels → `director_export`.
- **CLI:** `livepeer story "how <X> works, 5 explainer beats, clean diagrams"` → TTS + music via `livepeer media create` → `livepeer media export --aspect 9:16 --caption steps.json --subtitles captions.srt`.
- **Webapp chat:** `explain how <X> works as a 60s diagram short` — the agent writes the steps and offers labels + finishing as follow-ups.

## Execution mode (autopilot / director / auto)

This is a multi-scene project, so pass a `mode` to `generate_project` to control the **pre-finish gate** (after every scene renders, before delivery): `autopilot` (certain brief → ship in one call, no pause), `director` (always pause for a human pick/steer before delivery), or `auto` (recommended — ship UNLESS the auto-critic is unsure: score < `confidence_threshold` (default 0.8), verdict `iterate`, or a flagged shot). Setting `mode` runs the project async (returns a `job_id`); resume a director/auto pause with `review_checkpoint` + `resume_from_checkpoint` (decision `continue` to deliver / `abort` to discard). Omit `mode` for legacy straight-through behavior.