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.

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.

.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.

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:

.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.

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

Preset quick reference

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

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

When to use effects

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.

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.

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.