# Claude Video Detail Modes Explained: Trade‑offs Between Transcript, Efficient, Balanced, and Token‑Burner Presets

> Explore Claude Video detail modes transcript efficient balanced and token burner Understand trade-offs between visual coverage speed and token cost for optimal performance.

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

---

**The `transcript`, `efficient`, `balanced`, and `token-burner` detail modes trade visual coverage against speed and token cost, with frame budgets ranging from 0 to unlimited frames.**

The **claude-video** project provides a `watch` skill that downloads videos, extracts frames, and optionally generates transcripts. Four detail presets control how aggressively the tool samples visual content from the source video. Understanding these trade-offs helps you optimize for token budgets, processing time, and analytical depth.

## How Detail Modes Work in claude-video

The detail mode is selected via the `--detail` CLI flag defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 35‑40). The extraction logic branches based on this selection around lines 104‑110, routing to either fast keyframe extraction or scene‑aware sampling.

### Mode Comparison Overview

| Mode | Frame Budget | Extraction Strategy | Typical Output |
|------|-------------|---------------------|--------------|
| **transcript** | 0 frames | Skips extraction entirely | Text only |
| **efficient** | ≤ 50 frames | Fast keyframe sampling | Quick visual summary |
| **balanced** | ≤ 100 frames | Scene‑aware uniform distribution | Solid coverage across duration |
| **token‑burner** | Unlimited | Scene‑aware, no cap | Exhaustive frame collection |

## Transcript Mode: Zero Visual Cost

**`transcript`** bypasses frame extraction completely. The tool downloads the video, runs Whisper transcription if no caption exists, and returns only the spoken text.

- **Frame budget:** 0 (hard‑coded skip)
- **Token cost:** Minimal (text tokens only)
- **Speed:** Fastest path; no **ffmpeg** frame decoding
- **Use case:** Rapid content review, accessibility workflows, strict token budgets

```bash
watch https://example.com/video.mp4 --detail transcript

```

This mode is ideal when you need to verify quotes, generate summaries, or process long archives where visual analysis is unnecessary.

## Efficient Mode: Fast Keyframe Sampling

**`efficient`** extracts only **keyframes**—frames where **ffmpeg** detects scene changes. This provides a lightweight visual timeline without heavy computation.

- **Frame cap:** 50 frames (default, from `frame_cap()` in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) line 34)
- **Extraction method:** `extract_keyframes()` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- **CPU/I/O:** Low; leverages **ffmpeg**'s built‑in scene detection
- **Coverage gaps:** May miss gradual changes or scenes without hard cuts

```bash
watch https://example.com/video.mp4 --detail efficient

```

Choose this mode for short videos, preliminary scans, or when you need a thumbnail‑style overview without token overhead.

## Balanced Mode: Scene‑Aware Distribution

**`balanced`** uses the same scene‑detection engine as `efficient` but adds **temporal uniformity logic** to ensure frames spread across the entire video duration. This prevents clustering at the beginning of content with many early scene changes.

- **Frame cap:** 100 frames (default, from [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) line 34)
- **Extraction method:** `extract_scene_or_uniform()` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- **CPU/I/O:** Moderate; requires parsing scene timestamps plus redistribution math
- **Warning trigger:** For videos > 10 minutes, the script warns that coverage may appear "thin" ([`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 26‑34)

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

```

This is the **default mode** when no `--detail` argument is provided. It suits general‑purpose analysis where you need representative visuals without excessive token consumption.

## Token‑Burner Mode: Unrestricted Visual Capture

**`token‑burner`** removes the frame cap entirely, allowing the scene‑aware engine to extract **every detected scene change** regardless of count.

- **Frame cap:** `None` (unlimited)
- **Warning threshold:** > 250 frames triggers a console warning ([`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 19‑24)
- **CPU/I/O:** High; unbounded storage and processing requirements
- **Token cost:** Potentially hundreds of image tokens per video

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

```

Reserve this mode for archival preservation, forensic analysis, or short clips where complete visual documentation outweighs cost concerns.

## Key Trade‑Offs at a Glance

| Metric | transcript | efficient | balanced | token‑burner |
|--------|-----------|-----------|----------|--------------|
| **Frames extracted** | 0 | ≤ 50 | ≤ 100 | Unlimited (often > 250) |
| **Processing speed** | Instant | Very fast | Moderate | Slow (scales with content) |
| **Token consumption** | Minimal | Low‑moderate | Moderate | High |
| **Visual fidelity** | None | Coarse, cut‑focused | Evenly distributed | Exhaustive |
| **Best for** | Text‑only workflows | Quick previews | General analysis | Deep archival work |

## Customizing Frame Limits and Behavior

You can override preset caps without changing modes using additional flags:

```bash

# Raise balanced cap to 200 frames

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

# Force specific sampling rate (ignores scene detection)

watch https://example.com/video.mp4 --fps 1

# Preserve specific timestamps regardless of mode

watch https://example.com/video.mp4 --detail efficient --timestamps 30,60,90

```

The `--max-frames` parameter feeds directly into the `frame_cap()` logic in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py), while `--timestamps` bypasses extraction entirely to use user‑specified frames.

## Summary

- **`transcript`** gives you spoken content with zero visual tokens—fastest and cheapest.
- **`efficient`** samples keyframes up to 50 frames for lightweight visual context.
- **`balanced`** distributes up to 100 frames evenly across the timeline for representative coverage.
- **`token‑burner`** removes all limits, capturing every scene change at maximum fidelity and cost.

Choose based on your token budget, video length, and whether you need comprehensive visual evidence or just directional context.

## Frequently Asked Questions

### What happens if token‑burner extracts too many frames?

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script prints a warning when extraction exceeds 250 frames (lines 19‑24), alerting you to high upcoming token usage. Processing continues unless you interrupt it. Consider using `--max-frames` to impose a manual ceiling if the warning appears.

### Can I use balanced mode on very long videos?

Yes, but the script warns that frame distribution may appear sparse for videos exceeding 10 minutes ([`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) lines 26‑34). For long content, either accept thinner visual coverage or switch to `token‑burner` with budget awareness.

### How do the caps actually get enforced?

The `frame_cap()` function in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (line 34) maps mode names to integer limits. This value is passed to extraction functions in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), which truncate or subsample output to respect the cap. `token‑burner` explicitly passes `None` to disable limiting.

### Is there a way to preview how many frames will extract before running?

Not directly, but you can estimate: `efficient` typically yields 10‑30 keyframes for standard content, while `balanced` fills toward its 100‑frame cap. For `token‑burner`, run with `--detail efficient` first to gauge scene density, or check the 10‑minute warning logic to anticipate sparse coverage.