# What Causes Uniform Sampling Fallback in Claude-Video When Scene Detection Is Active?

> Discover why Claude-Video uses uniform sampling fallback when scene detection is active. Learn how it ensures reliable frame extraction for static videos with fewer than 8 distinct shots.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-04

---

**When the scene detection engine finds fewer than 8 distinct shots, Claude-Video automatically falls back to uniform sampling to ensure reliable frame extraction for static videos.**

The `claude-video` project, developed by `bradautomates`, implements an intelligent frame extraction system that balances visual quality with processing efficiency. When users invoke the `/watch` skill with scene detection enabled, the system dynamically switches to uniform sampling if the video content lacks sufficient visual changes—such as screen recordings or single-camera interviews—to justify the computational cost of full scene analysis.

## How the Scene Detection Fallback Works

The fallback logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). At line 26, the system defines a minimum threshold for meaningful scene diversity:

```python
SCENE_MIN_FRAMES = 8  # Line 26

```

This constant establishes that any video producing fewer than 8 distinct shots is classified as **static** and routed to the simpler uniform sampling path.

### Step-by-Step Decision Flow

The `extract_scene_or_uniform` function orchestrates the evaluation:

1. **Scene candidate extraction** — Lines 33-41 call `extract_scene_candidates()`, which collects the first frame plus any frames where `ffmpeg` detects scene changes above the configured threshold.

2. **Shot count validation** — Line 42 calculates `scene_count = len(scene_frames)`.

3. **Fallback trigger** — Lines 42-53 implement the critical check:
   - If `scene_count >= SCENE_MIN_FRAMES`: Use scene engine results
   - Else: Discard scene results and execute uniform fallback

4. **Uniform sampling execution** — Lines 55-73 invoke `extract()` with fixed FPS parameters, populating metadata with `"fallback": True` and `"engine": "uniform"`.

## Why Static Videos Trigger the Fallback

The design optimizes for **budget-aware processing** and **consistent output quality**:

- **Computational efficiency**: Scene detection requires a complete video decode and frame-by-frame analysis. For visually uniform content, this expensive operation yields minimal value.

- **Guaranteed coverage**: Uniform sampling ensures every clip produces a predictable number of frames regardless of content characteristics, preventing downstream failures in transcript generation or visual analysis pipelines that expect minimum frame availability.

## Detecting When Fallback Occurs in Code

The function returns metadata that explicitly signals fallback status:

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

video_path = "example.mp4"
out_dir = Path("out")
fps, _ = auto_fps(30)          # target 30-second clip

frames, meta = extract_scene_or_uniform(
    video_path,
    out_dir,
    fps=fps,
    target_frames=20,
)

print(meta["engine"])          # "scene" or "uniform"

print(meta["fallback"])        # True only when uniform fallback occurred

```

For static content like screen recordings or single-shot videos, `meta["engine"]` returns `"uniform"` and `meta["fallback"]` equals `True`.

## Related Fallback: Keyframe Engine

A parallel mechanism exists for the keyframe extraction engine in the same file. Using `KEYFRAME_MIN = 4` (line 36), the system switches to uniform sampling when `len(candidates) < 4` (lines 36-68). This mirrors the scene engine's conservative approach, favoring reliable output over idealized extraction methods when source material lacks structural diversity.

## Summary

- **Threshold**: The `SCENE_MIN_FRAMES = 8` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) defines the minimum shot count for scene detection viability.

- **Trigger condition**: Fewer than 8 distinct scene-change frames classifies a video as static.

- **Fallback behavior**: Automatic switch to uniform sampling with `"fallback": True` metadata annotation.

- **Design rationale**: Eliminate wasteful computation on uniform content while ensuring consistent frame output across all video types.

## Frequently Asked Questions

### How can I force scene detection even on static videos?

The current implementation in `claude-video` does not expose a parameter to override the `SCENE_MIN_FRAMES` threshold. You would need to modify line 26 of [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) locally, though this risks inefficient processing on genuinely static content.

### Does fallback affect frame quality or downstream analysis?

Uniform sampling produces regularly spaced frames rather than content-representative keyframes. For truly static videos, this difference is negligible. The system preserves `target_frames` count in both paths, so downstream components receive equivalent frame quantities.

### Where does fallback metadata propagate in the application?

The `meta` dictionary returned by `extract_scene_or_uniform` flows through [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which reports fallback status to the user-facing `/watch` skill interface defined in [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md).

### Is there a way to preview whether a video will trigger fallback?

No pre-flight analysis exists in the current codebase. Testing with `extract_scene_candidates()` directly on a sample clip and checking if `len(results) >= 8` provides equivalent insight before full processing.