Token-Burner vs Balanced Detail Mode: When to Use Each in Claude-Video

Use balanced detail mode when you want scene-aware frame extraction capped at approximately 100 frames for cost efficiency, and token-burner when you need unlimited scene-change frames for maximum visual fidelity regardless of token cost.

The /watch skill in the bradautomates/claude-video repository extracts video frames and transcripts using configurable detail modes that control both the frame-selection strategy and the maximum number of frames generated. Understanding the distinction between these modes ensures you optimize your workflow for either processing economy or visual comprehensiveness.

How Detail Modes Control Frame Extraction

The implementation resides in skills/watch/scripts/watch.py, where the --detail argument selects between extraction routines. When you specify either balanced or token-burner, the system calls extract_scene_or_uniform() from frames.py to perform scene-aware detection.

However, the critical difference lies in the frame cap defined in skills/watch/scripts/config.py:

def frame_cap(detail: str) -> int | None:
    if detail == "efficient":
        return 50
    if detail == "balanced":
        return 100          # ← capped at 100

    if detail == "token-burner":
        return None         # ← uncapped

• Balanced mode: Hard-capped at 100 frames (unless overridden by --max-frames)
• Token-burner mode: No limit; retains every detected scene-change frame

When to Use Balanced Detail Mode

Balanced is the default mode designed for typical video analysis workflows where you need a representative visual overview without excessive token consumption.

Use this mode when:

• Processing videos under a few minutes where roughly 100 frames capture the essential scene changes
• Optimizing for downstream LLM costs, as each frame consumes image tokens
• Generating lightweight reports that load quickly and process efficiently

The 100-frame cap ensures you receive a scene-aware sampling that hits the major visual transitions while keeping the output manageable.

When to Use Token-Burner Detail Mode

Token-burner removes the frame ceiling entirely, preserving every detected scene-change frame regardless of quantity. This mode prioritizes visual completeness over token economy.

Choose token-burner when:

• Analyzing long-form or highly dynamic content where missing any scene change would compromise analysis
• Performing frame-by-frame review or fine-grained visual inspection
• Token budget is secondary to capturing maximum visual fidelity

The system issues a warning when exceeding 250 frames, as implemented in watch.py:

if detail == "token-burner" and len(frames) > 250:
    print("> **Warning:** token-burner detail selected {len(frames)} frames…")

This alert reminds users that extensive frame counts significantly increase token consumption during LLM processing.

Practical Command Examples

Run the /watch skill with your preferred detail mode using the CLI:

# Balanced: scene-aware extraction capped at ~100 frames

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

# Token-burner: unlimited scene-change frames

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

Override default caps using --max-frames regardless of mode:

# Balanced mode with custom higher limit

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

Summary

• balanced detail mode applies a 100-frame cap to scene-aware extraction, making it ideal for cost-effective analysis of shorter videos.
• token-burner detail mode removes frame limits entirely, capturing every scene change but potentially generating hundreds or thousands of frames.
• Both modes use the same underlying extract_scene_or_uniform() function in frames.py; only the cap defined in config.py differs.
• The CLI warns when token-burner generates more than 250 frames to alert users of high token consumption.

Frequently Asked Questions

What is the default detail mode in claude-video?

The system defaults to balanced mode as defined in skills/watch/scripts/config.py. This ensures users receive a comprehensive yet capped frame set unless they explicitly opt into higher consumption modes.

Can I use token-burner for short videos?

Yes, though it is designed for maximum fidelity on long or complex content. For short videos with minimal scene changes, token-burner may generate only slightly more frames than balanced, but without the 100-frame safety limit.

How does the frame cap affect processing costs?

Each extracted frame consumes image tokens when processed by downstream LLMs. The 100-frame cap in balanced mode directly limits token consumption, while token-burner allows unlimited frames, potentially increasing API costs linearly with frame count.

Where is the frame extraction logic implemented?

The scene-aware extraction algorithm lives in skills/watch/scripts/frames.py within the extract_scene_or_uniform() function. The watch.py file handles CLI argument parsing and mode selection, while config.py stores the frame caps and validation logic.

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