# Claude Video Token Costs by Detail Mode: A Complete Breakdown

> Analyze Claude video token costs across four detail modes. Understand transcript, efficient, balanced, and token-burner modes to optimize your usage and budget.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: performance
- Published: 2026-08-05

---

**The four detail modes in claude-video range from 0 image tokens (`transcript` mode) to approximately 22.8k image tokens (`token-burner` mode), with `efficient` (~9.8k) and `balanced` (~19.7k) falling in between.**

The claude-video project provides a `/watch` skill that extracts visual information from video URLs using a single **detail dial** to trade off speed, visual fidelity, and token consumption. This guide breaks down the estimated token cost for each mode based on the actual implementation in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

## How Detail Modes Determine Token Costs

The token cost in claude-video is driven almost entirely by **image tokens**, calculated using Anthropic's formula: `(width × height) ÷ 750`. With the default 512px width, 720p frames resolve to 512 × 288px ≈ **197 tokens per frame**. The `--detail` flag controls how many frames get extracted and sent to Claude.

### Token Cost Comparison Table

| Mode | Extraction Engine | Frame Cap | Typical Time | Estimated Image Tokens |
|------|------------------|-----------|--------------|------------------------|
| `transcript` | No frames (captions/Whisper only) | 0 | ~4.5s | **0** (≈ 26.6k text tokens) |
| `efficient` | Fast key-frame pass (`ffmpeg -skip_frame nokey`) | 50 | ~0.5s | **≈ 9.8k** |
| `balanced` | Scene-change detection with fallback | 100 | ~20.9s | **≈ 19.7k** |
| `token-burner` | Scene-change detection, uncapped | uncapped* | ~21.0s | **≈ 22.8k** |

*Uncapped mode extracted 116 frames in a 49-minute test video.

## Detailed Mode Breakdown

### Transcript Mode: Zero Image Tokens

**`transcript`** mode skips frame extraction entirely, relying solely on captions or Whisper-generated transcripts. This yields the **lowest possible token cost** for video analysis—zero image tokens—at the expense of all visual information. The ~26.6k text tokens come from the transcript itself.

Use this mode when:
- Visual content is irrelevant (e.g., lecture audio, podcast video)
- Token budget is severely constrained
- Speed is the absolute priority

```bash

# Transcript-only (cheapest)

/watch https://youtu.be/example --detail transcript

```

### Efficient Mode: ~9.8k Image Tokens

**`efficient`** mode uses `ffmpeg -skip_frame nokey` to grab up to **50 keyframes** in approximately half a second. This extracts only designated keyframes—typically scene cuts or significant motion changes—providing minimal visual coverage at minimal cost.

The token estimate assumes 50 frames × 197 tokens ≈ **9,850 image tokens**.

Use this mode when:
- Speed is critical (sub-second extraction)
- You need basic visual context without fine detail
- Processing many videos in batch

```bash

# Fast key-frame mode (~50 frames)

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

```

### Balanced Mode: ~19.7k Image Tokens (Default)

**`balanced`** mode runs **scene-change detection** with a hard cap of **100 frames**, falling back to uniform sampling if scene detection fails. At ~20.9 seconds extraction time, this is the **default mode** offering reasonable coverage without excessive token burn.

The token estimate assumes 100 frames × 197 tokens ≈ **19,700 image tokens**.

Use this mode when:
- You need comprehensive visual understanding
- Token budget allows moderate image token consumption
- No specific constraints on speed or cost

```bash

# Balanced scene-aware mode (default, ~100 frames)

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

```

### Token-Burner Mode: ~22.8k+ Image Tokens

**`token-burner`** mode runs scene-change detection with **no frame cap**, keeping every detected scene change. In testing, this extracted 116 frames from a 49-minute video for approximately **22.8k image tokens**.

Actual costs vary significantly with video length and scene complexity. Long videos with frequent cuts can push this much higher.

Use this mode when:
- Maximum visual fidelity is required
- Token budget is not a constraint
- Analyzing short, visually dense content

```bash

# Full uncapped mode (most tokens)

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

```

## Overriding Frame Caps Manually

Regardless of detail mode, you can enforce a hard limit with `--max-frames`. This caps extraction even in `token-burner` mode:

```bash

# Limit to 40 frames regardless of mode

watch https://youtu.be/example --detail balanced --max-frames 40

```

This override is processed in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) after the detail mode determines the base extraction strategy.

## Implementation Reference

The token-budget logic lives in three key files:

- [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) — Defines the skill contract and documents the detail dial's token implications
- [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) — Parses `--detail`, orchestrates ffmpeg extraction, and reports frames for Claude to `Read`
- [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md) — Contains measured frame budgets and token estimates for each mode

The extraction pipeline in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) branches based on the parsed `--detail` argument, selecting between:
- No extraction (`transcript`)
- Fast key-frame extraction (`efficient`)
- Scene-detection with explicit caps (`balanced`) or without (`token-burner`)

## Summary

- **Token costs scale linearly with extracted frames** at ~197 tokens per 512×288 frame
- **`transcript`** mode eliminates image tokens entirely (~26.6k text tokens only)
- **`efficient`** mode costs ~9.8k image tokens for 50 keyframes in <1 second
- **`balanced`** mode costs ~19.7k image tokens for 100 scene-aware frames (default)
- **`token-burner`** mode has uncapped costs starting at ~22.8k image tokens
- Use **`--max-frames`** to hard-cap any mode's token consumption

## Frequently Asked Questions

### How does claude-video calculate image token costs?

Claude-video uses Anthropic's documented formula: `(width × height) ÷ 750`. With the default 512px width and 720p frames (512 × 288px), this yields approximately 197 tokens per frame. Multiply by the number of extracted frames determined by your `--detail` mode to estimate total image token cost.

### Can I reduce token costs without using transcript mode?

Yes. Use `--max-frames` to override any mode's frame cap, or select `efficient` mode for up to 50 keyframes at ~9.8k tokens. You can also combine `balanced` mode with a lower `--max-frames` value to stay well under the default 100-frame, ~19.7k token budget.

### Why does token-burner mode vary in cost?

`token-burner` mode has **no frame cap**, so costs depend entirely on video length and scene density. A 49-minute test video generated 116 frames (~22.8k tokens), but a two-hour film with frequent cuts could extract 300+ frames. Only use this mode when visual completeness outweighs token predictability.

### Where is the detail mode logic implemented?

The extraction pipeline is implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which parses the `--detail` argument and invokes the appropriate ffmpeg command. The token budgeting documentation and measured performance tables live in [`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md), while [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) defines the skill contract and dial semantics.