# Understanding Claude‑Video Detail Modes: efficient, balanced, token‑burner, and transcript > Explore Claude-Video's detail modes: efficient, balanced, token-burner, and transcript. Learn how frame extraction & audio transcription optimize your video analysis. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: deep-dive - Published: 2026-07-19 --- **Claude‑Video supports four detail modes—`efficient`, `balanced`, `token‑burner`, and `transcript`—that control how many frames are extracted from a video, ranging from keyframe‑only sampling to full scene‑aware capture or audio‑only transcription.** The `bradautomates/claude-video` repository provides AI video analysis through the command‑line `watch` skill. The **`--detail`** flag lets you tune the trade‑off between token consumption and visual coverage by selecting one of four distinct processing strategies defined in the source code. ## The Four Claude‑Video Detail Modes The detail modes are defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and enforced by the processing logic in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). Each mode maps to a specific frame‑extraction engine and budget. ### Efficient Mode **Efficient** mode uses the `keyframes` engine to select only the most essential scene‑change moments. This keeps the frame budget minimal, making it the most token‑efficient option. In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), the `efficient` mode is configured to use aggressive sampling that discards redundant frames. When you run: ```bash watch https://example.com/video.mp4 --detail efficient ``` The system extracts only representative keyframes, significantly reducing the number of tokens sent to the model. ### Balanced Mode (Default) **Balanced** mode is the default setting, as confirmed by `DEFAULT_DETAIL` in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and unit tests in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py). It employs the `scene‑aware frames` engine to sample more densely than `efficient` while still respecting frame caps. This mode provides a middle ground between coverage and cost. If you omit the flag or specify it explicitly: ```bash watch https://example.com/video.mp4 # or watch https://example.com/video.mp4 --detail balanced ``` The code in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) selects the scene‑aware engine and applies the default frame cap defined by the `frame_cap()` function. ### Token‑Burner Mode **Token‑burner** mode disables the normal frame‑budget cap (or raises it dramatically) to retain every scene‑change frame. According to the implementation in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), this mode triggers a warning if the extraction exceeds 250 frames (`if len(frames) > 250`). Use this when you need maximum visual fidelity and are willing to consume more tokens: ```bash watch https://example.com/video.mp4 --detail token-burner ``` The engine keeps all detected scene changes up to the hard limit, providing the model with the richest visual context. ### Transcript Mode **Transcript** mode skips frame extraction entirely. Instead, it returns only the Whisper‑generated transcript (or captions). If no transcript is available, the code falls back automatically to `balanced` mode. This is ideal for audio‑centric analysis: ```bash watch https://example.com/video.mp4 --detail transcript ``` The logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which checks for transcript availability before defaulting back to scene‑aware frames. ## How Detail Modes Work Under the Hood The configuration layer in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) defines the **`DETAILS`** list and the **`frame_cap()`** function that maps each mode to its specific frame budget. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script reads the `--detail` argument (or the `WATCH_DETAIL` environment variable) and selects the appropriate engine label—either `"keyframes"` or `"scene‑aware frames"`—while applying caps and warnings. For example, the `frame_cap()` function returns different budget limits for `efficient` versus `balanced`, while `token‑burner` effectively returns `None` or a very high limit, subject to the 250‑frame safety check in the execution layer. ## Configuring Detail Modes You can specify modes per command or set a permanent default. Set the environment variable to override the default `balanced` setting: ```bash export WATCH_DETAIL=efficient watch https://example.com/video.mp4 ``` Or pass the flag directly for one‑off usage: ```bash # Minimal frames, minimal tokens watch https://example.com/video.mp4 --detail efficient # Maximum visual detail (up to ~250 frames) watch https://example.com/video.mp4 --detail token-burner # Audio only, no frames watch https://example.com/video.mp4 --detail transcript ``` ## Summary - **`efficient`** uses the `keyframes` engine for minimal token usage by sampling only essential scene changes. - **`balanced`** (default) uses the `scene‑aware frames` engine for moderate coverage and is defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) as `DEFAULT_DETAIL`. - **`token‑burner`** removes frame caps and warns at 250 frames, maximizing visual context at higher token cost. - **`transcript`** skips frames entirely, returning only Whisper transcripts with a fallback to `balanced` if audio is unavailable. ## Frequently Asked Questions ### What is the default detail mode in Claude‑Video? The default detail mode is **`balanced`**, as defined by the `DEFAULT_DETAIL` constant in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) and verified in [`tests/test_config.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_config.py). This mode uses the `scene‑aware frames` engine to provide a middle ground between coverage and token efficiency. ### How does token‑burner mode affect API costs? Token‑burner mode significantly increases token consumption because it disables the standard frame budget cap and retains all scene‑change frames up to a hard limit of 250. While this provides the richest visual context for the AI, it should be used sparingly when analyzing visually complex videos where every frame matters. ### Can I set a permanent default detail mode? Yes. You can override the default `balanced` mode by setting the **`WATCH_DETAIL`** environment variable. When this variable is present, the `watch` command uses the specified mode automatically without requiring the `--detail` flag for every invocation. ### What happens if I use transcript mode on a video without audio? If you specify `--detail transcript` but the video contains no extractable audio or Whisper transcript, the code in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) automatically falls back to **`balanced`** mode and extracts scene‑aware frames instead. This ensures you still receive usable output even when audio transcription fails.