Efficient vs Balanced vs Token-Burner Detail Modes in Claude-Video

The efficient, balanced, and token-burner detail modes in Claude-Video's watch skill differ primarily in their frame budgets and extraction algorithms—efficient limits output to 50 keyframes using a fast keyframe engine, balanced caps at 100 scene-aware frames, and token-burner removes the cap entirely to capture every scene change.

The watch skill in the bradautomates/claude-video repository processes video content by extracting visual frames for AI analysis. The detail parameter controls both the quantity of frames extracted and the algorithm used to select them, allowing you to trade processing speed against visual completeness.

Frame Budgets and Extraction Engines

The three modes share a common configuration system but apply different constraints on frame extraction. According to the source code in skills/watch/scripts/config.py, the frame_cap() function maps each mode to a specific budget:

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py#L65-L73

def frame_cap(detail: str) -> int | None:
    if detail == "efficient":   return 50
    if detail == "balanced":    return 100
    if detail == "token-burner":return None
    if detail == "transcript":  return None
    return 100

Efficient Mode (50 Frames, Keyframe Engine)

Efficient mode prioritizes speed over coverage. It applies a hard cap of 50 frames and uses a fast keyframe extraction engine that selects only the most visually salient frames. In skills/watch/scripts/watch.py, the code explicitly branches to use extract_keyframes() when this mode is active:

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L198-L215

if detail == "efficient":
    frames, frame_meta = extract_keyframes(...)
else:  # balanced, token-burner

    frames, frame_meta = extract_scene_or_uniform(...)

Use this mode for quick previews where processing speed matters more than capturing every visual detail.

Balanced Mode (100 Frames, Scene-Aware)

Balanced mode serves as the default configuration (DEFAULT_DETAIL = "balanced"). It increases the frame budget to 100 frames while using the scene-aware extraction engine. This engine samples frames based on detected scene changes, providing better visual coverage than keyframe selection while maintaining reasonable performance.

The mode is recommended for general-purpose video analysis where you need a representative sample without consuming excessive tokens.

Token-Burner Mode (Unlimited Frames, Scene-Aware)

Token-burner mode removes the frame cap entirely (None), allowing the scene-aware engine to keep every detected scene-change frame across the entire video duration. This produces the richest visual context but generates significantly more tokens.

The CLI includes a warning threshold when this mode produces excessive frames:

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L319-L322

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

Use this mode when you need deep visual analysis and token limits are not a concern.

Implementation in the Source Code

The configuration logic resides in skills/watch/scripts/config.py, which defines the default mode and frame caps. The watch.py CLI entry point parses the --detail argument and selects the appropriate extraction engine:

# https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L36-L40

ap.add_argument(
    "--detail",
    choices=["transcript", "efficient", "balanced", "token-burner"],
    help="Fidelity/speed dial: transcript (no frames), efficient (fast keyframes, cap 50), "
         "balanced (scene, cap 100), token-burner (scene, uncapped).",
)

The environment variable WATCH_DETAIL can also override the default without modifying CLI commands.

Practical Usage Examples

Select a detail mode via the --detail flag when invoking the watch skill:

# Fast preview with maximum 50 keyframes

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

# Default scene-aware sampling with 100-frame cap

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

# Uncapped scene extraction for maximum detail

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

To inspect the current configuration programmatically:

from skills.watch.scripts.config import get_config, frame_cap

cfg = get_config()
detail = cfg["detail"]          # e.g., "balanced"

cap = frame_cap(detail)        # Returns 100, or None for token-burner

print(f"Detail mode: {detail}, frame cap: {cap}")

Summary

• Efficient mode uses a fast keyframe engine and limits output to 50 frames, optimal for quick previews.
• Balanced mode is the default, using the scene-aware engine with a 100-frame cap for general-purpose analysis.
• Token-burner mode uses the scene-aware engine with no frame cap, capturing every scene change for maximum visual context.
• The modes are configured in skills/watch/scripts/config.py and implemented in skills/watch/scripts/watch.py.
• Unit tests in tests/test_config.py and tests/test_watch.py validate the default settings and engine selection logic.

Frequently Asked Questions

What is the default detail mode in Claude-Video?

The default mode is balanced. This is defined by the DEFAULT_DETAIL = "balanced" constant in skills/watch/scripts/config.py. You can override this default by setting the WATCH_DETAIL environment variable or passing the --detail flag to the CLI.

Which extraction engine does each mode use?

Efficient mode uses the extract_keyframes() function for fast keyframe selection, while balanced and token-burner modes both use extract_scene_or_uniform(). The distinction is made in skills/watch/scripts/watch.py where the code checks if detail == "efficient" to branch between the two engines.

Why is the unlimited mode called "token-burner"?

The name reflects its behavior of generating a large number of frames—potentially hundreds depending on video length and scene complexity—which increases token consumption significantly. The source code includes a warning when this mode selects more than 250 frames to alert users to the high token cost.

Can I use the detail modes without the CLI?

Yes. The configuration is accessible via the Python API by importing get_config() and frame_cap() from skills/watch/scripts/config.py. The detail mode setting propagates through the configuration dictionary and affects the extraction logic when calling the watch skill's functions directly.

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