compose

Compose

This atom owns the full video assembly pipeline. You receive raw outputs from the capture stage and produce a single polished artifact. Follow the pipeline below step by step.

Inputs

The command or capture stage should have provided a handoff with two sections:

Mechanical (structured)

• clips: paths to raw recordings (.cast, .mp4, .webm); stills are not clips — see "Screenshot-only artifacts"
• driver: tuistory | true-input | agent-browser | cua-driver
• layout: single | side-by-side
• labels: text for each clip (e.g., "BEFORE (dev)", "AFTER (PR)")
• speed: playback multiplier applied once, by the composition, to every clip (default 1x)
• fidelity: compact | standard | inspect (optional; omitted => side-by-side=inspect, single=standard)
• title: text for the title card
• subtitle: one-sentence summary
• sections: text banners for chapters [{t, title}] (optional)
• keys: keystroke events [{t, label, dur?}] (if overlay requested)
• showcase: preset name -- macos, minimal, hero, presentation, factory, factory-hero
• effects tier: utilitarian | full | none (see "Choosing effects at compose time" below)
• output: desired output path

Creative (natural language)

Free-text guidance on what to emphasize: which moments to hold, what the title card should convey, whether phase cards are warranted, how to trim dead time. Use this -- along with the effects tier -- for editorial decisions, including choosing specific effects to apply.

Pipeline

1. Build props   →  construct the Showcase JSON props
2. Render        →  render-showcase.sh (converts .cast, stages clips, probes duration, renders, cleans up)
3. Finalize      →  verify and output

Remotion handles all compositing in a single pass — title cards, transitions, window chrome, backgrounds, keystroke overlays, spotlights, particles, noise, and color grading are all automatic. You construct the props JSON; the engine does the rest.

Remotion project & helper script

REMOTION_DIR=${DROID_PLUGIN_ROOT}/remotion
RENDER=${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh

Showcase mode vs Demo mode

Both use the same Remotion pipeline but target different visual registers.

	Showcase	Demo
Goal	Cinematic, high-polish marketing material	Clear, utilitarian demonstration — single or comparison, whichever the story calls for
Preset	factory, factory-hero, or hero	macos, minimal, or presentation
Effects tier	Full -- spotlight, zoom, callout, keystroke overlay. Go all out.	Utilitarian -- zoom for readability, keystroke overlay for user actions
Audience	External — landing pages, social, marketing	Internal — PR reviews, docs, QA

Decision rule: If the video will be seen outside the eng team, use Showcase mode. If it's for a PR description, internal demo, or documentation embed, use Demo mode. The visual polish layers (warm glow, particles, color grade, motion blur) are always present but their intensity is palette-driven — Factory presets produce rich cinematic warmth while Catppuccin presets stay subtle and cool.

Choosing effects at compose time

The command stage committed an effects tier (utilitarian, full, or none). Now that you have actual recordings, choose specific effects:

• Utilitarian: Add zoom effects for any small or hard-to-read text. Add keystroke overlay if user actions were captured. Skip spotlight and callout unless something is genuinely hard to find on screen.
• Full: Use the full palette. Spotlight the key proof points. Zoom into details. Add callout annotations where the UI isn't self-explanatory. Layer keystroke overlay throughout. Aim for cinematic -- the viewer should feel guided, not left to scan.
• None: Pass "effects": [] in props. Keystroke overlay is still allowed if committed separately.

Step 1: Choose fidelity and pacing

render-showcase.sh selects inspect for side-by-side and standard for single-clip layouts when fidelity is omitted; pass compact, standard, or inspect (in props or via --fidelity) to override. It is the only place fidelity is resolved.

Fidelity	Default output size	Remotion encode	Polish overlays	Best for
compact	1920x1080	H.264 CRF 21, JPEG frames	full grain + grade	Small embeds
standard	1920x1080	H.264 CRF 18, JPEG frames	reduced grain + grade	Single-panel demos
inspect	2560x1440	H.264 CRF 14, PNG frames	minimal grain + grade	Side-by-side comparisons / tiny text

.cast conversion behavior

render-showcase.sh converts .cast inputs through agg -> gif -> ffmpeg -> mp4 before Remotion render, using the asciicast's own cols/rows and fixed font metrics so element positions remain stable across fidelity profiles. Conversion runs at 1x with agg's idle-time compression disabled, so the mp4 keeps the recording's timeline (plus agg's 3s hold on the final frame); speed is applied later by the composition, exactly like .mp4/.webm clips.

