Remotion Visual Debugging

You cannot natively view video files, but you CAN read rendered JPEG frames. This skill enables visual debugging of Remotion projects by extracting frame samples and analyzing them.

When to Use Visual Debugging

Use this skill when:

Layout issues: Verifying element positioning, spacing, alignment
Animation timing: Checking animation sequences, transitions, easing
Text rendering: Verifying font rendering, text overflow, truncation
Responsive design: Checking how content fits at different points
Color/styling: Verifying gradients, shadows, opacity
Scene transitions: Checking handoffs between scenes
Before delivery: Final verification before rendering full video

The Render Script

The skill bundles a universal Remotion frame extractor. Use the cross-platform wrapper which automatically sets up the project:

node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs [options]

The wrapper automatically copies render-stills.mjs to your project directory (if needed) and runs it. Works on Windows, macOS, and Linux.

Quick Reference

# List available compositions
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --list

# Extract 9 frames across entire video (default)
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs -n 9 --grid --labels

# Analyze specific animation range (frames 100-200, 12 samples)
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --from 100 --to 200 -n 12 --grid --labels

# Analyze by timestamp (5s to 10s)
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --from 5000 --to 10000 --ms -n 9 --grid --labels

# Specific frames only
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs -f 0,30,60,90,120 --grid --labels

Alias tip: Add to your shell config for shorter commands:

# Bash/Zsh (Linux/macOS)
alias remotion-debug="node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs"

# PowerShell (Windows)
function remotion-debug { node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs $args }

Output

Individual frames: out/stills/frame-XXXX.jpeg
Grid composite: out/stills/grid.jpg (when --grid used)

Visual Debugging Workflow

Step 1: Understand the Composition

node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --list

This shows available compositions with dimensions, duration, and FPS.

Step 2: Render Overview Grid

For initial overview, render 9-12 frames across the entire video:

node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs -n 9 --grid --labels

Step 3: Read and Analyze the Grid

Read the file: out/stills/grid.jpg

The grid image shows frames with labels (frame number + timestamp). Analyze:

Overall flow and pacing
Scene transitions
Layout consistency
Any obvious visual issues

Step 4: Deep Dive Problem Areas

If you spot issues in a specific time range, extract more frames from that area:

# If issue appears around frame 150, analyze frames 120-180 closely
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --from 120 --to 180 -n 12 --grid --labels

Step 5: Verify Fixes

After making code changes, re-render the affected range to verify the fix.

Script Options Reference

Frame Selection (mutually exclusive)

| Option | Description | Example | |--------|-------------|---------| | -f, --frames | Specific frame numbers | -f 0,30,60,90 | | -t, --timestamps | Specific timestamps (ms) | -t 0,1000,2000 | | -i, --interval | Every N milliseconds | -i 500 | | --from/--to -n | Uniform distribution in range | --from 0 --to 300 -n 9 | | --ms | Interpret from/to as milliseconds | --from 5000 --to 10000 --ms |

Grid Options

| Option | Description | Example | |--------|-------------|---------| | --grid, -g | Create grid composite | --grid (auto), --grid 3 (3 cols), --grid 3x2 | | --labels, -l | Add frame/timestamp labels | --labels | | --gap | Gap between images (px) | --gap 8 |

Output Options

| Option | Description | Example | |--------|-------------|---------| | -s, --scale | Scale factor (default 0.5) | -s 1 (full res) | | -q, --quality | JPEG quality 0-100 | -q 90 | | -o, --output | Output directory | -o ./debug-frames |

Project Options

| Option | Description | Example | |--------|-------------|---------| | -p, --project | Project directory | -p /path/to/project | | -c, --composition | Composition ID | -c MyScene | | -e, --entry | Entry point file | -e src/Video.tsx |

Common Debugging Scenarios

Animation Not Smooth

Extract many frames from the animation range to see individual steps:

node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --from 50 --to 80 -n 15 --grid --labels

Element Positioning Wrong

Render at full scale for pixel-accurate analysis:

node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs -f 100 -s 1 -q 95

Scene Transition Issue

Focus on the transition frames:

# If Scene 1 ends at frame 150, check 140-160
node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs --from 140 --to 160 -n 10 --grid --labels

Text Rendering/Font Issues

Render specific frames at full resolution:

node ~/.claude/skills/remotion-visual-debug/scripts/render-frames.mjs -f 30,60,90 -s 1 --grid

Dependencies

The script requires these packages (install in any Remotion project):

@remotion/renderer
@remotion/bundler
sharp

npm install @remotion/renderer @remotion/bundler sharp

Tips for Effective Visual Debugging

Start with overview - Always render a full-video grid first
Use labels - The --labels flag helps correlate frames with code
Iterate quickly - Bundle caching makes subsequent renders fast
Check boundaries - Scene transitions and animation start/end points
Verify at scale - Use -s 1 for pixel-accurate checks when needed
Compare before/after - Render same frames before and after fixes