# How Efficient, Balanced, and Token-Burner Detail Modes Differ in Claude-Video > Understand Claude-Video's efficient, balanced, and token-burner modes. Discover how each mode balances processing speed and frame density to manage token consumption effectively. Learn the differences to optimize your Claude-Vi... - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: deep-dive - Published: 2026-07-09 --- **Claude-Video's three detail modes—efficient, balanced, and token-burner—trade off between processing speed and frame extraction density, with each mode using a different extraction engine and frame cap to control token consumption.** The `bradautomates/claude-video` repository provides a `watch` command that processes video URLs through Claude's vision capabilities, and selecting the right **efficient, balanced, or token-burner detail mode** determines how many frames are extracted and how many tokens are consumed during analysis. ## Frame Extraction Engines and Frame Caps Each detail mode maps to a specific frame budget and extraction strategy defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). - **Efficient mode** uses `extract_keyframes` with a maximum of **50 frames** (`frame_cap("efficient")` returns 50). This engine relies on yt-dlp-derived scene-change keyframes only, making it the fastest option because it never runs full-frame analysis. - **Balanced mode** uses `extract_scene_or_uniform` with a **100-frame cap** (`frame_cap("balanced")` returns 100). This runs an ffmpeg-based scene-change detector to identify meaningful boundaries, then fills gaps with uniformly-spaced frames if needed to hit the target count. - **Token-burner mode** uses the same `extract_scene_or_uniform` engine as balanced, but `frame_cap("token-burner")` returns `None`, meaning **no frame limit** is applied. Every detected scene-change frame is kept, which can generate hundreds of frames for long videos. ## Source Code Implementation ### Configuration Defaults In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `frame_cap()` function (lines 66-71) maps each detail string to its respective limit: 50 for efficient, 100 for balanced, and `None` for token-burner. The default mode is controlled by the `DEFAULT_DETAIL` variable set to `"balanced"`, which can be overridden via the `WATCH_DETAIL` environment variable or the `--detail` CLI argument. ### Engine Selection Logic The dispatch logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). Lines 204-210 handle the **efficient** branch by calling `extract_keyframes` with the budget derived from `detail_budget`. For **balanced** and **token-burner** modes (lines 214-225), the code calls `extract_scene_or_uniform`, passing the same budget parameter. When `detail_budget` is `None`—which occurs for token-burner—the extraction engine keeps every detected scene frame without capping. A runtime warning triggers at lines 19-24 when token-burner yields more than 250 frames, alerting users that image-token costs may be substantial. ## Performance Characteristics **Efficient** mode prioritizes speed using existing video keyframe indexes, making it ideal for quick previews where visual completeness is less critical than latency. **Balanced** mode offers moderate coverage suitable for most use cases; its scene-aware detection ensures meaningful frames are captured while the 100-frame cap prevents excessive token usage. **Token-burner** mode maximizes visual fidelity by capturing every scene change regardless of count, consuming significantly more processing time and API tokens, appropriate only when comprehensive frame analysis is required. ## Usage Examples ```bash # Fast, low-frame preview (max 50 keyframes) watch https://youtu.be/xyz --detail efficient # Moderate coverage – scene-change frames, capped at 100 watch https://youtu.be/xyz --detail balanced # Full scene coverage – no frame cap (may generate hundreds of frames) watch https://youtu.be/xyz --detail token-burner ``` Override specific caps while retaining the extraction engine: ```bash # Balanced mode but force a higher cap watch https://youtu.be/xyz --detail balanced --max-frames 200 ``` ## Summary - **Efficient mode** extracts only existing keyframes (max 50) using `extract_keyframes`, providing the fastest processing with minimal token usage. - **Balanced mode** uses scene-aware detection (`extract_scene_or_uniform`) capped at 100 frames, offering a middle ground between speed and detail. - **Token-burner mode** employs the same scene detection as balanced but imposes no frame limit, potentially extracting hundreds of frames and triggering a warning if the count exceeds 250. - Configuration resides in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), while dispatch logic operates in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) according to the `detail_budget` calculation. ## Frequently Asked Questions ### What is the default detail mode in Claude-Video? Claude-Video defaults to **balanced** mode as defined by the `DEFAULT_DETAIL` variable in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). You can override this globally by setting the `WATCH_DETAIL` environment variable, or per-command using the `--detail` flag. ### How many frames does token-burner mode typically extract? Token-burner mode has **no frame cap**, so it extracts every scene-change frame detected by the ffmpeg-based analyzer. For long videos with frequent scene changes, this can produce several hundred frames. The application emits a warning when exceeding 250 frames to alert you of potentially high token costs. ### Can I override the frame cap in efficient or balanced mode? Yes. While `frame_cap()` in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) defines defaults (50 for efficient, 100 for balanced), you can supply the `--max-frames` argument to the `watch` command to set a custom limit. This value becomes `detail_budget` in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) and is passed to the respective extraction engine. ### Which detail mode should I use for long videos? For long videos, **efficient** mode is recommended when you need quick summaries, as it limits extraction to 50 keyframes and avoids heavy CPU processing. Use **balanced** for standard analysis where scene context matters but token costs must remain controlled. Reserve **token-burner** only for short clips requiring exhaustive visual analysis, as unlimited frames become prohibitively expensive on long content.