CRITICAL: agg replaces ALL 16 ANSI colors with its theme palette. The render script uses a custom Droid CLI theme. If you manually run agg, never omit --theme and never use built-in themes like monokai or dracula.

The --theme flag accepts a comma-separated hex string (no # prefix): bg,fg,color0..color7 (10 values) or bg,fg,color0..color7,color8..color15 (18 values for bright variants).

Note: tuistory recordings of the Droid CLI typically emit NO color escape codes -- the CLI uses Ink's direct rendering which doesn't produce standard ANSI SGR sequences in the cast output. The theme's bg (first value: 181818) and fg (second value: e0d0c0, warm white) are the only colors that will affect the output. The warm-white fg avoids the cold blue-grey look of default themes.

For other terminals that DO emit ANSI color codes, build the full theme string from the terminal's actual color settings.

Pacing: Target the final video duration, not a speed factor. A blind multiplier either makes text illegible or leaves dead air.

Demo type	Target duration	Why
Single feature, 3-5 steps	30-45s	Viewer watches the whole thing in one breath
Before/after comparison, side-by-side	45-75s	Each panel needs time to land; frozen-vs-active contrasts need a beat
Multi-phase or complex flow	60-120s	Phase cards give the viewer reset points; rushing defeats the purpose

Targets are for the final video, which is the clips plus 7.5s of cards (4s title, 3.5s outro; see the duration checkpoint). Set the speed prop to hit the target: for a 60s target the clips get ~52s, so a 3-minute raw recording needs "speed": 3.5. If it's already 40s raw, use "speed": 1 or trim dead time instead. Trim first, speed second -- cut LLM thinking pauses, build waits, and network delays from the .cast with asciinema cut or by splitting segments, then apply a gentle speed-up only if still over target.

Overlay timing boundary: every overlay time in props (keys[].t, sections[].t, effects[].t/dur, codeAnnotations[].t/dur) is output-timeline seconds relative to content start. The composition applies speed to the clips only, never to overlay times. Capture logs raw recording seconds, so divide each timestamp by the speed factor (and subtract any trimmed lead) before writing props: a keystroke at raw t=6.0s in a 3x video is t=2.0s.

Non-.cast clips

.mp4 and .webm clips are staged unchanged and play at speed like converted casts. Re-encode them manually only if their pixel format or dimensions are invalid. .png files are refused as clips; stills belong in "Screenshot-only artifacts" below.

Clip aspect ratio (mandatory check for browser captures)

At the default 1920×1080 output with factory preset margins, panels come out roughly:

Layout	Panel aspect
single	~1760×920 (≈16:9 landscape)
side-by-side	~872×920 per panel (≈8:9, near-square / slight portrait)

.cast conversions target panel aspect automatically. Pre-recorded .mp4 / .webm clips do not — if the clip aspect doesn't match the panel aspect, the clip will letterbox (with the default objectFit: "contain") or crop (with "cover").

Common pitfall: browser captures are typically 16:9 landscape (e.g. 1280×720). Dropped into a side-by-side layout they render as a thin band with giant black bars above and below.

Two fixes, in priority order:

1. Re-capture at a panel-friendly viewport — go back to the capture stage and set viewport to ~960×1000 for side-by-side, ~1280×720 for single.
2. Pass "objectFit": "cover" in props — crops the clip edges to fill the panel. Acceptable when the relevant UI is centered and edges are expendable. Not acceptable if cropped content matters (e.g. sidebar UI cut off).

.cast clips rarely need this since their rendered aspect is derived from cols/rows; it's almost always a browser-capture concern.

Duration checkpoint (mandatory, before proceeding)

Check whether the planned speed factor produces a final duration within the pacing table's target range:

final_duration = 4s title + longest_clip_duration / speed_factor + 3.5s outro

This is the exact length remotion/src/lib/duration.ts gives the composition (frames are rounded up to whole frames at 30fps). The content sequence has padding for both 0.5s crossfades: the title crossfade precedes playback; the outro crossfade begins after the frame-rounded playback interval and shows held frames. The window chrome's own 0.5s entrance animation overlaps the first half-second of playback, so open recordings on a settled baseline. Any positive finite speed is valid, including one that shrinks the clips below a crossfade length.

The clips run for the longest clip; a shorter clip holds its final frame (it does not loop) until the sequence ends. For comparisons, record both clips to matched endings or the viewer sees one panel frozen while the other continues.

If final_duration is...	Action
Within the target range	Proceed
Below the minimum	Reduce the speed factor until the target is met. If even at 1x the clip is below the minimum, the recording is too short — return to capture and add more interaction steps.
Above the maximum	Trim dead time first (asciinema cut), then increase the speed prop

This checkpoint is not optional. A video that lands outside the target range fails verification.

Step 2: Build props

Choose layout

Default: single. One clip of the target/final state. New features, bug-fix proofs, walkthroughs, and README heroes all belong here.

Use side-by-side only when the story is fundamentally a comparison: regression (broken vs fixed), behavior-preserving refactor, or an explicit user request. Never fabricate a "before" clip to justify the side-by-side shape.

Save the showcaseSchema JSON to a temp file:

DEMO_TMP="$(mktemp -d /tmp/droid-demo-XXXXXX)"
PROPS="${DEMO_TMP}/showcase-props.json"

cat > "$PROPS" << 'EOF'
{
  "clips": ["demo.cast"],
  "layout": "single",
  "labels": [],
  "speed": 3,
  "title": "PR #11621 — Prevent session freezes",
  "subtitle": "Bash Mode blocks interactive commands and supports ESC cancellation",
  "preset": "factory",
  "keys": [
    {"t": 2.0, "label": "vim"},
    {"t": 5.5, "label": "sleep 100"},
    {"t": 8.0, "label": "Esc"}
  ],
  "sections": [],
  "effects": [],
  "speedNote": "3x speed",
  "windowTitle": "droid demo"
}
EOF

For a comparison flow, swap "clips" to two paths, "layout" to "side-by-side", and populate "labels" (e.g., ["BEFORE (main)", "AFTER (PR #11621)"]).

Use a run-scoped props path like $PROPS; do not reuse a global /tmp/showcase-props.json across rerenders or concurrent demos.

clipDuration is owned by the render script. It probes every clip with ffprobe and writes the longest duration in source seconds; the composition divides by speed. Do not set it by hand — to shorten a video, trim the source clip.

Props reference

Prop	Type	Required	Description
clips	string[]	yes	Overwritten by the render script with staged paths in command-line order; the positional clip arguments are the source of truth
layout	"single" | "side-by-side"	yes	Composition layout
labels	string[]	yes	Labels for each clip (visible in side-by-side; pass [] for single)
fidelity	"compact" | "standard" | "inspect"	no	Output quality/compression profile. Omit and the render script chooses by layout.
speed	number	no	Playback multiplier applied once by the composition to every clip (default 1). Overlay times are not scaled.
title	string	yes	Title card heading
subtitle	string	yes	Title card subheading
preset	preset name	yes	Visual preset — see table below
keys	Keystroke[]	yes	Keystroke overlay events (pass [] for none)
sections	Section[]	no	Section banners to mark chapters (pass [] for none)
effects	Effect[]	yes	Effect timeline (pass [] for none)
clipDuration	number	no	Longest clip in source seconds. Set by the render script; do not write it by hand.
speedNote	string	no	Shown on title card (e.g., "3x speed")
windowTitle	string	no	Text in the window title bar
width	number	no	Output width (default: 2560 for inspect, else 1920)
height	number	no	Output height (default: 1440 for inspect, else 1080)
objectFit	"contain" | "cover" | "fill"	no	How each clip fits its panel. Default "contain" (letterbox to preserve aspect). Use "cover" when clip aspect doesn't match panel aspect and you'd rather crop than see black bars. See "Clip aspect ratio" below.
codeAnnotations	CodeAnnotation[]	no	Timed syntax-highlighted code overlays shown during the main content sequence. See "Code annotations" below.
transitionStyle	"motion-blur" | "flash" | "whip-pan" | "light-leak" | "glitch-lite"	no	Presentation used for title→content and content→outro transitions. Default "motion-blur" preserves existing aesthetic. See "Transition styles" below.

Preset quick reference

Preset	Look	Palette	Best for
factory	Warm black bg, traffic lights, 12px radius, 80px margin	Factory (warm)	Official Factory content
factory-hero	Same as factory + gradient bg	Factory (warm)	Factory landing pages, social
hero	Gradient bg, generous margins, prominent shadow	Catppuccin (cool)	Non-Factory marketing
macos	Dark bg, traffic lights, clean frame	Catppuccin (cool)	General-purpose demos
presentation	Black bg, generous margins	Catppuccin (cool)	Slide decks, talks
minimal	No window bar, tiny radius, tight margins	Catppuccin (cool)	Docs embeds, inline clips

Keystroke schema

{ t: number, label: string, dur?: number }

• t: Time in seconds relative to clip start (not title card). Adjust for speed factor.
• label: Display text (e.g., "Ctrl+C", "vim main.rs")
• dur: Display duration in seconds (default: 1.2s). Auto-cut when next keystroke starts.

Section schema

{ "t": 2.0, "title": "Testing basic echo" }

• t: Time in seconds relative to clip start (not title card). Adjust for speed factor.
• title: Display text for the section header. Remains visible until the next section starts.

Effect types

Effect	Props	Description
fade-in	t, dur	Fade from black (schema-valid but not yet rendered by Showcase — emits a render-time warning)
fade-out	t, dur	Fade to black (schema-valid but not yet rendered by Showcase — emits a render-time warning)
zoom	t, dur, to: {x,y,w,h}	Directed zoom to a target region (30% in, 40% hold, 30% out)
spotlight	t, dur, on: {x,y,w,h}, dim?	Dim everything except a region (dim: 0–1, default 0.6)
callout	t, dur, text, at: {x,y}	Text overlay anchored to a point

Regions use percentage strings (e.g., "25%") relative to the video dimensions.

When to use effects

Effect	Use when…	Don't use when…
spotlight	Drawing attention to a specific region (error, status change)	The whole frame is relevant
zoom	Small text or detail that's hard to read at full scale	Content is already legible
callout	Annotating something the viewer might not recognize	The UI is self-explanatory
Keystroke overlay	Showing user actions (typing, key presses)	No user interaction in the clip

Less is more. One well-timed spotlight has more impact than five overlapping effects.

Code annotations

Timed syntax-highlighted code card laid over the captured video. Use for PR demos where the decisive source change needs to sit next to the runtime proof.

Field	Type	Required	Description
t	number	yes	Start time in seconds, relative to clip start. Adjust for speed factor (same rule as keys[].t).
dur	number	yes	How long the card stays visible, in seconds.
code	string	yes	Source text; \n for multiline; no trailing newline.
language	string	no	Prism language id (tsx, ts, py, rust, bash, ...). Default tsx.
title	string	no	Small caption above the code (usually a file path).
highlight	[{start,end}]	no	1-based inclusive line ranges with accent background + left border.
focus	[{start,end}]	no	1-based inclusive line ranges kept at full opacity; others are dimmed/blurred.
position	"top-right" | "center" | "bottom-left"	no	Default "top-right". Move to "bottom-left" if the captured top-right is load-bearing.

Keep it short — aim for ≤ 15 lines per card, hold for 3–6 seconds.

Transition styles

transitionStyle selects the title→content and content→outro crossfade presentation. Both transitions in one render share the same style. flash and light-leak derive their tint from the preset palette. Default motion-blur is always safe; preset-tier guidance lives in showcase/SKILL.md.

Style	Feel	Use when…
motion-blur	Subtle dolly, blur + opacity crossfade	Default for PR demos, Factory content, most showcase work
flash	Quick palette-tinted flash at midpoint	Bug-fix proofs where the "after" state should feel sudden
whip-pan	Horizontal pan + motion blur	Energetic showcase / marketing when pacing is fast
light-leak	Warm gradient sweep	Factory-branded landing/social clips
glitch-lite	RGB channel offset + horizontal band	Security/vulnerability proof, terminal aesthetic; never default, never twice

Step 3: Render

Use the render script — it is the only entry point to the composition (staging, normalization, duration, rendering, cleanup):

RENDER=${DROID_PLUGIN_ROOT}/scripts/render-showcase.sh

# Basic render
$RENDER --props "$PROPS" --output "${RUN_DIR}/demo.mp4" \
  "${RUN_DIR}/before.cast" "${RUN_DIR}/after.cast"

# Or with inline props (useful for simple cases)
$RENDER --props-inline '{"clips":[],"layout":"single","labels":[],"title":"Demo","subtitle":"Test","preset":"macos","keys":[],"effects":[]}' \
  --output "${RUN_DIR}/demo.mp4" "${RUN_DIR}/clip.mp4"

The script:

1. Accepts .cast, .mp4, .webm only; converts .cast to .mp4 at 1x with the selected fidelity profile
2. Stages clips as clip-<index> inside a directory it creates under ${REMOTION_DIR}/public/ for this render only
3. Resolves fidelity, width/height, speed; sets clipDuration to the longest clip (ffprobe)
4. Runs npx remotion render Showcase with profile-specific encode flags plus --pixel-format=yuv420p --color-space=bt709 (the color space is what keeps the file at limited-range yuv420p instead of yuvj420p)
5. Removes its own staged directory on exit and on failure. Cancel it with Ctrl-C or by signalling its process group; a signal sent to the script's PID alone takes effect only after the npx remotion child exits

Quick frame check (sanity-check layout before full render; same normalization and staging as a render):

$RENDER --props "$PROPS" --still 150 --output "${RUN_DIR}/check.png" "${RUN_DIR}/before.cast" "${RUN_DIR}/after.cast"
# frame 150 = 5.0s at 30fps; clips start at frame 120, after the title crossfade

Render time: Expect ~1-3 minutes for a 30-60s video at 1920x1080. Set worker timeouts accordingly (5 minutes is safe).

Step 4: Finalize

Check the result:

ffprobe -v quiet -print_format json -show_format -show_streams "${RUN_DIR}/demo.mp4"

Confirm:

• Resolution matches the resolved fidelity: 1920x1080 for compact/standard, 2560x1440 for inspect (the default for side-by-side), or the explicit width/height in props
• Duration matches 4s title + longest_clip / speed + 3.5s outro (the duration checkpoint formula)
• File size is manageable (under 5 MB for GitHub embeds, 25 MB hard limit)
• Pixel format is yuv420p with color_space=bt709 (universal playback)

The verify stage owns the decode and proof-frame checks; do not report the video as playable from metadata alone.

Outputs

Hand to the verify stage:

## Compose outputs
- video: /tmp/demo-pr-11621.mp4
- resolution: 1920x1080
- duration: 42s
- size: 3.2 MB
- preset: factory
- keystrokes: 3 events overlaid
- effects: 1 spotlight
- engine: remotion

Screenshot-only artifacts (proofs, QA)

Not every deliverable is a video. For proof and QA workflows, compose may just organize screenshots and snapshots. This is also where .png stills go — they are never passed to the render script as clips:

Annotated screenshot set

ffmpeg -y -i before.png -i after.png \
  -filter_complex "
    [0:v]scale=960:-1[left];
    [1:v]scale=960:-1[right];
    [left][right]hstack=inputs=2[out]" \
  -map "[out]" comparison.png

Markdown report with embedded evidence

For text-based deliverables, organize the evidence into a structured report rather than a video. The verify stage handles this.