How to Synthesize Test Videos with ffmpeg in the Claude-Video Test Suite

The Claude-Video repository generates test videos programmatically using ffmpeg's lavfi "color" filter source, implemented through two helper functions in tests/conftest.py that create key-frame-rich cut clips and single-color static clips for deterministic testing.

The Claude-Video test suite avoids external media dependencies by synthesizing test videos on-the-fly with ffmpeg. This approach ensures fast, reproducible tests that run anywhere ffmpeg is installed. The synthesis logic lives in tests/conftest.py, where two core functions—build_cut_clip() and build_static_clip()—generate precisely controlled video content for different testing scenarios.

Core ffmpeg Video Synthesis Functions

build_cut_clip(): Multi-Segment Test Videos

The build_cut_clip() function creates short clips containing sequential solid-color segments separated by hard cuts. This design produces abundant key-frames and scene changes for testing key-frame extraction and scene-selection algorithms.

The implementation builds multiple lavfi inputs—one per color segment—and concatenates them:

# Simplified command structure from tests/conftest.py

ffmpeg -f lavfi -t <segment_duration> -i "color=c=red:s=320x240:r=10" \
       -f lavfi -t <segment_duration> -i "color=c=green:s=320x240:r=10" \
       ... \
       -filter_complex "[0:v][1:v]...concat=n=14:v=1:a=0[out]" \
       -c:v libx264 \
       -force_key_frames "expr:gte(t,n_forced*<segment_duration>)" \
       output.mp4

Key parameters:

• color=c=<color>:s=<size>:r=<fps> — Generates uniform color frames at specified resolution and frame rate
• concat=n=<n>:v=1:a=0 — Concatenates n video streams without audio
• -force_key_frames "expr:gte(t,n_forced*<seg>)" — Forces a key-frame at every segment boundary for deterministic scene detection

build_static_clip(): Single-Color Static Videos

The build_static_clip() function produces a single-color clip with minimal key-frames for testing duplicate-frame deduplication:

# Command structure as implemented in tests/conftest.py

ffmpeg -f lavfi -t <duration> -i "color=c=blue:s=320x240:r=10" \
       -c:v libx264 \
       -g 600 \
       output.mp4

The -g 600 parameter sets a large GOP (Group of Pictures), yielding only one key-frame across the entire clip. This allows deduplication tests to verify that identical frames are correctly collapsed.

Pytest Fixture Integration

Both functions are exposed through pytest fixtures that cache results per test session:

Fixture	Function	Purpose
cut_clip	build_cut_clip()	14-segment color clip for scene/key-frame tests
static_clip	build_static_clip()	3-second blue clip for deduplication tests

The fixtures delegate execution to an internal _run() helper that invokes subprocess.run() and raises explicit errors on ffmpeg failure.

Practical Usage Examples

Generate a multi-segment cut clip programmatically:

from pathlib import Path
from tests.conftest import build_cut_clip

output_path = Path("tmp/cuts.mp4")
build_cut_clip(output_path)  # → 14 colored segments, key-frame at each cut

Create a static clip for deduplication testing:

from pathlib import Path
from tests.conftest import build_static_clip

output_path = Path("tmp/static.mp4")
build_static_clip(output_path)  # → 3s solid blue, single key-frame

Key Implementation Files

File	Role
tests/conftest.py	Defines ffmpeg helper functions (build_cut_clip, build_static_clip) and pytest fixtures
tests/test_fixtures.py	Smoke tests verifying generated clips are playable with correct duration
tests/test_watch.py	Uses synthesized clips to validate watch-script detail-selection logic
tests/test_dedup.py	Tests duplicate-frame detection using static clips

Summary

• ffmpeg lavfi color source eliminates external media dependencies by generating uniform color video streams programmatically
• build_cut_clip() concatenates multiple color segments with forced key-frames for scene-change testing
• build_static_clip() creates minimal-key-frame content for deduplication verification
• Pytest session-scoped fixtures ensure efficient, cached video generation across the test suite
• Deterministic, reproducible testing works on any machine with ffmpeg installed

Frequently Asked Questions

What ffmpeg filter generates the solid-color video sources?

The lavfi color filter creates uniform color streams. The filter string color=c=<color>:s=<size>:r=<fps> specifies color name, resolution, and frame rate. According to the Claude-Video source code, the test suite uses 320×240 resolution at 10 fps with colors like red, green, and blue.

Why does build_cut_clip() force key-frames at segment boundaries?

The -force_key_frames "expr:gte(t,n_forced*<segment_duration>)" parameter guarantees a key-frame at every color transition. This ensures deterministic scene-change detection for key-frame and scene-selection engine tests, as implemented in tests/conftest.py.

How does the test suite handle ffmpeg execution failures?

The _run() helper in tests/conftest.py executes ffmpeg via subprocess.run() with check=True. Non-zero exit statuses raise a clear exception with command output, failing fast and surfacing synthesis errors immediately.

Can these synthetic clips replace real video content for all testing scenarios?

The synthetic clips cover key-frame extraction, scene detection, and duplicate-frame deduplication testing. They deliberately avoid encoding complexity, motion, or audio. Tests requiring perceptual analysis, codec-specific behavior, or temporal motion patterns would need supplemental real-world media.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}