# What Is the Token-Burner Mode in Claude Video and When Should You Use It?

> Discover Claude Video tokenburner mode for maximum visual fidelity. Learn when to use this uncapped frame extraction setting to preserve every scene-change frame.

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

---

**The `token-burner` mode is an uncapped frame extraction setting in Claude Video that preserves every scene-change frame detected by ffmpeg, maximizing visual fidelity at the cost of high token consumption when analyzing videos with Claude.**

The `token-burner` mode is one of four **detail modes** available in the `watch` skill of the [bradautomates/claude-video](https://github.com/bradautomates/claude-video) repository. Unlike the default `balanced` mode that limits extraction to 100 frames, `token-burner` removes this cap entirely, allowing the script to generate hundreds or thousands of images from long, high-motion videos.

## How Token-Burner Mode Works

In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `token-burner` mode is defined within the `DETAILS` configuration set alongside `efficient`, `balanced`, and `high` modes. While standard modes enforce a frame ceiling to control costs, `token-burner` specifically disables the 100-frame cap implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

When processing a video, the mode instructs ffmpeg to detect and extract every scene-change frame across the entire duration. According to the implementation in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) at line 94, this preserves all visual transitions without the sparse-scan sampling applied by other modes.

The system includes a safeguard: if the total frame count exceeds 250, the script prints a soft warning to stderr. As implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 319-322, this notification reminds users that they have selected 312 frames (or more) and that this may consume a large number of tokens.

## When to Use Token-Burner Mode

Select `token-burner` when your analysis requires maximum frame coverage and token costs are secondary to completeness:

- **Deep visual analysis of rapid transitions** — Use this mode when analyzing content with quick cuts, slide transitions, or detailed product demonstrations where every visual cue matters. The uncapped extraction ensures no scene change is omitted.

- **Long videos with dense editing** — When working with videos longer than 10 minutes that contain frequent cuts, `token-burner` avoids the "sparse scan" behavior described in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) lines 63-70, which thins out frames in capped modes to respect the 100-frame limit.

- **Unlimited token budgets** — If you are running Claude via API with ample quota, or using a local model where token consumption is irrelevant, this mode guarantees the most comprehensive visual context.

- **Debugging frame extraction** — Developers validating ffmpeg's scene-change detection can use `token-burner` to view the raw, unfiltered output of the detection algorithm without artificial limits masking the results.

## When to Avoid Token-Burner Mode

Avoid `token-burner` when processing cost-sensitive workflows or videos where frame-by-frame fidelity provides no analytical benefit. For routine summaries of talking-head videos or static presentations, the default `balanced` mode (or the faster `efficient` mode) provides sufficient context at a fraction of the token cost.

## Implementation Details

The mode logic resides in three key files:

- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)** — Defines the `DETAILS` set and maps `token-burner` to an unlimited frame cap configuration.
- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)** — The entry point that parses the `--detail` argument and implements the uncapped frame logic, including the 250-frame warning system.
- **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)** — Documents the mode's behavior and its role in the "detail dial" spectrum of extraction strategies.

Unlike `balanced` mode, which begins dropping frames after the 100th scene change to maintain a sparse representation, `token-burner` passes the `-scene 0.3` threshold directly to ffmpeg without subsequent culling.

## Usage Examples

Run the watch script with explicit detail selection:

```bash

# Extract all scene-change frames from a YouTube URL

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/example" --detail token-burner

```

Set the mode globally via environment variable:

```bash
export WATCH_DETAIL=token-burner
python3 "${SKILL_DIR}/scripts/watch.py" "my_video.mp4"

```

When frame counts exceed 250, expect this console output:

```text
[watch] extracting scene-aware frames over full 12:34s (754.0s)
> **Warning:** token-burner detail selected 312 frames. This may consume a large number of tokens.

```

## Summary

- **`token-burner`** removes the 100-frame cap used by default modes, extracting every scene-change frame detected by ffmpeg.
- **Best suited** for deep visual analysis, long videos with many cuts, unlimited token budgets, and debugging frame extraction.
- **Warning threshold** at 250 frames alerts users to potential high token costs.
- **Implementation** spans [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) (definitions), [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (execution), and [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) (documentation).
- **Avoid** for cost-sensitive projects or videos where sparse sampling suffices.

## Frequently Asked Questions

### What is the difference between token-burner and balanced mode?

The `balanced` mode enforces a 100-frame cap on scene-change extraction to control token costs, while `token-burner` removes this limit entirely. According to [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md), `balanced` begins thinning frames after 10 minutes of video to maintain the cap, whereas `token-burner` preserves every detected transition regardless of video length or frame count.

### How many frames can token-burner extract?

There is no hard limit. The mode extracts every frame where ffmpeg detects a scene change above the 0.3 threshold. For a 60-minute video with frequent cuts, this could yield thousands of frames. The system warns you at 250 frames but continues processing.

### Does token-burner affect video processing speed?

Frame extraction speed remains similar to other modes since both use the same ffmpeg scene-detection algorithm. However, the subsequent analysis phase takes significantly longer because Claude must process hundreds or thousands of images instead of the capped 100 frames. The bottleneck shifts from extraction to LLM inference time and API latency.

### Can I use token-burner with local Claude models?

Yes. In fact, `token-burner` is ideal for local deployments where token costs are irrelevant and you want maximum visual fidelity. Since local models do not incur per-token API charges, you can leverage the uncapped extraction without budget concerns, making this mode optimal for offline analysis workflows.