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

> Understand Claude-Video detail modes: efficient balanced and token-burner. Learn how they optimize speed and frame count for effective video analysis.

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

---

**Claude-Video’s `watch` command offers three detail modes—efficient, balanced, and token-burner—that trade off processing speed and frame count by switching between keyframe-only extraction and scene-aware analysis with configurable caps.**

The `bradautomates/claude-video` repository provides a video processing tool that extracts frames from videos for AI analysis. These three detail modes determine how the `watch` command samples visual content, directly impacting both the token cost and the comprehensiveness of the video summary.

## What Are Detail Modes in Claude-Video?

Detail modes control the frame extraction strategy used when processing a video URL. According to the source code in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the `--detail` flag selects between three distinct engines, each designed for different use cases ranging from quick previews to maximum visual fidelity.

## Technical Implementation of Each Mode

The implementation splits the three modes into two extraction engines: **keyframe extraction** for efficient mode, and **scene-aware extraction** for balanced and token-burner modes.

### Efficient Mode: Keyframe-Only Extraction

**Efficient mode** is optimized for speed and minimal token usage. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) lines 204-210, when `detail == "efficient"`, the system calls `extract_keyframes` from [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This engine uses `yt-dlp` to extract existing scene-change keyframes from the video container without running full-frame analysis.

The default frame cap for this mode is **50 frames**, defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) by the `frame_cap()` function. This makes efficient mode ideal for quick previews of long videos where only major scene changes matter.

### Balanced Mode: Scene-Aware with Cap

**Balanced mode** is the default setting (controlled by `DEFAULT_DETAIL` in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py)). It provides moderate coverage by running an ffmpeg-based scene-change detector via `extract_scene_or_uniform` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

As implemented in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 214-225, balanced mode uses the `frame_cap()` setting of **100 frames**. The scene-aware engine detects meaningful scene boundaries, then optionally fills remaining slots with uniformly-spaced frames to hit the target count. This offers better coverage than efficient mode while maintaining reasonable token costs.

### Token-Burner Mode: Unlimited Scene Analysis

**Token-burner mode** maximizes visual detail by removing frame limits entirely. It uses the same `extract_scene_or_uniform` engine as balanced mode, but passes `None` as the `detail_budget` parameter, resulting in no frame cap. According to [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py), `frame_cap("token-burner")` returns `None`.

This mode keeps every detected scene-change frame, which can generate hundreds of frames for long videos. The system includes a runtime warning in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 19-24 that triggers if token-burner yields more than 250 frames, alerting users to potentially high image-token costs.

## Configuration and Frame Caps

The frame limits are centralized in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). The `frame_cap()` function maps each mode to its budget:

- `"efficient"`: returns `50`
- `"balanced"`: returns `100`  
- `"token-burner"`: returns `None` (unlimited)

Users can override the default mode via the `WATCH_DETAIL` environment variable or the `--detail` CLI argument. Additionally, the `--max-frames` flag can adjust the cap for any mode, though token-burner ignores the cap unless explicitly constrained.

## Usage Examples

Run the `watch` command with different detail modes using the `--detail` flag:

```bash

# Fast preview using existing keyframes only (max 50)

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

# Default scene-aware extraction (max 100 frames)

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

# Maximum detail with no frame limit

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

```

Override caps while keeping the scene-aware engine:

```bash

# Balanced engine with custom cap of 200

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

```

## Choosing the Right Detail Mode

Select **efficient** when you need rapid results and only require key scene changes. Choose **balanced** for general-purpose video analysis where moderate coverage suffices. Reserve **token-burner** for short, complex videos where every visual detail matters, keeping in mind that processing time and token costs scale with frame count.

## Summary

- **Efficient mode** uses `extract_keyframes` with a 50-frame cap for maximum speed by sampling only existing keyframes.
- **Balanced mode** runs `extract_scene_or_uniform` with a 100-frame cap, combining scene detection with uniform sampling for moderate coverage.
- **Token-burner mode** uses the same scene-aware engine but sets `detail_budget` to `None`, capturing every scene-change frame without limits.
- Configuration resides in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while dispatch logic lives 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 if it extracts more than 250 frames to prevent unexpected high costs.

## Frequently Asked Questions

### How do I set the default detail mode for all Claude-Video operations?

Set the `WATCH_DETAIL` environment variable to `"efficient"`, `"balanced"`, or `"token-burner"` in your shell configuration. If not set, the system defaults to `"balanced"` as defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) under `DEFAULT_DETAIL`.

### Can I use token-burner mode but limit the total frames?

Yes. While token-burner has no default cap, you can enforce a limit using the `--max-frames` argument. When provided, this value becomes the `detail_budget` passed to `extract_scene_or_uniform`, overriding the `None` value returned by `frame_cap("token-burner")`.

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

The warning mechanism in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 19-24 activates when token-burner extracts more than 250 frames. Since each frame consumes image tokens when sent to the AI, this alert prevents users from accidentally incurring high API costs on long videos with frequent scene changes.

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

If the scene-aware engine detects fewer scenes than the cap allows, balanced mode fills the remaining slots with uniformly-spaced frames to reach the target count. Efficient mode simply returns fewer frames since it only extracts existing keyframes and does not interpolate additional frames.