Psychopomp explainer reels

An explainer reel is several independently authored Scene Plans joined on one clock: behavior stories on the GPU Stage (orbs, cards, beams, packets, camera, bloom), pinned Callouts, Rolling Numbers, changes as animated Stepped Diffs, captions in a terminal voice, and optional spoken narration. When narrated, every visual beat waits for a phrase in the transcript, so re-voicing re-times the film automatically.

The working examples are in

scenes/pr-walkthrough

src/flagship.rs

(#50825 as a Stage film that zooms into its code),

src/stop_stage.rs

(#50042 combining Stage, Callouts, Rolling Number, and a Zoom into an annotated code diff), and

src/lib.rs

(the five-PR reel with sequence diagrams). Copy their shape; do not start from a blank crate. Component payloads, channels, and commands live in

SCENE_PLANS.md

("Make A Narrated Explainer Reel") and terms in

CONTEXT.md

; read both before authoring. Engineering rules are in

AGENTS.md

Steps

Establish the facts. For each change, read the actual diff and PR description (
```
gh pr diff
```
,
```
gh pr view
```
) and write one sentence each for the broken behavior, the fixed behavior, and the change. Done when every claim you will narrate is traceable to code, a test, or a reproduced run; mark anything you could not verify and keep it out of the script.
Write the script as
```
scenes/<name>/narration/script.json
```
, one clip per part: intro, then per change
```
<slug>-before
```
,
```
<slug>-after
```
,
```
<slug>-code
```
, then outro. Follow STORY.md when writing it. Done when each clip is under about 30 seconds spoken and every planned visual beat has a distinct anchor phrase in it.

Voice it (optional). Draft first with no credentials (

--draft

uses macOS

say

), or synthesize final narration with ElevenLabs (

engine: "elevenlabs"

, default model

eleven_v4

) or Fish Audio (

engine: "fish"

json

{
  "engine": "elevenlabs",
  "model": "eleven_v4",
  "voice": "<elevenlabs-voice-id>",
  "settings": { "stability": 0.5, "similarity": 0.7 },
  "clips": [
    { "id": "change-before", "text": "[warm, conversational voice] ..." }
  ]
}

# Draft (no API key required)
bun scripts/narrate.ts scenes/<name>/narration/script.json --draft

# ElevenLabs (requires ELEVENLABS_API_KEY and script.voice)
ELEVENLABS_API_KEY=... bun scripts/narrate.ts scenes/<name>/narration/script.json

# Fish Audio (requires FISH_AUDIO_API_KEY)
FISH_AUDIO_API_KEY=... bun scripts/narrate.ts scenes/<name>/narration/script.json

scripts/narrate.ts

normalizes loudness, transcribes word timings with Whisper, and writes

<id>.mp3

<id>.words.json

, and

narration.json

. When switching voices or engines, rebuild the Scene Plan against the new word timings.

Or declare the narration in the Scene Program with

psychopomp-media

(SCENE_PLANS.md, "Declare Narration And Sound"):

media.say(id, &voice, text)

media.dialogue

media.sfx

, and

audio.derive(Effect::pitch(..))

, then

media.finish()?

. Each line is generated once and recorded in

media.lock.json

; later runs call nothing unless a declaration changed, and ElevenLabs words come from its character alignment with the script's spelling. Check the cost first with

PSYCHOPOMP_MEDIA=plan cargo run -p <crate>

(zero API calls), time with

PSYCHOPOMP_MEDIA=draft

, and clean up with

PSYCHOPOMP_MEDIA=prune

. Move a narrate.ts scene with

cargo run -p psychopomp-media -- adopt scenes/<name>/narration

(no regeneration). Done when a plain run reports every resource

Author the Scene Program in
```
scenes/<name>
```
(the workspace picks it up; add it to
```
verify.json
```
with a few key times). Use
```
psychopomp::score
```
(
```
SCENE_PLANS.md
```
, "Author With The Score DSL") so
```
PlanBuilder
```
is the only
```
mut
```
binding and every actor (
```
Stage
```
,
```
Camera
```
,
```
Caption
```
,
```
Callout
```
,
```
RollingNumber
```
,
```
Checklist
```
,
```
Meter
```
,
```
Bars
```
,
```
Subtitles
```
,
```
Confetti
```
,
```
Terminal
```
,
```
Chat
```
,
```
ChangedFiles
```
,
```
LowerThird
```
,
```
Lens
```
) is an immutable value whose methods return composable
```
Beat
```
s (
```
.then
```
,
```
.also
```
,
```
.with
```
,
```
.on_end
```
,
```
.after
```
,
```
.early
```
,
```
stagger
```
,
```
each
```
,
```
at!(scene, time => ...)
```
). Schedule clips with
```
Narration::reading
```
, build elements with
```
StageElement::card|orb|beam|packet|label|ring
```
and relative
```
psychopomp::layout::Placement
```
envelopes on
```
StagePost::RESTRAINED
```
, frame with
```
Caption::header|chip|footer
```
, and play sounds with
```
sfx::*.beat(id, gain_db)
```
(or
```
audio.beat(gain_db)
```
for
```
psychopomp-media
```
). Load the
```
explainer-motion
```
skill and apply it to every beat: cards
```
settle_in
```
, beams
```
connect
```
, messages
```
send
```
, replies wait for
```
.reply()
```
, impacts
```
hit
```
, the hero
```
orb_in
```
, the fix's
```
rewind
```
; use
```
Callout
```
to pin annotations to Stage elements or Editor code ranges and
```
RollingNumber
```
for live counters/timers; drive camera moves through
```
stage.camera()
```
(
```
establish
```
,
```
frame
```
,
```
follow
```
,
```
release
```
,
```
orbit
```
,
```
whip
```
,
```
dolly_zoom
```
). Reach for the visualization and text overlays instead of hand-building them from Stage labels and rings:
```
Checklist
```
for checks that run and resolve,
```
Meter
```
(
```
MeterPlan::countdown
```
) for a timeout ring,
```
Bars
```
for before/after numbers,
```
Confetti
```
for a success beat, and
```
Subtitles
```
(
```
SubtitlesPlan::from_spoken
```
) to burn in word-timed captions. Changes are
```
Diff
```
s of
```
keep
```
,
```
add(step)
```
, and
```
remove(step)
```
lines, each step keyed to a phrase. Done when
```
cargo run -p <crate>
```
writes the reel and
```
cargo run --release -- plan validate <reel>
```
reports valid. A missing phrase panics with its clip: change the anchor to words the transcript actually contains.
Review before rendering. Get segment spans from
```
plan inspect <reel>
```
, then contact-sheet each segment at its before, switch, after, and code beats:
sh
```
bun scripts/sheet.ts <reel> t1,t2,... --theme neutral --shutter --out output/sheet.jpg
```
When tuning the look, set
```
PSYCHOPOMP_SHADER_DIR=crates/psychopomp-render/src/render
```
and edit
```
stage.wgsl
```
/
```
stage_post.wgsl
```
: every frame and sheet picks up shader edits without a Rust rebuild. Then render one behavior segment with audio (
```
plan render <reel> out.mp4 --cue <scene-id>
```
) or a 2–3 second window (
```
--range a..b
```
) and inspect frames extracted during motion. Done when every segment has been looked at and no text overlaps, clips, or reads against the wrong chip.
Render and verify the whole reel once, after the sheets and short windows pass. Run it in the foreground with a long timeout and never end a turn while it is still running:
sh
```
cargo run --release -- plan render <reel> output/<name>.mp4 --theme neutral
```
Done when
```
ffprobe
```
shows 1920x1080, 60 fps, AAC audio, and a duration matching
```
plan inspect
```
, and loudness is near -16 LUFS with peaks under -1 dBFS.
Deliver the MP4 path. Commit the scene, narration assets, and any engine changes in Psychopomp with conventional messages.

Improving Psychopomp

When a reel needs something the engine cannot do, add it to Psychopomp rather than working around it in one scene: plan types and validation in

crates/psychopomp

, strict-channel preflight in

plan_runtime

, pixels in

render

, GPU-free tests plus an

#[ignore]

GPU test, and the docs

AGENTS.md

asks you to keep current. Run

cargo run --release -- verify baseline

before the change and

verify compare --expect <scenes you changed>

after it to prove every other showroom and film is untouched.

Build from small reusable pieces. Interpolation, easing, curves, shape ports, and connectors belong in

psychopomp::math

(organized like pmndrs

math

: core

lerp

remap

smoothstep

easing

curve

shapes

random

; glam vectors). Extend it instead of inlining math in a renderer or scene, and split renderers into one small helper per element, as

render/stage.rs

does. Keep

cargo fmt --check

cargo clippy --workspace --all-targets --all-features -- -D warnings

, and

cargo test --workspace

green.

psychopomp

NPX Install

Tags

SKILL.md Content

Psychopomp explainer reels

Steps

Improving Psychopomp