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

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, the frame_cap function maps detail modes to absolute limits:

# 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 (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

# 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 (lines 5110-5148) illustrates this:

# 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:

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:

# 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 (lines 55-60) sets extraction density via auto_fps/auto_fps_focus:

# 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 (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 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 defines caps, frames.py implements sampling logic, and 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 (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 (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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}