Demo Reel

Demo Reel engine

A reusable, repo-agnostic engine that turns an ordered manifest of {title, description, clip} entries into a single narrated MP4: for each entry it renders a title/description card, plays that entry's clip, then moves to the next — concatenated in manifest order. With --publish it uploads the result private to YouTube and prints the URL.

The engine knows nothing about Rust, tests, PRDs, or any specific repo. Its only input is a manifest.json. It is invocable by an agent (via this skill) and directly by a human or CI (reel.sh manifest.json --out reel.mp4).

Status: the full engine pipeline is wired. A run validates the manifest and prerequisites, renders a card per entry, stitches [card, clip, …] into one uniform MP4 (reel.sh → ffmpeg), and — with --publish and credentials present — uploads it private to YouTube (upload.sh) and prints the URL. The stitch path is covered by a re-runnable local smoke (task reel-smoke); the live upload is verified by code review plus a documented one-line manual step (see Verifying the upload path).

Usage

reel.sh MANIFEST [--out OUT.mp4] [--title TITLE] [--publish]

Examples:

reel.sh manifest.json --out reel.mp4                                   # stitch only, no upload
reel.sh manifest.json --out reel.mp4 --publish                         # stitch + upload private (title = "reel")
reel.sh manifest.json --out reel.mp4 --title "My demo reel" --publish  # stitch + upload with an explicit title

Manifest contract

manifest.json is the only contract between a caller and the engine. It is a JSON array of one or more objects, in the order the segments should appear:

[
  {
    "title": "mouse/button/001 — inline-shortcut label",
    "description": "Start the app, focus the dashboard, and confirm the Button widget renders its inline-shortcut label.",
    "clip": "recordings/mouse-button-001/full-stream.cast"
  },
  {
    "title": "Second segment",
    "description": "What this clip shows, in 1–3 plain-English sentences.",
    "clip": "clips/second.mp4"
  }
]

The engine rejects a manifest that breaks any of these rules, with a specific message and a non-zero exit:

• The top level is a non-empty JSON array.
• Every entry is a JSON object with non-empty string title, description, and clip.
• clip is a path to an existing .cast (asciinema v2), .gif, or .mp4 file. Paths are resolved relative to the current working directory. The format is intentionally open: a cast renderer is just one optional front-end, so an already-rendered gif/mp4 can be fed directly (this is what lets a different recording tool reuse the same engine).

Prerequisites

The engine checks these before doing any work and fails fast with an actionable message naming exactly what is missing; it never self-installs anything.

Always required (CLIs on PATH):

Required only with --publish — YouTube Data API v3 OAuth credentials, read from the environment (never hardcoded). In this repo they are sourced from vals / .env.vals.yaml:

Stitch-only runs (no --publish) do not require any credentials. The one-time OAuth provisioning is documented in docs/develop/demo-reel.md.

How a reel is built

For each manifest entry, in order:

1. Card. A synthetic asciinema cast paints the bold bright-cyan title and a bright-white, left-aligned, vertically-centered description as terminal text, on the engine's own fixed CARD_COLSxCARD_ROWS grid (84x20 — shaped ~16:9 in character cells so a card fills the output canvas rather than letterboxing inside it). CARD_ROWS is a minimum: a long description grows the grid taller and the font shrinks to match, so text scales instead of clipping. The card's hold duration is a flat CARD_HOLD seconds (default 4s, env-overridable), independent of how much text the card carries: a fixed, deliberately short hold keeps the reel moving, and a viewer who wants to read a long description pauses the video rather than the reel parking on every long card. The hold is enforced at the ffmpeg level — a single painted still is frozen from the rendered card and looped to exactly the hold duration — so it is decoupled from agg's idle handling (which would otherwise collapse the static tail to a couple of seconds).
2. Clip. A .cast is first re-timed (retime.sh rewrites its event timestamps for a watchable cadence — see below), then rendered through agg at its recorded terminal grid; a pre-rendered gif/mp4 is used as-is (no re-timing).

Both are rendered at an agg font size fitted to the output canvas, not a fixed one. A terminal grid carries no pixel size of its own, so choosing the font is how the engine gets glyphs rasterized at output resolution: a 68x16 cast at font 16 is only 674x381, which on a 1080p canvas is a ~2.8x upscale of already- rasterized text (mush); at the fitted font (45) it renders 1896x1071 and stays sharp. Set CLIP_FONT_SIZE / CARD_FONT_SIZE to pin a font and skip the fit.

Clip re-timing

e2e casts are recorded at machine speed, so their raw timeline is unwatchable: a keypress and the full repaint it triggers land within a millisecond of each other, while short real waits (daemon startup, polling, debounce) sit between them. A single global agg --speed cannot fix this — slowing everything stretches the waits into dead air and still cannot spread coincident events apart. So before rendering, every .cast clip is passed through retime.sh, which rebuilds the timeline from the event payloads (rendering then runs at CLIP_SPEED 1.0):

The contract: the re-timer re-distributes time, it does not manufacture it. Time reclaimed from dead air is re-spent holding operations, so the output totals about max(MIN_BUDGET, the input duration) — and never more than max(MIN_BUDGET, MAX_STRETCH × input), which is a hard ceiling that compresses everything proportionally if the base gaps alone would exceed it. When there is no dead air to reclaim, nothing is held and the clip plays at roughly real time. No cast can come out as a slideshow.

