# How Claude-Video Capped Modes Process Long Videos vs. Token-Burner Mode

> Discover how Claude-Video capped modes efficiently sample long videos versus token-burner mode's detailed scene preservation. Optimize your video processing.

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

---

**Claude-Video capped modes enforce hard frame limits that evenly sample across video duration, while token-burner mode disables caps entirely to preserve every detected scene change at higher token cost.**

The `claude-video` repository provides four **detail modes** that control how frame extraction balances completeness against token consumption. For videos exceeding 10 minutes, this choice fundamentally alters what visual information reaches the language model.

## How Frame Caps Work in Claude-Video

The system budgets frames through a two-layer approach: **FPS-based sampling** creates an initial candidate pool, then a **mode-specific cap** thins that pool for efficiency.

In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `frame_cap` function maps detail modes to absolute limits:

```python

# skills/watch/scripts/config.py (lines 65-71)

def frame_cap(detail_mode: str) -> Optional[int]:
    caps = {
        "efficient": 50,
        "balanced": 100,
        "thorough": 200,
        "token-burner": None,  # Uncapped

    }
    return caps.get(detail_mode)

```

This cap propagates through the extraction pipeline in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 71-80), where `budget_cap` becomes the `max_frames` parameter passed to extraction engines.

## Capped Modes: Efficient and Balanced

### Efficient Mode (50-Frame Cap)

The **most aggressive** capped mode uses keyframe-only extraction. When processing long videos:

- `extract_keyframes` detects cut points across the entire duration
- If cuts exceed 50, the system keeps the **first 50 keyframes** plus even-sampled frames from start/end
- Result: extremely sparse representation for 30+ minute content

```bash

# CLI usage: 50-frame maximum regardless of video length

python3 skills/watch/scripts/watch.py \
  "https://youtu.be/long-video" --detail efficient

```

### Balanced Mode (100-Frame Cap)

The **moderate** capped mode employs scene-aware sampling:

1. `extract_scene_or_uniform` runs scene-change detection on the full video
2. The candidate list is **deduplicated** then **_even_sampled** to 100 frames
3. For long videos, the warning *"sparse scan"* appears in output

The sampling logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 5110-5148) illustrates this:

```python

# Pseudocode from extract_scene_or_uniform

candidates = extract_scene_candidates(video, fps)
candidates = dedupe_nearby_frames(candidates)

if max_frames is not None:
    # Capped mode: force even distribution

    selected = _even_sample(candidates, max_frames)
else:
    # Token-burner: keep everything

    selected = candidates

```

The `_even_sample` helper (lines 3989-3999) mathematically spreads selections:

```python
def _even_sample(frames: list, n: int) -> list:
    """Return n frames evenly distributed across the input list."""
    if len(frames) <= n:
        return frames
    step = (len(frames) - 1) / (n - 1)
    indices = [int(round(i * step)) for i in range(n)]
    return [frames[i] for i in indices]

```

For a 100-minute video with 800 scene candidates, balanced mode returns frames at roughly 1-minute intervals—adequate for structure, likely missing brief events.

## Token-Burner Mode: Uncapped Extraction

**Token-burner mode** disables the frame cap entirely by passing `max_frames=None`. This produces fundamentally different behavior:

| Aspect | Capped Modes | Token-Burner |
|--------|-------------|--------------|
| `max_frames` value | `50`, `100`, or `200` | `None` |
| Sampling after detection | Even-spread thinning | None—keep all candidates |
| Frame count on long video | Fixed cap | Scenes × duration |
| Token cost | Predictable, bounded | Unbounded, potentially 10×+ higher |

The same extraction function branches based on this parameter:

```python

# Direct Python API call for uncapped extraction

from skills.watch.scripts.frames import extract_scene_or_uniform

frames, meta = extract_scene_or_uniform(
    video_path="/path/to/two-hour-documentary.mp4",
    out_dir="/tmp/frames",
    fps=2.0,                # Respects 2 fps ceiling from auto_fps

    target_frames=100,      # Ignored when max_frames=None

    max_frames=None,        # Disables cap—token-burner behavior

)

# meta["selected_count"] equals total scenes detected, not a fixed number

```

## FPS Auto-Selection and Long Video Handling

Before caps apply, [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 55-60) sets extraction density via `auto_fps`/`auto_fps_focus`:

```python

# Automatic FPS ceiling for long videos

fps = min(calculated_fps, 2.0)  # Never exceed 2 fps regardless of mode

```

This **2 fps ceiling** ensures:
- Capped modes receive manageable candidate pools (duration × 2 maximum)
- Token-burner mode still captures genuine scene changes without drowning in near-duplicate frames

## Practical Comparison: 30-Minute Interview Video

| Detail Mode | Approximate Frames | Coverage Pattern | Use Case |
|-------------|-------------------|------------------|----------|
| `efficient` | ~50 | Keyframe cuts only | Quick gist, speaker tracking |
| `balanced` | 100 | Even spread across duration | Topic navigation, structure |
| `token-burner` | 400-800+ | Every scene change | Detailed analysis, visual Q&A |

The documentation in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (lines 90-106) confirms this trade-off, noting capped modes "thin out after ~10 min" while token-burner "keeps *every* scene-change frame."

## Performance and Cost Implications

Capped modes provide **predictable costs**: a 2-hour documentary costs approximately the same tokens as a 15-minute tutorial in balanced mode. Token-burner costs scale with video complexity—heavily edited content generates proportionally more frames.

The implementation preserves this predictability by construction. When [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) computes `budget_cap` (line 71), it explicitly caps at `frame_cap(detail)` unless overridden by `--max-frames`.

## Summary

- **Capped modes** (`efficient`, `balanced`, `thorough`) enforce hard limits via `_even_sample`, forcing sparse representation for videos longer than ~10 minutes
- **Token-burner mode** passes `max_frames=None` to `extract_scene_or_uniform`, preserving all detected visual changes without thinning
- The **2 fps auto-ceiling** applies universally but affects capped and uncapped modes differently: it bounds candidate generation for capped modes, while token-burner scales proportionally
- File [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) defines caps, [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) implements sampling logic, and [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) orchestrates the pipeline including FPS selection

## Frequently Asked Questions

### What happens if a short video has fewer scene changes than the cap?

The capped modes keep all detected frames. The `_even_sample` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 3989-3999) checks `if len(frames) <= n: return frames` before any thinning occurs. No artificial padding is added.

### Can I override the cap without using token-burner mode?

Yes. The CLI accepts `--max-frames N` which takes precedence over the detail mode's default. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 71-80), `budget_cap` uses the explicit value when provided: `max_frames or frame_cap(detail_mode)`.

### Why does balanced mode warn about "sparse scan" on long videos?

The warning triggers when even-sampling 100 frames across extended duration produces intervals exceeding a heuristic threshold (typically 30+ seconds between frames). This alerts users that brief visual events may be absent from the extracted set.

### Does token-burner mode process frames faster?

No. Token-burner mode runs identical detection engines but skips the `_even_sample` deduplication pass. Processing time may increase slightly due to higher I/O from retaining more frames. The primary difference is **output volume and token cost**, not speed.