Claude-Video Detail Modes: Controlling Frame Extraction and Token Usage

The four Claude-Video detail modes—transcript, efficient, balanced, and token-burner—control how many frames are extracted from video content, ranging from zero frames (audio-only) to unlimited scene-change detection.

The bradautomates/claude-video repository provides a powerful watch command for processing video content through AI analysis. By leveraging the --detail flag, you can precisely manage the trade-off between comprehensive visual coverage and token consumption, ensuring optimal performance for your specific use case.

The Four Claude-Video Detail Modes

The --detail option accepts four distinct modes, each implemented in skills/watch/scripts/config.py as the DETAILS configuration set and mapped to specific frame budgets.

Transcript Mode

Transcript mode skips frame extraction entirely, producing only a text transcript from captions or Whisper speech recognition. This mode sets the frame cap to None, resulting in zero frames processed.

Use this mode when you only need spoken content or want to minimize token usage for audio-heavy videos.

Efficient Mode

Efficient mode extracts fast-keyframes only, using a strict budget of approximately 50 frames. This provides a quick visual preview without processing every scene change.

Choose this mode when speed matters more than granular visual detail, such as when generating rapid summaries of long videos.

Balanced Mode

Balanced mode serves as the default detail setting when no --detail flag is specified. It performs scene-aware extraction targeting approximately 100 frames, providing a comprehensive visual summary without excessive token consumption.

This mode offers the best general-purpose solution, balancing coverage and cost for most video analysis tasks.

Token-Burner Mode

Token-burner mode extracts all scene-change frames without imposing a cap, setting the limit to None (unlimited). This produces the most exhaustive visual coverage possible.

Activate this mode for very long videos where you need complete scene detection, accepting significantly higher token usage in exchange for maximum visual fidelity.

Implementation and Source Code

The detail mode system is implemented across two core files in the bradautomates/claude-video repository.

In skills/watch/scripts/watch.py, the CLI registers the four choices as valid arguments for the --detail flag. The entrypoint parses this value, determines the appropriate frame cap, and drives the extraction process according to the selected mode.

The configuration logic resides in skills/watch/scripts/config.py, which defines the allowed set of modes (DETAILS) and maps each mode to its default frame budget. This centralized configuration ensures consistent behavior across the application.

Configuring Default Detail Modes

You can set a global default detail mode to avoid specifying --detail with every command. The system respects the WATCH_DETAIL environment variable, allowing you to define your preferred mode for all sessions:

export WATCH_DETAIL=efficient

Alternatively, store persistent configuration in ~/.config/watch/.env:

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

If you provide an invalid value, the system gracefully falls back to balanced mode as implemented in the configuration loading logic within skills/watch/scripts/config.py.

Command-Line Usage Examples

Process videos with specific detail modes using the --detail flag:

# Transcript-only (no frames)

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

# Fast keyframe extraction (≈50 frames)

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

# Balanced extraction (≈100 frames, default behavior)

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

# Unlimited scene extraction (all frames)

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

These examples demonstrate how to invoke each mode directly from the command line.

Summary

• Claude-Video detail modes control frame extraction via the --detail flag in the watch command.
• Four modes are available: transcript (0 frames), efficient (≈50 frames), balanced (≈100 frames, default), and token-burner (unlimited).
• Configuration is defined in skills/watch/scripts/config.py, while argument parsing occurs in skills/watch/scripts/watch.py.
• Global defaults can be set via the WATCH_DETAIL environment variable or ~/.config/watch/.env file.
• Balanced mode provides the optimal trade-off for most use cases, while token-burner offers exhaustive coverage at higher token cost.

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 detection. If you omit the --detail flag or provide an invalid value, the system automatically falls back to this setting as defined in skills/watch/scripts/config.py.

How do I reduce token usage when processing videos?

Use transcript mode to skip frame extraction entirely, processing only audio content. Alternatively, efficient mode limits extraction to approximately 50 fast-keyframes, significantly reducing tokens compared to the default balanced mode or token-burner mode.

When should I use token-burner mode instead of balanced?

Choose token-burner mode when analyzing very long videos where you require exhaustive visual coverage of every scene change. Unlike balanced mode, which caps extraction at approximately 100 frames, token-burner has no frame limit, making it ideal for detailed forensic analysis or comprehensive visual indexing where token cost is not a constraint.

Where are detail mode configurations stored in the source code?

The valid detail modes and their frame budgets are defined in skills/watch/scripts/config.py within the DETAILS configuration mapping. CLI argument validation occurs in skills/watch/scripts/watch.py, while environment variable overrides are processed in the configuration module's loading logic.

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