Two measured worked examples. A 28.7s cast of a real agent working, already smoothly paced (no gap over 0.03s), comes out at 32.3s — 1.12×, essentially unchanged. A synthetic cast of 6 repaints separated by 3s waits — 15s that is almost entirely dead air — comes out at 7s, with each repaint held the full OP_HOLD 1.4s: the waits are gone, every operation is now visible, and the whole thing is shorter than the original.

Each event is classified into one of three kinds, by payload size and content:

• op — a payload larger than SIZE_THRESHOLD bytes is a full-region repaint (opening a deck/form/pane). Consecutive large chunks within COALESCE_GAP of each other are one logical repaint and are coalesced into a single step. An op is held after the repaint (up to OP_HOLD) so the new state is actually visible — budget permitting.
• type — a small payload that actually prints something is a typed character (ratatui emits a minimal diff per keypress). Each gets its own step, at least TYPE_GAP apart, so typing replays at a readable speed.
• tick — a small payload that prints nothing: pure control sequences (SGR reset, show-cursor, cursor-position). That is the render loop's per-frame tail, not a keystroke, so it keeps its original gap (clamped to IDLE_CAP) and is never spread.

Any single gap is clamped to IDLE_CAP, which is what kills dead air while still reading as a pause.

The final frame is held for a sized beat, not agg's default. Left alone, agg holds a clip's last frame for its default --last-frame-duration (3s in the pinned 1.9.0) on top of whatever tail the cast already spends on that final state — issue #365 measured PRD #341's reel ending on 5.27s of one identical frame, ~2.2s of cast tail plus agg's hold. So reel.sh sizes the hold per clip. It asks retime.sh --trailing how many seconds the retimed cast runs after its last visible change, renders the cast with that tail cut out (retime.sh --cut-tail moves the tail's events onto the last change's timestamp, so their cursor state still lands in the final frame), and passes --last-frame-duration max(CLIP_FINAL_DWELL, tail + CLIP_LAST_FRAME). The tail is folded into the hold rather than left in the cast because agg emits a frame only when the image changes: a tail of ticks that move nothing renders as no time at all, while one whose ticks move the cursor renders up to the last move, and telling the two apart takes a terminal emulator. CLIP_LAST_FRAME (default 1s) is the closing beat after the tail; CLIP_FINAL_DWELL (default 2s) is the least total time the final state stays on screen. The floor is for a cast that ends on its payoff — a test that stops recording the moment its assertion matches paints the answer at or near its last event, with little or no tail, and would otherwise show it for about one second. At the defaults, a cast with a tail of at least 1s gets nothing from the floor, so a clip with issue #365's ~2.2s tail ends on ~3.2s of final state instead of 5.27s. Both are env-overridable, in seconds of reel time (the tail is divided by CLIP_SPEED, which agg applies to the cast but not to its last-frame hold). Cards are unaffected: their hold is CARD_HOLD, enforced at the ffmpeg level.

A visible change here is any event that is not inert, and inert is deliberately narrower than the re-timer's tick: only SGR attributes (which affect later writes, not what is painted), cursor show/hide, and cursor positioning or movement — the render-loop tail. A tick is anything that prints no characters, which also covers erase, scroll and newline; those do change the screen, and counting them as tail would overstate how long the final state has been up and shorten its hold.

Why content and not size alone. PRD #339's published reel turned a 15.5s cast into a 161s video (10.4×), and the classifier is why: it called every small payload a keystroke. A ratatui render loop emits a per-frame tail of SGR-reset + show-cursor + cursor-position that prints nothing at all, and those tails are the overwhelming majority of a cast's events — so each was given its own 100ms "typed char" step, and each coalesced repaint was then unconditionally held 1.4s on top. Re-measured on that test's replacement recording (28.7s, 1621 events: 1565 ticks, 44 real typed chars, 12 repaints), the old re-timer produces 172.4s — 1609 × 0.1s of fabricated typing cadence, which is ~93% of the total — while the new one produces 32.3s. Both failure modes are closed: tick events are no longer mistaken for typing, and OP_HOLD is granted only out of reclaimed slack under the duration budget.

retime.sh is repo-agnostic (it operates on any .cast) and standalone (retime.sh [INPUT.cast] [--out OUT.cast] [--trailing | --cut-tail], reading stdin / writing stdout by default; --trailing and --cut-tail measure and remove the final-state tail described above instead of re-timing). Its tunables are env-overridable, like the engine's CLIP_SPEED — SIZE_THRESHOLD (80) is in bytes, MAX_STRETCH (1.6) is a ratio, everything else is in seconds: TYPE_GAP (0.1), OP_HOLD (1.4, a maximum now), IDLE_CAP (0.4), MIN_BUDGET (8), COALESCE_GAP (0.05). (IDLE_THRESHOLD is gone — every gap is simply clamped to IDLE_CAP, so there is no separate "is this a real wait" threshold.) CLIP_SPEED (default 1.0) remains as a global multiplier layered on top of the re-timer for the rare clip that wants a uniform nudge; note that it multiplies duration outside the re-timer's budget.