# Efficient vs Balanced Detail Modes in claude-video: What's the Difference? > Understand Efficient vs Balanced detail modes in claude-video. Efficient mode uses fast keyframe extraction up to 50 frames. Balanced mode uses scene-aware analysis up to 100 frames. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: deep-dive - Published: 2026-07-29 --- **Efficient mode extracts up to 50 frames using fast keyframe extraction, while balanced mode extracts up to 100 frames using scene-aware analysis to capture distinct visual changes.** The `watch` command in the bradautomates/claude-video repository processes video content through configurable detail settings that trade off speed against visual coverage. Understanding the difference between **efficient** and **balanced** detail modes allows you to optimize frame extraction for either rapid previews or comprehensive scene analysis. ## Frame Capacity and Performance Limits The primary distinction between these modes is the hard frame cap enforced by the configuration layer. ### Efficient Mode **Efficient** mode targets speed with a fixed cap of **50 frames per clip**. According to [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) (lines 65-68), the `frame_cap()` function returns `50` when the detail argument is `"efficient"`. This mode minimizes CPU and I/O overhead by leveraging existing codec metadata rather than analyzing visual content. ### Balanced Mode **Balanced** mode, which serves as the default configuration in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 71-73), doubles the capacity to **100 frames per clip**. The `frame_cap()` function returns `100` for `"balanced"` (lines 69-70). This provides more thorough coverage suitable for capturing nuanced scene changes without overwhelming downstream processing. ## Extraction Engines: How Frames Are Selected Beyond capacity limits, the modes differ fundamentally in how they select which frames to extract from the video timeline. ### Keyframe Extraction (Efficient) In efficient mode, the system calls `extract_keyframes` implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This engine pulls frames exclusively at timestamps where the video encoder marks new keyframes (I-frames). Because it relies on existing codec data rather than pixel analysis, extraction is extremely fast. The engine is labeled `"keyframes"` in the execution log at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 198-199). ### Scene-Aware Sampling (Balanced) Balanced mode utilizes `extract_scene_or_uniform` from [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This engine actively analyzes the video to detect scene changes, selecting frames that best represent distinct visual segments. If scene detection fails or produces insufficient results, it falls back to uniform sampling. This method appears in logs as `"scene-aware frames"` (watch.py, lines 198-199). ## Frame Budget Calculation and Timestamps Both modes follow an identical workflow for budget management. The effective frame budget equals the mode's cap minus any frames requested via the `--timestamps` argument. For example, specifying three custom timestamps in efficient mode consumes three slots from the 50-frame budget, leaving 47 frames for the keyframe engine to fill. ## Practical Usage Examples Run efficient mode for quick previews of long videos: ```bash watch https://example.com/video.mp4 --detail efficient ``` Use balanced mode for richer context and scene detection: ```bash watch https://example.com/video.mp4 --detail balanced ``` Add specific timestamps that consume the budget before automatic extraction: ```bash watch https://example.com/video.mp4 \ --detail efficient \ --timestamps "00:01,00:45,01:20" ``` In this example, the three specified timestamps are extracted first, and the remaining 47 frames are populated by the efficient keyframe engine. ## Summary - **Efficient mode** limits extraction to **50 frames** using fast keyframe sampling from codec metadata, labeled `"keyframes"` in logs. - **Balanced mode** limits extraction to **100 frames** using scene-aware analysis via `extract_scene_or_uniform`, labeled `"scene-aware frames"`. - Both modes respect a strict frame budget where manual timestamps are extracted first and the remainder is filled by the respective engine. - The default detail mode is **balanced**, as implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). - Configuration values are defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) within the `frame_cap()` function (lines 65-70). ## Frequently Asked Questions ### What is the default detail mode in claude-video? The default detail mode is **balanced**, as specified in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 71-73). If you run the `watch` command without specifying `--detail`, it automatically applies the 100-frame cap and scene-aware extraction. ### Can I exceed the frame cap by adding manual timestamps? No, timestamps consume the frame budget rather than adding to it. When you specify timestamps via `--timestamps`, those frames are extracted first, and the remaining budget (47 frames for efficient, 97 for balanced) is filled by the automatic extraction engine. ### Which mode should I use for video analysis with many rapid scene changes? Use **balanced** mode for content with frequent scene changes. The `extract_scene_or_uniform` engine specifically detects visual transitions to ensure distinct scenes are represented in the 100-frame sample, whereas efficient mode might miss rapid changes if they don't align with codec keyframes. ### How do I change the default detail mode setting? The default is hardcoded as `"balanced"` in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 71-73). To change it, either modify the default value in that file or explicitly pass the `--detail` argument with every command invocation.