Claude Video Detail Modes: Efficient, Balanced, Token-Burner, and Transcript

Claude Video's --detail flag controls frame extraction density through four modes—efficient, balanced, token-burner, and transcript—each trading off processing speed and token consumption against visual context richness.

The bradautomates/claude-video repository implements a configurable video analysis pipeline that adapts to different computational budgets and accuracy requirements. The Claude Video detail modes determine how the watch.py script samples frames from video files before generating transcripts, directly impacting both API costs and analysis depth.

How Detail Modes Work

The detail mode system centers on the frame_cap() function in skills/watch/scripts/config.py. This function returns specific frame limits based on the selected mode, while skills/watch/scripts/watch.py orchestrates the extraction pipeline and handles mode-specific logic such as the transcript-only short-circuit.

The Four Detail Modes Explained

Efficient Mode (Key-Frame Sampling)

Efficient mode minimizes token usage by selecting only the strongest scene-change frames using a key-frame engine. In skills/watch/scripts/config.py, lines 66-68 implement this logic by returning a low frame cap when detail == "efficient".

• Frame count: Often ≤30 frames regardless of video length
• Best for: Quick runs, short clips, or rough visual summaries where token cost is a primary concern
• Trade-off: May miss subtle scene changes due to sparse sampling

Balanced Mode (Scene-Aware Sampling)

Balanced mode serves as the default configuration when no detail level is specified, employing a scene-aware engine that samples frames more densely while maintaining reasonable limits. The implementation in skills/watch/scripts/config.py (lines 70-71) sets a moderate cap for this mode.

• Frame count: Approximately 100 frames for a 5-minute clip
• Best for: General-purpose analysis requiring good visual coverage without excessive token consumption
• Trade-off: Uses more tokens and processing time than efficient mode, but provides substantially better visual context

Token-Burner Mode (Maximum Visual Fidelity)

Token-burner mode prioritizes exhaustive visual analysis by retaining every detected scene-change frame. When detail == "token-burner", the frame_cap() function in skills/watch/scripts/config.py (lines 72-73) returns None, effectively removing the frame cap and allowing unlimited extraction.

• Frame count: Can exceed 250 frames for longer videos; skills/watch/scripts/watch.py (lines 319-322) issues a warning when this threshold is crossed
• Best for: Thorough analysis of visually complex content where missing any scene change would compromise results
• Trade-off: Heavy token consumption and increased processing latency; risks hitting model context limits

Transcript Mode (Audio-Only Analysis)

Transcript mode bypasses frame extraction entirely, processing only the audio stream to generate text transcripts. In skills/watch/scripts/watch.py, lines 111-113 implement a short-circuit that skips visual analysis when detail == "transcript", unless the user explicitly provides --timestamps cue points.

• Frame count: Zero visual frames (only cue-timestamps if provided via CLI)
• Best for: Dialogue-centric content where visual context is irrelevant and token conservation is critical
• Trade-off: Completely loses visual information such as on-screen text, slides, or scene context

Command-Line Usage Examples

Execute these commands to leverage different detail modes based on your analysis requirements:

# Efficient mode for quick, low-token analysis

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

# Balanced mode (default) for general-purpose coverage

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

# Token-burner mode for exhaustive visual analysis

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

# Transcript mode for audio-only processing

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

# Transcript mode with specific timestamp frames

claude-video watch https://example.com/video.mp4 --detail transcript \
    --timestamps 10,45,120

Summary

• Efficient mode uses key-frame sampling (≤30 frames) for minimal token consumption in skills/watch/scripts/config.py.
• Balanced mode provides scene-aware sampling (~100 frames/5min) as the default fallback when configuration is missing.
• Token-burner mode removes frame caps entirely, allowing unlimited scene-change detection but warning users at >250 frames in skills/watch/scripts/watch.py.
• Transcript mode eliminates frame extraction completely through the short-circuit logic at lines 111-113 of skills/watch/scripts/watch.py.
• Select modes based on your token budget, video length, and whether visual context is essential for accurate analysis.

Frequently Asked Questions

What is the default detail mode in Claude Video?

When the --detail flag is omitted, Claude Video defaults to balanced mode. This fallback is implemented in the configuration layer to ensure moderate frame sampling that balances token usage with visual coverage for general-purpose video analysis.

How does token-burner mode handle extremely long videos?

Token-burner mode does not impose a hard frame limit in frame_cap(), allowing the scene-aware engine to extract every detected scene change. However, skills/watch/scripts/watch.py (lines 319-322) issues a warning when frame counts exceed 250, alerting users to potential token limit issues and increased processing costs.

Can I extract specific frames while using transcript mode?

Yes. While transcript mode normally skips all frame extraction as implemented in skills/watch/scripts/watch.py (lines 111-113), you can preserve specific visual context by providing the --timestamps argument with comma-separated seconds (e.g., --timestamps 10,45,120). This extracts frames only at the specified cue points while still bypassing automated scene detection.

Which detail mode should I use for analyzing presentation slides?

For presentation videos where slide changes carry critical information, token-burner mode is recommended despite higher token costs. The mode ensures no slide transitions are missed by the scene-aware engine. If token budgets are constrained, balanced mode provides a reasonable middle ground, while efficient mode risks skipping rapid slide changes due to its sparse key-frame sampling.

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