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. agg's static last-frame hold is left intact, so the final state lingers.

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], reading stdin / writing stdout by default). 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.

Output canvas

Every segment is then normalized (ffmpeg scale + pad) to one common resolution at a constant fps and yuv420p, so all segments share resolution/fps/pixfmt and concat into a single uniform stream (reel.mp4 by default).

That resolution is a fixed, landscape 16:9 canvas — REEL_WxREEL_H, default 1920x1080, a normal laptop screen — and is deliberately not derived from the segments. It used to be the per-axis max across every native segment, which silently produced a canvas whose aspect ratio belonged to neither a card nor a clip: PRD #339's reel took its width from the card (1140) and its height from a portrait 60x50 clip (1142), came out 1140x1142, and showed the terminal in a ~585px centre strip with black bars either side.

Segments are fit into the canvas (scale preserving aspect, then pad) and are never cropped — cropping a terminal would cut off content. So the canvas fixes the frame, but how much of it a clip fills remains a property of the recording:

• A ~16:9 cast fills it nearly edge to edge. In character cells that is roughly 4x as many columns as rows (a cell is about 1:2.3), e.g. 68x16 or 200x50.
• A portrait cast can only ever occupy a centre strip. A 60x50 terminal is 0.52:1 against a 1.78:1 canvas and covers ~29% of the frame — no engine setting can fix that; it has to be re-recorded.

The engine warns (non-fatally, per segment) when a clip's aspect is more than ASPECT_TOLERANCE (1.35) off the canvas, naming the percentage of the frame it will actually cover.

Checks the engine runs for you

Every run reports these to stderr, so a bad artifact is visible before it is published rather than after someone watches it. All are non-fatal — the engine's job is to render what it was given — but each one names a specific thing to fix:

Still worth doing by eye before publishing: extract a frame and look at it (ffmpeg -ss <t> -i reel.mp4 -frames:v 1 -update 1 frame.png). No automated check substitutes for seeing the thing.

Local smoke test

A re-runnable smoke builds a reel from a tiny self-contained fixture (two hand-written .cast clips + a manifest under .claude/skills/demo-reel/tests/fixtures/) in stitch-only mode (no network, no credentials) and asserts the result with ffprobe: non-empty file, exactly one video stream at the expected resolution (a single stream proves there is no resolution/fps/pixfmt seam between segments), yuv420p, constant 30/1 fps, and a duration between the sum of the per-card holds and the engine's own upper bound on it (card holds + each clip's re-timing budget + a small per-clip allowance for agg's trailing hold). That upper bound is the regression guard for the 10.4x stretch above. It is local-only (never CI):

task reel-smoke
# or directly:
.claude/skills/demo-reel/tests/smoke.sh

Privacy — uploads are PRIVATE by default, and that is a security boundary

upload.sh creates the video with privacyStatus: private, and reel.sh --publish passes no privacy flag at all, so the automated path can only ever produce a private video. upload.sh --privacy unlisted|public is the explicit escape hatch for a hand-run.

Why the default moved off unlisted: unlisted means anyone with the link can watch, and in this project's flow the link is written into the PR body and the changelog fragment, which flows into the public release notes. A reel clip is only eligible if the recorded run spun up a real agent, so every cast the reel stitches was written by a process holding live credentials. Uploading unlisted therefore put a credential-bearing recording on a publicly-reachable URL with no human between the two. Private keeps the same automation — the channel owner can always watch their own private videos, so an agent still uploads unattended and the link still goes in the PR — while making the human review a publication gate instead of a merge gate: flipping the video to unlisted before a release is a deliberate step somebody takes.

The video id survives a private → unlisted flip, so the link already in the PR and the changelog starts working with no re-upload and no link edit.

What private does not do. The upload has already happened; the bytes sit on Google's servers either way. Private contains a leak to the owner's own account. It does not undo one. And redaction upstream of this is a blocklist that can only remove values the harness registered — see docs/develop/e2e-lanes.md for its known gaps.

Verifying the upload path

The live YouTube upload cannot be a routine automated test, so it is verified by code review of upload.sh plus a one-time manual check: with the three YOUTUBE_* credentials exported, run

.claude/skills/demo-reel/reel.sh some-manifest.json --out reel.mp4 --publish

and confirm it prints an https://youtu.be/<id> URL that opens a private video — signed in as the channel owner it plays normally and shows a Private badge; signed out, or as any account the owner has not deliberately shared it with, it is unavailable. That asymmetry is the point (see Privacy below). All hosting lives in upload.sh alone, so swapping hosts later does not touch the rest of the engine.

Failure behavior

• Bad invocation (no manifest, unknown flag, --out without a value) prints usage to stderr and exits non-zero.
• A missing manifest file, malformed JSON, or a manifest that breaks the contract above fails with a specific message and a non-zero exit.
• A missing CLI (agg/ffmpeg/jq/curl) is a hard failure: it is reported by name in the pre-flight check before any work starts; the message points at docs/develop/demo-reel.md or to asking the agent, and does not embed setup steps.
• Missing --publish credentials degrade gracefully: the reel is still stitched and the local MP4 is kept; only the upload is skipped, with a "reel is at <path>; could not publish (missing …)" note. Stitch-only runs never need credentials.
• Runtime upload errors (expired/revoked token, exhausted quota, API disabled) are only knowable at upload time; upload.sh passes the API's raw error through rather than swallowing it.