Understanding Claude‑Video Detail Modes: efficient, balanced, token‑burner, and transcript

Claude‑Video supports four detail modes—efficient, balanced, token‑burner, and transcript—that control how many frames are extracted from a video, ranging from keyframe‑only sampling to full scene‑aware capture or audio‑only transcription.

The bradautomates/claude-video repository provides AI video analysis through the command‑line watch skill. The --detail flag lets you tune the trade‑off between token consumption and visual coverage by selecting one of four distinct processing strategies defined in the source code.

The Four Claude‑Video Detail Modes

The detail modes are defined in skills/watch/scripts/config.py and enforced by the processing logic in skills/watch/scripts/watch.py. Each mode maps to a specific frame‑extraction engine and budget.

Efficient Mode

Efficient mode uses the keyframes engine to select only the most essential scene‑change moments. This keeps the frame budget minimal, making it the most token‑efficient option.

In skills/watch/scripts/config.py, the efficient mode is configured to use aggressive sampling that discards redundant frames. When you run:

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

The system extracts only representative keyframes, significantly reducing the number of tokens sent to the model.

Balanced Mode (Default)

Balanced mode is the default setting, as confirmed by DEFAULT_DETAIL in skills/watch/scripts/config.py and unit tests in tests/test_config.py. It employs the scene‑aware frames engine to sample more densely than efficient while still respecting frame caps.

This mode provides a middle ground between coverage and cost. If you omit the flag or specify it explicitly:

watch https://example.com/video.mp4

# or

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

The code in skills/watch/scripts/watch.py selects the scene‑aware engine and applies the default frame cap defined by the frame_cap() function.

Token‑Burner Mode

Token‑burner mode disables the normal frame‑budget cap (or raises it dramatically) to retain every scene‑change frame. According to the implementation in skills/watch/scripts/watch.py, this mode triggers a warning if the extraction exceeds 250 frames (if len(frames) > 250).

Use this when you need maximum visual fidelity and are willing to consume more tokens:

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

The engine keeps all detected scene changes up to the hard limit, providing the model with the richest visual context.

Transcript Mode

Transcript mode skips frame extraction entirely. Instead, it returns only the Whisper‑generated transcript (or captions). If no transcript is available, the code falls back automatically to balanced mode.

This is ideal for audio‑centric analysis:

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

The logic resides in skills/watch/scripts/watch.py, which checks for transcript availability before defaulting back to scene‑aware frames.

How Detail Modes Work Under the Hood

The configuration layer in skills/watch/scripts/config.py defines the DETAILS list and the frame_cap() function that maps each mode to its specific frame budget. The watch.py script reads the --detail argument (or the WATCH_DETAIL environment variable) and selects the appropriate engine label—either "keyframes" or "scene‑aware frames"—while applying caps and warnings.

For example, the frame_cap() function returns different budget limits for efficient versus balanced, while token‑burner effectively returns None or a very high limit, subject to the 250‑frame safety check in the execution layer.

Configuring Detail Modes

You can specify modes per command or set a permanent default.

Set the environment variable to override the default balanced setting:

export WATCH_DETAIL=efficient
watch https://example.com/video.mp4

Or pass the flag directly for one‑off usage:

# Minimal frames, minimal tokens

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

# Maximum visual detail (up to ~250 frames)

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

# Audio only, no frames

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

Summary

• efficient uses the keyframes engine for minimal token usage by sampling only essential scene changes.
• balanced (default) uses the scene‑aware frames engine for moderate coverage and is defined in skills/watch/scripts/config.py as DEFAULT_DETAIL.
• token‑burner removes frame caps and warns at 250 frames, maximizing visual context at higher token cost.
• transcript skips frames entirely, returning only Whisper transcripts with a fallback to balanced if audio is unavailable.

Frequently Asked Questions

What is the default detail mode in Claude‑Video?

The default detail mode is balanced, as defined by the DEFAULT_DETAIL constant in skills/watch/scripts/config.py and verified in tests/test_config.py. This mode uses the scene‑aware frames engine to provide a middle ground between coverage and token efficiency.

How does token‑burner mode affect API costs?

Token‑burner mode significantly increases token consumption because it disables the standard frame budget cap and retains all scene‑change frames up to a hard limit of 250. While this provides the richest visual context for the AI, it should be used sparingly when analyzing visually complex videos where every frame matters.

Can I set a permanent default detail mode?

Yes. You can override the default balanced mode by setting the WATCH_DETAIL environment variable. When this variable is present, the watch command uses the specified mode automatically without requiring the --detail flag for every invocation.

What happens if I use transcript mode on a video without audio?

If you specify --detail transcript but the video contains no extractable audio or Whisper transcript, the code in skills/watch/scripts/watch.py automatically falls back to balanced mode and extracts scene‑aware frames instead. This ensures you still receive usable output even when audio transcription fails.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}