Efficient vs Balanced Detail Modes in claude-video: What's the Difference?

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 (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 (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. 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 (lines 198-199).

Scene-Aware Sampling (Balanced)

Balanced mode utilizes extract_scene_or_uniform from 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:

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

Use balanced mode for richer context and scene detection:

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

Add specific timestamps that consume the budget before automatic extraction:

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.
• Configuration values are defined in 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 (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 (lines 71-73). To change it, either modify the default value in that file or explicitly pass the --detail argument with every command invocation.

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