# What Triggers the Uniform Fallback in Claude-Video Instead of Scene-Aware Frame Selection

> Discover why Claude-Video uses uniform fallback instead of scene-aware frame selection. Learn about the ffmpeg scene and keyframe detection triggers that cause this behavior.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: internals
- Published: 2026-07-09

---

**The uniform fallback triggers when ffmpeg detects fewer than eight scene changes (`SCENE_MIN_FRAMES`) or fewer than four keyframes (`KEYFRAME_MIN`), causing Claude-Video to abandon content-aware analysis in favor of evenly distributed frame sampling.**

Claude-Video, the open-source video processing framework maintained by bradautomates, automatically selects between intelligent scene detection and uniform frame sampling based on visual content density. This fallback mechanism ensures reliable frame extraction even for static screen recordings or low-motion clips where scene-aware algorithms would return insufficient results.

## Scene-Aware vs. Uniform Frame Selection Strategies

Claude-Video implements two primary frame extraction engines in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The **scene-aware engine** (`engine: "scene"`) uses ffmpeg's scene-change filter to identify distinct visual cuts, while the **uniform engine** (`engine: "uniform"`) samples frames at regular intervals regardless of content.

According to the source code, the system evaluates content using two specific thresholds defined as module constants:

- **`SCENE_MIN_FRAMES = 8`** (line 26) – Minimum scene cuts required to use scene-aware selection
- **`KEYFRAME_MIN = 4`** (line 29) – Minimum I-frames required for keyframe-based extraction

When video content falls below either threshold, the corresponding engine triggers the uniform fallback to guarantee a usable frame set.

## How Scene Detection Triggers the Fallback

### The SCENE_MIN_FRAMES Threshold

In [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the `extract_scene_or_uniform` function governs the scene-aware pipeline. After running ffmpeg's scene-change detection across the full video range, the code counts detected frames (`scene_count`) and compares against the threshold at line 554.

If `scene_count >= SCENE_MIN_FRAMES` (≥ 8 scenes), the function proceeds with deduplication and even sampling. However, when `scene_count < SCENE_MIN_FRAMES`, execution jumps to the uniform fallback block starting at line 554, which calls the simple `extract` function and marks metadata with `fallback: True`.

```python
if scene_count >= SCENE_MIN_FRAMES:
    deduped, n_dropped = dedupe_perceptual(scene_frames) if dedup else (scene_frames, 0)
    cap = len(deduped) if max_frames is None else max_frames
    selected = _even_sample(deduped, cap)
    return selected, {
        "engine": "scene",
        "candidate_count": scene_count,
        "deduped_count": n_dropped,
        "selected_count": len(selected),
        "fallback": False,
    }

```

When the condition fails, the uniform fallback executes:

```python
fallback_cap = target_frames if max_frames is None else min(max_frames, target_frames)
frames = extract(
    video_path, out_dir, fps=fps, resolution=resolution,
    max_frames=fallback_cap, start_seconds=start_seconds, end_seconds=end_seconds,
)
...
return frames, {
    "engine": "uniform",
    "candidate_count": scene_count,
    "deduped_count": n_dropped,
    "selected_count": len(frames),
    "fallback": True,
}

```

## Keyframe Engine Fallback Logic

### The KEYFRAME_MIN Threshold

The `extract_keyframes` function implements similar safeguards. After extracting I-frame candidates, the code checks availability at lines 636-637. If `len(candidates) < KEYFRAME_MIN` (< 4 keyframes), the engine abandons keyframe selection and falls back to uniform sampling over the same time range (lines 640-668).

```python
if len(candidates) < KEYFRAME_MIN:
    # uniform fallback over the same range

    frames_out = extract(...)
    ...
    return frames_out, {
        "engine": "uniform",
        "candidate_count": len(candidates),
        "deduped_count": n_dropped,
        "selected_count": len(frames_out),
        "fallback": True,
    }

```

This ensures that videos with sparse keyframe metadata—common in screen recordings or compressed static content—still return a representative frame set rather than empty results.

## Why Static Videos Force the Uniform Fallback

The fallback mechanism serves a critical reliability function. Scene-aware detection relies on measurable visual differences between frames, calculated using ffmpeg's scene-change filter. When processing static screen recordings, presentation slides, or low-motion security footage, the difference metric falls below detection thresholds, yielding fewer than eight valid scene cuts.

By switching to uniform sampling at fixed temporal intervals, Claude-Video guarantees that the `skills/watch` pipeline always returns the requested number of frames regardless of visual stagnation. The metadata flag `fallback: True` allows downstream processes in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) to report when this substitution occurs, maintaining transparency about extraction methodology.

## Summary

- **Scene-aware fallback** triggers when fewer than 8 scene cuts (`SCENE_MIN_FRAMES`) are detected in `extract_scene_or_uniform` at line 554 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).
- **Keyframe fallback** triggers when fewer than 4 I-frames (`KEYFRAME_MIN`) are found in `extract_keyframes` at lines 636-637.
- Both conditions route execution to the uniform `extract` function, which samples frames at regular intervals across the video duration.
- The fallback mechanism ensures Claude-Video handles static content, short clips, and screen recordings without failing or returning empty frame sets.

## Frequently Asked Questions

### What is the minimum number of scenes required to avoid the uniform fallback?

Claude-Video requires **eight distinct scene cuts** (`SCENE_MIN_FRAMES = 8`) to maintain scene-aware frame selection. If ffmpeg's scene-change filter detects seven or fewer transitions, the system automatically switches to uniform sampling.

### Does the uniform fallback apply to keyframe extraction as well?

Yes. The keyframe engine (`extract_keyframes`) implements an independent threshold of **four I-frames** (`KEYFRAME_MIN = 4`). When videos contain fewer than four keyframes—which commonly occurs in static screen recordings—the engine falls back to uniform sampling over the same temporal range.

### Where is the fallback logic implemented in the Claude-Video codebase?

The core fallback logic resides in **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**. Specifically, the scene-aware check appears at lines 542-572, while the keyframe fallback spans lines 636-668. The orchestration layer in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) reports the fallback status to users.

### How can I detect if uniform fallback was used for my video?

Check the returned metadata dictionary from the extraction functions. When the uniform fallback activates, the metadata contains `"engine": "uniform"` and `"fallback": True`. The scene-aware path returns `"engine": "scene"` and `"fallback": False`.