# How Efficient, Balanced, and Token-Burner Detail Modes Differ in Claude-Video Processing

> Discover efficient balanced and token burner mode differences in Claude-Video processing. Understand frame extraction limits and scene detection to choose the best mode for your needs.

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

---

**The three detail modes in `bradautomates/claude-video` differ by frame extraction engine, frame cap limits, and scene detection depth—efficient uses keyframe-only extraction capped at 50 frames, balanced uses scene-aware detection capped at 100 frames, and token-burner removes all caps for maximum visual coverage.**

When processing video with the `watch` command in the `bradautomates/claude-video` repository, you can select from three distinct **video processing detail modes** that trade off speed, frame count, and token consumption. Each mode invokes a different extraction engine and imposes specific constraints on how many frames are analyzed and sent to the language model.

## Frame Extraction Engines and Frame Caps

The `watch` command determines how to sample your video based on the `--detail` argument, which maps to specific extraction functions and hard limits defined in the configuration layer.

### Efficient Mode: Keyframe-Only Extraction

**Efficient** mode prioritizes speed and minimal token usage by extracting only existing keyframes from the video container.

- **Engine**: `extract_keyframes` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)
- **Frame Cap**: 50 frames (defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py))
- **Behavior**: Uses `yt-dlp`-derived scene-change keyframes without running full-frame analysis, making it the fastest option for quick previews

In [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 204-210, when `detail == "efficient"`, the code calls `extract_keyframes` with `max_frames = detail_budget`, which defaults to 50 based on the `frame_cap()` function.

### Balanced Mode: Scene-Aware Detection

**Balanced** mode offers a middle ground by detecting actual scene changes and optionally filling gaps with uniform frames to hit a target count.

- **Engine**: `extract_scene_or_uniform` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)
- **Frame Cap**: 100 frames (defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py))
- **Behavior**: Runs an ffmpeg-based scene-change detector to identify meaningful boundaries, then interpolates uniform frames if needed to reach the cap

This is the default mode when `WATCH_DETAIL` is unset, as specified by `DEFAULT_DETAIL = "balanced"` in the configuration. Lines 214-225 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) dispatch to this engine for both balanced and token-burner modes.

### Token-Burner Mode: Unlimited Scene Coverage

**Token-burner** mode maximizes visual fidelity by removing frame limits entirely, keeping every detected scene-change frame regardless of quantity.

- **Engine**: `extract_scene_or_uniform` (same as balanced)
- **Frame Cap**: Unlimited (`None` returned by `frame_cap()`)
- **Behavior**: Same scene-detection algorithm as balanced, but `detail_budget` is `None`, so the engine keeps every detected scene-change frame without interpolation

When this mode generates more than 250 frames, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 19-24 emit a runtime warning alerting users to high image-token costs.

## Source Code Implementation

The architectural flow that determines video processing behavior spans three key files:

**Configuration Layer** ([`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)):
- The `frame_cap()` function returns `50` for `"efficient"`, `100` for `"balanced"`, and `None` for `"token-burner"` and `"transcript"`
- `DEFAULT_DETAIL` sets the fallback to `"balanced"`

**Dispatch Logic** ([`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)):
- Configuration is loaded via `get_config()`, reading `WATCH_DETAIL` from environment variables
- The `detail_budget` variable is calculated by subtracting user-supplied cue timestamps from `max_frames`
- For **efficient** mode, the budget is passed to `extract_keyframes`
- For **balanced** and **token-burner**, the budget is passed to `extract_scene_or_uniform`; when `None` (token-burner), the engine preserves every detected frame

**Extraction Engines** ([`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)):
- `extract_keyframes`: Pulls pre-existing keyframes using `yt-dlp` metadata
- `extract_scene_or_uniform`: Runs ffmpeg scene detection and applies uniform sampling only if a cap is specified

## Performance and Token Cost Trade-offs

Each mode represents a distinct optimization point:

- **Efficient**: Fastest execution, lowest token cost, best for quick video summaries or long content where only major visual changes matter
- **Balanced**: Moderate processing time, moderate token cost, optimal for standard video analysis where scene context is important but not exhaustive
- **Token-burner**: Highest processing time, potentially massive token consumption (hundreds of frames), suitable for detailed forensic analysis or short clips requiring frame-by-frame scrutiny

## Usage Examples

Run the `watch` command with explicit detail modes to control extraction behavior:

```bash

# Fast preview with max 50 keyframes

watch https://youtu.be/xyz --detail efficient

# Standard analysis with scene detection capped at 100 frames

watch https://youtu.be/xyz --detail balanced

# Comprehensive coverage with unlimited frame extraction

watch https://youtu.be/xyz --detail token-burner

```

Override default caps while maintaining the extraction engine:

```bash

# Balanced engine with custom frame limit

watch https://youtu.be/xyz --detail balanced --max-frames 200

```

## Summary

- **Efficient mode** uses `extract_keyframes` with a 50-frame cap, relying on existing video keyframes for maximum speed.
- **Balanced mode** uses `extract_scene_or_uniform` with a 100-frame cap, running ffmpeg scene detection for meaningful frame selection.
- **Token-burner mode** uses the same scene detection as balanced but sets `detail_budget` to `None`, removing frame limits entirely.
- Configuration caps are defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while dispatch logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) lines 204-225.
- Token-burner triggers a warning when yielding more than 250 frames to alert users to high API costs.

## Frequently Asked Questions

### What is the default detail mode if I don't specify --detail?

The default detail mode is **balanced**, as defined by `DEFAULT_DETAIL = "balanced"` in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). You can override this by setting the `WATCH_DETAIL` environment variable or passing the `--detail` argument explicitly.

### Why does token-burner mode warn about high frame counts?

When token-burner mode generates more than 250 frames, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 19-24 print a warning because each frame is encoded as an image token sent to the language model. Hundreds of frames can consume significant API quota and processing time, so the warning alerts users before incurring unexpected costs.

### Can I use efficient mode but increase the frame cap?

No, the frame cap for efficient mode is hardcoded to 50 in the `frame_cap()` function within [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). If you need more frames, you must switch to balanced mode (100 frames) or use `--max-frames` with balanced/token-burner modes, which use the scene-aware extraction engine rather than pure keyframe extraction.

### Do balanced and token-burner use different scene detection algorithms?

No, both modes use the identical `extract_scene_or_uniform` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The only difference is the `detail_budget` parameter passed to this function: balanced passes a numeric cap (100), while token-burner passes `None`, causing the engine to preserve every detected scene-change frame without interpolation.