Understanding the Detail Modes in Claude Video: A Complete Guide

Claude Video provides four detail modes—transcript, efficient, balanced (default), and token-burner—that control frame extraction density and transcript generation to optimize token usage versus visual coverage.

The watch command in the bradautomates/claude-video repository offers granular control over video analysis through its --detail option. These detail modes determine how many frames are extracted from a video and whether a transcript is generated, allowing users to balance processing speed, token costs, and visual comprehensiveness when sending video content to Claude.

What Are Detail Modes in Claude Video?

Detail modes in Claude Video govern the frame extraction strategy applied when processing video content. Each mode maps to a specific frame budget or cap, determining whether the system extracts keyframes, performs scene-aware sampling, or skips visual analysis entirely in favor of transcription only. The implementation splits between argument parsing in skills/watch/scripts/watch.py and configuration logic in skills/watch/scripts/config.py.

The Four Claude Video Detail Modes Explained

transcript (Text-Only Mode)

The transcript mode skips frame extraction entirely, setting the frame cap to None. This mode generates only a text transcript using captions or Whisper speech recognition, making it ideal when you need spoken content without visual analysis or want to minimize token consumption.

efficient (Fast Keyframe Extraction)

The efficient mode extracts fast-keyframes only with a strict budget of approximately 50 frames. As implemented in skills/watch/scripts/config.py, this mode prioritizes speed over visual density, suitable for quick video previews where rapid processing matters more than exhaustive scene coverage.

balanced (Default Scene-Aware Sampling)

The balanced mode serves as the default configuration, performing scene-aware extraction with a target of approximately 100 frames. According to the source code in skills/watch/scripts/config.py, this mode provides an optimal trade-off between visual comprehensiveness and token efficiency for general-purpose video analysis.

token-burner (Unlimited Frame Extraction)

The token-burner mode extracts all scene-change frames without any cap (unlimited/None), providing exhaustive visual coverage regardless of video length. Use this mode for detailed analysis of long videos where missing any visual detail is unacceptable, acknowledging the significantly higher token consumption.

Implementation and Configuration

The detail mode system is implemented across two core files in the repository. In skills/watch/scripts/watch.py (lines 35-40), the CLI registers the four valid choices for the --detail argument. The skills/watch/scripts/config.py file (lines 14-73) defines the DETAILS constant that maps each mode to its default frame budget and validation logic.

Using Detail Modes in Practice

You can specify detail modes via command line, environment variables, or configuration files.

Command line usage:

# Transcript-only analysis (no frames extracted)

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

# Quick analysis with ~50 keyframes

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

# Standard scene-aware extraction with ~100 frames (default)

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

# Exhaustive frame extraction for long videos

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

Global configuration options:

# Set via environment variable for single session

export WATCH_DETAIL=efficient

# Persist setting in config file

echo "WATCH_DETAIL=token-burner" >> ~/.config/watch/.env

As defined in skills/watch/scripts/config.py (lines 51-58), the system checks the WATCH_DETAIL environment variable and the local ~/.config/watch/.env file, falling back to balanced when invalid values are provided.

Summary

• Claude Video offers four detail modes (transcript, efficient, balanced, token-burner) that control visual analysis intensity and transcript generation.
• Frame budgets range from zero frames (transcript-only) to unlimited extraction (token-burner), with balanced (≈100 frames) serving as the default.
• Configuration occurs through the --detail CLI flag, the WATCH_DETAIL environment variable, or the ~/.config/watch/.env file.
• Implementation resides in skills/watch/scripts/watch.py for argument parsing and skills/watch/scripts/config.py for mode definitions and validation.

Frequently Asked Questions

What is the default detail mode in Claude Video?

The default detail mode is balanced, which extracts approximately 100 frames using scene-aware sampling. If you provide an invalid detail mode value via the command line or environment variables, the system automatically falls back to this default, as implemented in the configuration validation logic within skills/watch/scripts/config.py.

How does the transcript mode differ from other detail modes?

Unlike efficient, balanced, and token-burner modes—which extract visual frames at varying densities—the transcript mode skips frame extraction entirely (frame cap = None) and processes only audio content to generate text transcripts. This mode minimizes token usage when visual analysis is unnecessary.

Can I use detail modes for very long videos without hitting token limits?

For long videos where token conservation matters, use the efficient mode (≈50 frames) or transcript mode (no frames). Avoid token-burner for long content unless you require exhaustive visual coverage, as it extracts unlimited scene-change frames regardless of video duration, potentially generating substantial token costs.

Where are the detail mode constants defined in the source code?

The valid detail modes and their associated frame budgets are defined in the DETAILS constant within skills/watch/scripts/config.py (lines 14-73). The CLI argument choices are registered in skills/watch/scripts/watch.py (lines 35-40), while the canonical interface specification appears in skills/watch/SKILL.md.

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