/video-generation

name: video-generation
description: How to generate repo-committed video content (README hero videos, case-study clips, landing demos) with Remotion. Covers project layout, fonts and colors that match the brand, audio sourcing, rendering in a worker container, the full-range yuvj420p gotcha, CI exclusions, and the "honest read" pacing principle. Use whenever you are asked to create a video from a Remotion project, animate a wireframe, or re-render an existing Remotion project. For a design-led one-off showreel use open-prompt-showreel instead.
metadata:
  type: procedure

Video generation (Remotion)

Remotion (React + TypeScript) is the stack for videos that live in a repo: README heroes, landing demos, case-study clips, thread dramatizations. `assets/video-source/` in `desplega-ai/agent-swarm` is the reference implementation; read it before starting a new project.

Golden rules

1. **Remotion for repo-committed video.** `npx remotion studio` for previews, `remotion render` for mp4s. For a one-off design-led cut with no repo, use `open-prompt-showreel` instead. 2. **Ask for audio, don't pick it.** Music is a brand call. A person on the team chooses the track (CC0 or CC BY 4.0, for example from https://freesound.org). Never grab something yourself; ask. There is no default bed. 3. **Attribute in the video folder's README.** Artist name, source URL, license. Not in the repo root README; in the video project's own README. 4. **Design tokens mirror the product.** Pull colors and fonts from the product's own `globals.css` (Agent Swarm: Space Grotesk + Space Mono, zinc dark palette, amber `#f2a93b` accent). Do not invent new ones. 5. **Honest read pacing.** The first draft always over-packs the opening and under-weights the payoff. Compress setup scenes, expand the one that carries the message. See "Pacing" below. 6. **One Remotion project, many compositions.** Do not spin up a new repo per video. Register additional `<Composition>` entries in `src/Root.tsx` and add a `build:<slug>` script.

Project layout

<project>/
  package.json            # remotion + @remotion/cli + @remotion/google-fonts + react 18
  remotion.config.ts
  tsconfig.json           # isolated: exclude from the root tsconfig (see CI below)
  README.md               # render commands + audio attribution
  src/
    index.ts              # registerRoot(Root)
    Root.tsx              # <Composition> per video
    fonts.ts              # loadFont() for Space Grotesk + Space Mono at module scope
    theme.ts              # brand tokens (bg/fg/accent/sans/mono)
    compositions/         # one per video: stitches scenes + audio
    scenes/<video-slug>/  # per-scene components, one folder per composition
  public/
    audio/bed.mp3         # music bed, referenced via staticFile("audio/bed.mp3")
  out/                    # rendered mp4s (gitignored)

Bootstrapping a new video project

Ran in a worker container (Remotion 4.0.532, 23 s install):

mkdir -p assets/video-source && cd assets/video-source
npm init -y
npm install remotion @remotion/cli @remotion/google-fonts react@^18.3.1 react-dom@^18.3.1
npm install -D @types/react typescript
npx remotion studio   # scaffolds config + opens preview

`npx remotion studio` opens an interactive preview and was not run for this playbook.

Rendering in a worker container

The worker image already ships Chromium (`/opt/playwright/chromium`) and its system libraries, so no apt install is needed. Point Remotion at it instead of letting it download its own browser:

npx remotion render src/index.ts <CompositionId> out/<name>.mp4 \
  --browser-executable=/opt/playwright/chromium --color-space=bt709

A 30-frame 1280x720 test composition rendered in 14 s this way.

**Color-range gotcha.** Without `--color-space=bt709`, `remotion render` writes `yuvj420p(pc, bt470bg)`: full range, not the limited-range `yuv420p` that social uploaders expect. With the flag it writes `yuv420p(tv, bt709)`. Check with `ffmpeg -hide_banner -i out.mp4 2>&1 | grep Stream`. If a clip is already rendered, re-encode it with the template's `x-reencode.sh`.

For a bare Debian/Ubuntu container that is not a worker image, Chromium needs system libraries and root. **Unverified, not run for this playbook:**

sudo apt-get install -y ffmpeg libnspr4 libnss3 libatk1.0-0 libatk-bridge2.0-0 \
  libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
  libxrandr2 libgbm1 libpango-1.0-0 libcairo2 libasound2t64 libatspi2.0-0

Fonts

Load once at module scope in `src/fonts.ts` and import from `src/Root.tsx`:

import { loadFont as loadSpaceGrotesk } from "@remotion/google-fonts/SpaceGrotesk";
import { loadFont as loadSpaceMono } from "@remotion/google-fonts/SpaceMono";

loadSpaceGrotesk("normal", { weights: ["400", "500", "600", "700"], subsets: ["latin"] });
loadSpaceMono("normal", { weights: ["400", "700"], subsets: ["latin"] });

Theme tokens (dark palette, amber accent)

export const theme = {
  bg: "#09090b",
  card: "#18181b",
  fg: "#fafafa",
  muted: "#a1a1aa",
  mutedDim: "#52525b",
  border: "rgba(255,255,255,0.10)",
  borderStrong: "rgba(255,255,255,0.18)",
  accent: "#f2a93b",      // amber: brand primary in dark mode
  accentDim: "#7a4d12",
  accentFg: "#1a1409",
  success: "#4ade80",
  danger: "#f87171",
  sans: "'Space Grotesk', system-ui, -apple-system, sans-serif",
  mono: "'Space Mono', ui-monospace, 'SF Mono', Menlo, monospace",
};

Multiple compositions

Register each video as its own `<Composition>` in `src/Root.tsx`. `durationInFrames` is at 30 fps unless you raise the fps:

<Composition id="DailyEvolution" component={DailyEvolution}
  durationInFrames={900} fps={30} width={1920} height={1080} />
<Composition id="SlackToPR" component={SlackToPR}
  durationInFrames={1350} fps={30} width={1920} height={1080} />

Add a `build:<slug>` script per composition in `package.json`:

"build:daily-evolution"