compose

What this skill does

# 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, .png)
- **driver**: tuistory | true-input | agent-browser
- **layout**: `single` | `side-by-side`
- **labels**: text for each clip (e.g., "BEFORE (dev)", "AFTER (PR)")
- **speed**: multiplier (default 3x)
- **fidelity**: `auto` | `compact` | `standard` | `inspect` (optional; auto => 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, 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

```bash
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` auto-selects `inspect` for side-by-side and `standard` for single-clip layouts when `fidelity` is omitted or set to `auto`.

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

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

Set the `speed` prop to hit the target: if the raw recording is 3 minutes and the target is 60s, use `"speed": 3`. 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.

**Keystroke timing adjustment**: If a keystroke list was emitted during capture, its timestamps are in raw recording time. When you apply a speed multiplier, you **must** divide every timestamp by the speed factor before passing it to the Remotion props. A keystroke at raw `t=6.0s` in a 3x video should appear at `t=2.0s`.

### Non-.cast clips

`.mp4`, `.webm`, and `.png` clips are passed through to Remotion unchanged except for staging into `public/`. Re-encode non-`.cast` clips manually only if their pixel format or dimensions are invalid.

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