# When Does the Uniform Sampler Fallback Activate in claude-video?

> Discover when the uniform sampler fallback activates in claude-video when scene detection fails. Ensure proper frame coverage for static or low-motion videos.

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

---

**The uniform sampler fallback activates whenever the scene detector produces fewer than eight distinct shots, ensuring static or low-motion videos still receive adequate frame coverage for analysis.**

The `claude-video` repository implements a dual-engine approach to frame extraction, prioritizing intelligent scene detection to capture visually distinct moments. When analyzing videos with minimal cuts—such as screen recordings or talking-head footage—the system automatically invokes a **uniform sampler fallback** to prevent gaps in coverage. Understanding the precise activation threshold and decision logic helps developers predict extraction behavior and debug processing pipelines.

## How Scene Detection Works in claude-video

The primary extraction engine relies on scene-cut detection to identify shot boundaries. This process runs through the `extract_scene_candidates` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), which analyzes the video for visual discontinuities and returns candidate keyframes representing distinct scenes.

This approach works well for narrative content with frequent cuts but risks returning sparse results for static content.

## The Fallback Threshold: SCENE_MIN_FRAMES

The decision to abandon scene-based extraction hinges on a hardcoded minimum threshold defined at the top of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py):

```python
SCENE_MIN_FRAMES = 8

```

This constant requires the scene detector to identify at least eight distinct shots before the scene engine is considered reliable. If the video contains fewer cuts than this threshold, the system assumes the scene detector failed to produce sufficient coverage and triggers the fallback mechanism.

## Decision Logic in extract_scene_or_uniform

The core decision logic resides in the `extract_scene_or_uniform` function. After gathering candidates via `extract_scene_candidates`, the function evaluates the count against the minimum threshold:

```python
if scene_count >= SCENE_MIN_FRAMES:
    # Use scene-based extraction

else:
    # Trigger uniform sampler fallback

    frames, meta = extract(...)

```

When `scene_count < SCENE_MIN_FRAMES`, the code calls the uniform sampling engine via `extract(...)`, which distributes frames evenly across the entire video duration rather than at scene boundaries. This guarantees the `target_frames` budget is met regardless of motion content.

## Identifying Fallback in Output Metadata

When the uniform sampler activates, the returned metadata dictionary explicitly flags the behavior. According to the implementation in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), the metadata includes:

```python
{
    "engine": "uniform",
    "fallback": True,
    # ... other metadata fields

}

```

This allows downstream processes in the `/watch` skill to detect when scene detection was insufficient and adjust processing accordingly.

## Practical Example: Extracting Frames with Fallback Handling

The following example demonstrates how the `/watch` skill calls the extraction function and inspects the fallback status:

```python
from skills.watch.scripts.frames import extract_scene_or_uniform
from pathlib import Path

video_path = "/path/to/video.mp4"
out_dir = Path("/tmp/frames")

frames, meta = extract_scene_or_uniform(
    video_path,
    out_dir,
    fps=2.0,
    target_frames=30,
    resolution=512,
    max_frames=30,
    start_seconds=None,
    end_seconds=None,
    dedup=True,
)

if meta.get("fallback"):
    print(f"Scene detection insufficient ({meta.get('scene_count', 0)} scenes). Using uniform sampling.")
else:
    print(f"Scene detection succeeded with {meta.get('scene_count')} scenes.")

```

This pattern ensures your application handles both high-motion and static content gracefully.

## Summary

- **The uniform sampler fallback activates when fewer than eight scene-change frames are detected** (`scene_count < SCENE_MIN_FRAMES`).
- The threshold is defined by the constant `SCENE_MIN_FRAMES = 8` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).
- The decision logic is implemented in the `extract_scene_or_uniform` function, which orchestrates both engines.
- When triggered, the fallback calls `extract(...)` for uniform sampling and sets `meta["fallback"]` to `True` and `meta["engine"]` to `"uniform"`.
- This safeguard ensures static, poorly-encoded, or short videos still provide usable frames for downstream transcript generation.

## Frequently Asked Questions

### When does the uniform sampler fallback activate in claude-video?

The fallback activates whenever the scene detector identifies fewer than eight distinct shot boundaries in the video. Specifically, when `scene_count < SCENE_MIN_FRAMES` (where `SCENE_MIN_FRAMES` equals 8), the system switches from scene-based extraction to uniform sampling to ensure adequate frame coverage.

### How can I detect if the uniform sampler was used instead of scene detection?

Inspect the metadata dictionary returned by `extract_scene_or_uniform`. If the uniform sampler was used as a fallback, the metadata will contain `"engine": "uniform"` and `"fallback": True`. The scene-based engine would return `"engine": "scene"` and `"fallback": False` or omit the fallback flag entirely.

### Why is the SCENE_MIN_FRAMES threshold set to 8?

The threshold of eight frames serves as a reliability guard. Videos with very few cuts—such as screen recordings or talking-head footage—would otherwise produce sparse frame sets, causing downstream transcript generation to miss large portions of content. Requiring eight distinct shots ensures the scene engine only operates when it can provide meaningful coverage distinct from uniform sampling.

### Can I modify the threshold that triggers the uniform sampler fallback?

The threshold is controlled by the `SCENE_MIN_FRAMES` constant defined at the top of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). While this value is hardcoded in the current implementation, developers can modify this constant in the source code to adjust the sensitivity of the fallback mechanism for their specific use cases.