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

> Learn how the Claude Video test suite synthesizes test videos with ffmpeg using helper functions in conftest.py to create key-frame-rich clips and static clips for deterministic testing.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-08-02

---

**The Claude-Video repository generates test videos programmatically using ffmpeg's lavfi "color" filter source, implemented through two helper functions in [`tests/conftest.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```python

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

```python

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

```python
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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/tests/conftest.py) | Defines ffmpeg helper functions (`build_cut_clip`, `build_static_clip`) and pytest fixtures |
| [`tests/test_fixtures.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_fixtures.py) | Smoke tests verifying generated clips are playable with correct duration |
| [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py) | Uses synthesized clips to validate watch-script detail-selection logic |
| [`tests/test_dedup.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/tests/conftest.py).

### How does the test suite handle ffmpeg execution failures?

The `_run()` helper in [`tests/conftest.py`](https://github.com/bradautomates/claude-video/blob/main/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.