# Token-Burner vs Balanced Detail Mode: When to Use Each in Claude-Video

> Learn when to use Claude Claude-Video's token-burner vs balanced detail mode. Balanced caps frames for cost-efficiency, while token-burner prioritizes visual fidelity.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: best-practices
- Published: 2026-07-29

---

**Use `balanced` detail mode when you want scene-aware frame extraction capped at approximately 100 frames for cost efficiency, and `token-burner` when you need unlimited scene-change frames for maximum visual fidelity regardless of token cost.**

The `/watch` skill in the `bradautomates/claude-video` repository extracts video frames and transcripts using configurable detail modes that control both the frame-selection strategy and the maximum number of frames generated. Understanding the distinction between these modes ensures you optimize your workflow for either processing economy or visual comprehensiveness.

## How Detail Modes Control Frame Extraction

The implementation resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), where the `--detail` argument selects between extraction routines. When you specify either `balanced` or `token-burner`, the system calls `extract_scene_or_uniform()` from [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) to perform scene-aware detection.

However, the critical difference lies in the frame cap defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py):

```python
def frame_cap(detail: str) -> int | None:
    if detail == "efficient":
        return 50
    if detail == "balanced":
        return 100          # ← capped at 100

    if detail == "token-burner":
        return None         # ← uncapped

```

- **Balanced mode**: Hard-capped at **100 frames** (unless overridden by `--max-frames`)
- **Token-burner mode**: No limit; retains every detected scene-change frame

## When to Use Balanced Detail Mode

**Balanced** is the default mode designed for typical video analysis workflows where you need a representative visual overview without excessive token consumption.

Use this mode when:

- Processing videos under a few minutes where roughly 100 frames capture the essential scene changes
- Optimizing for downstream LLM costs, as each frame consumes image tokens
- Generating lightweight reports that load quickly and process efficiently

The 100-frame cap ensures you receive a scene-aware sampling that hits the major visual transitions while keeping the output manageable.

## When to Use Token-Burner Detail Mode

**Token-burner** removes the frame ceiling entirely, preserving every detected scene-change frame regardless of quantity. This mode prioritizes visual completeness over token economy.

Choose `token-burner` when:

- Analyzing long-form or highly dynamic content where missing any scene change would compromise analysis
- Performing frame-by-frame review or fine-grained visual inspection
- Token budget is secondary to capturing maximum visual fidelity

The system issues a warning when exceeding 250 frames, as implemented in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py):

```python
if detail == "token-burner" and len(frames) > 250:
    print("> **Warning:** token-burner detail selected {len(frames)} frames…")

```

This alert reminds users that extensive frame counts significantly increase token consumption during LLM processing.

## Practical Command Examples

Run the `/watch` skill with your preferred detail mode using the CLI:

```bash

# Balanced: scene-aware extraction capped at ~100 frames

watch https://example.com/video.mp4 --detail balanced

# Token-burner: unlimited scene-change frames

watch https://example.com/video.mp4 --detail token-burner

```

Override default caps using `--max-frames` regardless of mode:

```bash

# Balanced mode with custom higher limit

watch https://example.com/video.mp4 --detail balanced --max-frames 300

```

## Summary

- **`balanced` detail mode** applies a 100-frame cap to scene-aware extraction, making it ideal for cost-effective analysis of shorter videos.
- **`token-burner` detail mode** removes frame limits entirely, capturing every scene change but potentially generating hundreds or thousands of frames.
- Both modes use the same underlying `extract_scene_or_uniform()` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py); only the cap defined in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) differs.
- The CLI warns when `token-burner` generates more than 250 frames to alert users of high token consumption.

## Frequently Asked Questions

### What is the default detail mode in claude-video?

The system defaults to `balanced` mode as defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). This ensures users receive a comprehensive yet capped frame set unless they explicitly opt into higher consumption modes.

### Can I use token-burner for short videos?

Yes, though it is designed for maximum fidelity on long or complex content. For short videos with minimal scene changes, `token-burner` may generate only slightly more frames than `balanced`, but without the 100-frame safety limit.

### How does the frame cap affect processing costs?

Each extracted frame consumes image tokens when processed by downstream LLMs. The 100-frame cap in `balanced` mode directly limits token consumption, while `token-burner` allows unlimited frames, potentially increasing API costs linearly with frame count.

### Where is the frame extraction logic implemented?

The scene-aware extraction algorithm lives in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) within the `extract_scene_or_uniform()` function. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) file handles CLI argument parsing and mode selection, while [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) stores the frame caps and validation logic.