🚜 sql-demo-maker

Generate annotated demo videos for DuckDB extensions from YAML scripts.

Built by Query.Farm.

How It Works

1. Write a YAML script describing the demo (SQL queries, annotations, visualizations)
2. Run sql-demo-maker prepare to execute queries against DuckDB and produce a JSON render plan
3. Render with Remotion to produce a polished MP4 video

YAML → DuckDB execution → JSON → Remotion (React) → MP4

Quick Start

# Install Python dependencies
uv venv && uv pip install -e .

# Install Remotion dependencies
cd remotion && npm install

# Generate render plan
sql-demo-maker prepare demos/lindel_extension.yaml -o remotion/src/data/renderPlan.json

# Preview in browser
cd remotion && npx remotion studio

# Render final video
npx remotion render src/index.ts LindelDemo --output ../output.mp4 --crf 18

Project Structure

sql-demo-maker/
├── demos/                      # YAML demo scripts
│   ├── lindel_extension.yaml   # Lindel extension demo
│   └── lindel_script.md        # Video script/storyboard
├── remotion/                   # Video rendering (React/TypeScript)
│   ├── src/
│   │   ├── LindelDemo.tsx      # Main video composition
│   │   ├── theme.ts            # Centralized color theme
│   │   ├── highlight.ts        # SQL syntax highlighting
│   │   ├── mapPath.ts          # Natural Earth SVG map data
│   │   └── components/         # Reusable video components
│   │       ├── Terminal.tsx     # DuckDB CLI terminal
│   │       ├── CurveGrid.tsx   # Animated space-filling curves
│   │       ├── HighlightGrid.tsx # Grid with cell highlighting
│   │       ├── CityScatter.tsx # GPS city map visualization
│   │       ├── RowGroupDiagram.tsx # Parquet row group diagram
│   │       ├── BrandBar.tsx    # Persistent header branding
│   │       ├── SplitLayout.tsx # Two-panel layout
│   │       ├── TitleCard.tsx   # Title/closing cards
│   │       ├── Callout.tsx     # Info/warning/success boxes
│   │       └── StepNote.tsx    # Floating note badges
│   └── public/
│       └── qr-lindel.png      # QR code for extension page
├── sql_demo_maker/             # Python CLI
│   ├── cli.py                  # Click CLI (prepare command)
│   ├── schema.py               # Pydantic YAML models
│   └── executor.py             # DuckDB query execution
├── narration.txt               # Voice-over script
└── pyproject.toml

Theming

Colors are centralized in remotion/src/theme.ts. Current theme: Modern Farmhouse.

export const T = {
  bg: "#12150f",       // near-black with green tint
  surface: "#1e2419",  // dark sage
  text: "#f5f0e8",     // eggshell
  green: "#66bb6a",    // meadow
  gold: "#ffca28",     // honey
  orange: "#ffa726",   // apricot
  red: "#ef5350",      // poppy
  blue: "#42a5f5",     // clear sky
  mauve: "#ab47bc",    // lavender field
  teal: "#80cbc4",     // pond
  // ...
};

Change the theme by editing this one file — all components reference it.

Audio

Voice-over is generated with ElevenLabs and synced per-scene using FFmpeg:

# Generate per-scene audio segments, time-fit to scene durations, concatenate
# Then combine with video:
ffmpeg -i video.mp4 -i narration_synced.wav \
  -c:v libx264 -crf 18 -pix_fmt yuv420p \
  -c:a aac -b:a 192k \
  -movflags +faststart \
  output.mp4

YAML Step Types

Type	Purpose
title	Full-screen title card
sql	Execute SQL, show output
callout	Info/warning/success overlay
clear	Clear terminal
reveal	Progressive sub-steps
visualization	Animated grids, charts
split_sql	SQL + visualization side by side
section_header	Non-modal text overlay

Dependencies

Python: duckdb, pyyaml, pydantic, click

Node: remotion, react, typescript

System: FFmpeg, SF Mono font (from Terminal.app)

License

MIT