How to Use the Token-Burner Detail Mode for Maximum Frame Coverage in Claude-Video

The token-burner detail mode extracts every scene-change frame across an entire video without any frame-count cap, using the scene-aware engine while bypassing the default limits imposed on other modes.

The claude-video repository provides a watch skill that analyzes video content through frame extraction and transcription. When you need comprehensive visual coverage of every scene change without artificial limits, the token-burner detail mode offers an uncapped, scene-aware extraction strategy that processes the complete video duration according to the source implementation.

What Is the Token-Burner Detail Mode?

The token-burner detail mode is the most exhaustive extraction setting available in the watch skill. Unlike efficiency-focused alternatives, this mode leverages the scene-aware frame engine—implemented in skills/watch/scripts/frames.py—to detect and preserve every visual transition throughout the video's entire length.

When you invoke --detail token-burner, the script selects the scene-aware extraction engine at skills/watch/scripts/watch.py lines 36-40. Simultaneously, the configuration logic in skills/watch/scripts/config.py (lines 65-71) returns None for the frame cap, effectively removing any upper limit on the number of frames extracted. This differs fundamentally from the balanced mode (100-frame cap) and efficient mode (50-frame cap).

How Token-Burner Differs from Other Detail Modes

Understanding the hierarchy of detail modes helps clarify when to deploy token-burner:

• Efficient mode: Caps extraction at 50 frames using uniform sampling, prioritizing speed and minimal token usage.
• Balanced mode: Uses the same scene-aware engine as token-burner but imposes a 100-frame maximum via the frame_cap logic.
• Token-burner mode: Invokes scene-aware detection without caps, capturing every detected scene change regardless of video length or density of visual transitions.

The critical distinction lies in the frame_cap("token-burner") function in config.py, which returns None rather than an integer, signaling the extraction pipeline to process all scene transitions.

Step-by-Step Configuration for Maximum Coverage

To achieve absolute maximum frame coverage, configure the tool using these specific options.

Enable the Uncapped Mode

Start by specifying the detail mode to remove frame limits:

watch <video-url-or-path> --detail token-burner

This command instructs the engine to keep every scene-change frame detected across the entire video duration.

Disable Near-Duplicate Removal

By default, the tool applies deduplication filters to remove visually identical consecutive frames. For absolute maximum coverage—including static slides or paused segments—disable this filter:

watch <url> --detail token-burner --no-dedup

The --no-dedup flag preserves all extracted frames even when consecutive images are visually identical, ensuring zero loss of visual information.

Optimize Resolution and Output Location

The default frame width is 512 pixels. Increase this value for higher detail, and specify a custom output directory to manage the potentially large file set:

watch <url> --detail token-burner --resolution 1024 --out-dir ./my-frames

Higher resolutions improve visual clarity but increase file sizes and token costs proportionally.

Managing Resource Limits and Warnings

The watch.py script (lines 19-25) includes a safeguard that issues a warning when extraction generates more than 250 frames. This serves as a cost alert, reminding you that the resulting markdown report will contain a substantial number of image tokens that may be expensive to process.

For very long videos exceeding 10 minutes, consider using time windows to focus extraction on specific segments while maintaining the uncapped token-burner behavior:

watch <url> --detail token-burner --start 01:00 --end 03:00

This approach applies the exhaustive scene detection only to your specified time range, balancing comprehensive coverage with manageable output size.

Complete Command Examples

# Basic token-burner usage with uncapped scene detection

watch https://www.youtube.com/watch?v=example --detail token-burner

# Maximum coverage: disable deduplication for all frames including static content

watch https://youtu.be/example --detail token-burner --no-dedup

# High-resolution extraction with custom output directory

watch ./local-video.mp4 --detail token-burner --resolution 1024 --out-dir ./frames

# Time-limited exhaustive extraction for long videos

watch https://youtu.be/example --detail token-burner --start 05:00 --end 10:00

Summary

• The token-burner detail mode removes frame count caps by returning None from frame_cap() in config.py lines 65-71, unlike the 50 or 100 frame limits in other modes.
• Scene-aware extraction processes every detected visual transition throughout the entire video when using this mode.
• The 250-frame warning in watch.py lines 19-25 alerts you to potentially high token costs but does not stop processing.
• Use --no-dedup to preserve visually identical consecutive frames for absolute maximum coverage.
• Combine with --start and --end to apply exhaustive extraction to specific segments of long videos.

Frequently Asked Questions

What is the difference between token-burner and balanced mode?

Both modes use the same scene-aware extraction engine implemented in frames.py, but balanced mode caps extraction at 100 frames while token-burner imposes no limit. According to config.py lines 65-71, frame_cap("balanced") returns 100, whereas frame_cap("token-burner") returns None, allowing the engine to capture every scene change regardless of quantity.

Why do I receive a warning about image tokens when using token-burner?

The warning mechanism at skills/watch/scripts/watch.py lines 19-25 triggers when frame extraction exceeds 250 frames. This serves as a cost notification because each frame becomes an image token in the final markdown report. The warning reminds you that processing hundreds of high-resolution images may incur significant computational expenses, though the extraction completes normally regardless of frame count.

Can I use token-burner mode with specific time segments?

Yes. Combine --detail token-burner with --start and --end timestamps to apply uncapped scene detection to specific portions of a video. This approach maintains exhaustive frame extraction within your defined window while preventing unmanageable output sizes for very long source videos.

How does the deduplication filter affect token-burner output?

By default, the deduplication filter removes near-identical consecutive frames to reduce redundancy. When using --detail token-burner for maximum coverage, add --no-dedup to disable this filtering. This preserves all extracted frames—including static slides or visually identical segments—ensuring absolutely no visual information is discarded from the source video.

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