# When Does Uniform Sampling Fallback Trigger Over Scene Detection?

> Learn when uniform sampling replaces scene detection. Claude Video uses uniform sampling for videos with fewer than 8 scene cuts to ensure frame extraction from static or low-motion content.

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

---

**Uniform sampling automatically replaces scene detection when a video produces fewer than 8 distinct scene cuts, ensuring usable frame extraction from static or low-motion content.**

The `bradautomates/claude-video` repository implements an intelligent frame extraction pipeline that switches between scene-based detection and uniform sampling based on content analysis. When visual changes are insufficient, the system triggers a **uniform sampling fallback** to guarantee meaningful frame coverage across the entire clip. This behavior is hardcoded in the extraction logic and requires no manual configuration.

## The 8-Frame Minimum Threshold

The fallback mechanism relies on a hardcoded constant defined in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). At **line 26**, the code sets `SCENE_MIN_FRAMES = 8`, establishing the minimum threshold for meaningful scene detection.

When processing a video, the system first attempts to identify scene changes using `extract_scene_candidates`. If the resulting frame count—including the mandatory first frame—falls below this threshold, the algorithm classifies the content as effectively static. This condition captures videos with zero scene changes (such as solid-color clips) or minimal motion that fails to generate distinct visual boundaries.

## How the Fallback Logic Works

The decision logic resides in the `extract_scene_or_uniform` function within [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 521–543). The implementation follows this sequence:

1. Extract candidate frames using scene detection
2. Count the candidates (`scene_count = len(scene_frames)`)
3. Compare against `SCENE_MIN_FRAMES`
4. Execute the appropriate extraction path

```python
scene_frames = extract_scene_candidates(...)
scene_count = len(scene_frames)

# ---- Uniform-fallback guard ----

if scene_count >= SCENE_MIN_FRAMES:
    # Normal scene engine path

    ...
else:
    # Uniform fallback: sample across the whole range

    frames = extract(...)
    return frames, {
        "engine": "uniform",
        "candidate_count": scene_count,
        "fallback": True,
    }

```

When the fallback activates, the function returns metadata with `"engine": "uniform"` and `"fallback": True`, using the requested `fps` and `target_frames` parameters to generate evenly-spaced samples across the entire video duration.

## Practical Code Examples

### Detecting When Fallback Occurs

You can identify fallback activation by inspecting the metadata returned from `extract_scene_or_uniform`. Static content triggers the uniform engine automatically:

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

video = "static_clip.mp4"          # A clip with no scene changes

out_dir = Path("/tmp/frames")
fps = 1.0
target = 30                       # Desired number of frames

frames_out, meta = frames.extract_scene_or_uniform(
    video_path=video,
    out_dir=out_dir,
    fps=fps,
    target_frames=target,
    resolution=512,
    max_frames=None,
)

print(meta)

# => {

#      "engine": "uniform",

#      "candidate_count": 0,

#      "fallback": True,

#      "selected_count": 30,

#    }

```

The `meta["fallback"]` flag confirms that uniform sampling was used because the scene engine located insufficient cuts.

### Normal Scene Detection Operation

Content with sufficient visual changes bypasses the fallback entirely:

```python

# A clip with many cuts (e.g., a fast-editing music video)

video = "cut_heavy_clip.mp4"

frames_out, meta = frames.extract_scene_or_uniform(
    video_path=video,
    out_dir=out_dir,
    fps=1.0,
    target_frames=30,
    resolution=512,
    max_frames=30,
)

print(meta["engine"])   # → "scene"

print(meta["fallback"]) # → False

```

Because `scene_count >= 8`, the scene engine executes without intervention.

## Key Source Files and Testing

The fallback implementation spans the following files:

- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)** — Contains `extract_scene_or_uniform`, `extract_scene_candidates`, and the `SCENE_MIN_FRAMES` constant (line 26)
- **[`tests/test_frames.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_frames.py)** — Unit tests verifying both scene engine and uniform fallback behavior
- **[`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py)** — Integration tests confirming the watch command reports correct engine and fallback status

## Summary

- **Eight frames minimum**: The `SCENE_MIN_FRAMES` constant (set to 8) defines the threshold below which uniform sampling replaces scene detection
- **Automatic activation**: No CLI flag exists to override the fallback; the system decides based on content analysis
- **Metadata transparency**: The return dictionary includes `"engine": "uniform"` and `"fallback": True` when the fallback triggers
- **Even distribution**: Fallback frames use the requested `fps` and `target_frames` to sample uniformly across the entire clip duration

## Frequently Asked Questions

### What is the minimum number of scene cuts required to avoid uniform sampling fallback?

You need at least **8 distinct scene cuts** (including the first frame) to prevent the fallback from triggering. This threshold is defined by the `SCENE_MIN_FRAMES` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) at line 26.

### Can I disable the uniform sampling fallback and force scene detection?

No. According to the source code in `bradautomates/claude-video`, the fallback is **automatic** and unconditional. There is no configuration option or CLI flag to force scene detection when the shot count falls below the threshold.

### How can I verify which extraction engine was used?

Inspect the metadata dictionary returned by `extract_scene_or_uniform`. The `"engine"` key will show either `"scene"` or `"uniform"`, while the `"fallback"` boolean indicates whether the uniform sampling fallback was activated due to insufficient scene cuts.

### Does the fallback affect the number of frames returned?

No. The uniform sampling fallback respects your requested `target_frames` and `fps` parameters. Instead of returning frames at scene boundaries, it returns the same quantity of frames distributed evenly across the entire video duration.