Understanding the Detail Modes in the Watch Skill: A Complete Guide

The watch skill in bradautomates/claude-video provides four detail modes—transcript, efficient, balanced, and token-burner—that control frame extraction density and token costs, ranging from zero visual frames to unlimited scene-aware captures.

The watch skill in the bradautomates/claude-video repository offers a configurable "fidelity/speed dial" through the --detail command-line option and the WATCH_DETAIL environment variable. This parameter determines how visual information is extracted from video files, directly impacting both processing speed and token consumption. Understanding these detail modes allows you to optimize the trade-off between comprehensive visual analysis and computational efficiency.

What Are Detail Modes in the Watch Skill?

Detail modes function as extraction presets defined in skills/watch/scripts/config.py. Each mode maps to a specific frame budget managed by the frame_cap() function, which returns either an integer limiting the maximum frames or None for unlimited extraction. The available modes are stored in the DETAILS set: {"transcript", "efficient", "balanced", "token-burner"}.

The Four Detail Modes Explained

transcript

The transcript mode extracts no visual frames whatsoever. In skills/watch/scripts/config.py, the frame_cap() function returns None for this mode, signaling zero-frame extraction. When captions exist natively on the video source, this mode can skip the video download entirely, conserving bandwidth and eliminating image token costs. Use this mode when you require only the spoken text content and no visual analysis.

efficient

The efficient mode prioritizes speed over visual fidelity by extracting fast keyframes with a hard cap of 50 frames. According to the frame_cap() implementation in skills/watch/scripts/config.py, this mode returns 50 as the maximum frame allowance. The underlying extraction uses the extract_keyframes strategy from skills/watch/scripts/frames.py rather than scene-aware analysis. This mode suits long videos where you need a rough visual overview without excessive token expenditure.

balanced

Balanced serves as the default detail mode, implementing scene-aware frame extraction with a maximum cap of 100 frames. The frame_cap() function returns 100 for this setting, providing representative scene changes while maintaining a moderate token budget. This mode utilizes the extract_scene_or_uniform function from skills/watch/scripts/frames.py to identify meaningful visual transitions. For most general-purpose video analysis tasks, balanced offers the optimal compromise between coverage and cost.

token-burner

The token-burner mode delivers maximum visual fidelity through uncapped, scene-aware frame extraction. In skills/watch/scripts/config.py, frame_cap() returns None for this mode, removing any upper limit on the number of frames extracted. Like balanced, it uses scene-aware extraction (extract_scene_or_uniform), but processes every detected scene change regardless of count. Reserve this mode for detailed analysis of short clips where exhaustive visual coverage justifies higher token costs.

How Detail Modes Affect Frame Processing

In skills/watch/scripts/watch.py (lines 35-40), the argument parser declares the --detail flag with specific choices:

ap.add_argument(
    "--detail",
    choices=["transcript", "efficient", "balanced", "token-burner"],
    default=None,
    help="Fidelity/speed dial: transcript (no frames), efficient (fast keyframes, cap 50), "
         "balanced (scene, cap 100), token-burner (scene, uncapped).",
)

After parsing, the script resolves the active mode using detail = args.detail or str(config["detail"]). It then calculates a detail_budget using the logic: detail_budget = max_frames if max_frames is None else max(0, max_frames - len(cue_frames)). For non-transcript modes, the pipeline invokes extraction strategies from skills/watch/scripts/frames.py—either extract_keyframes for efficient mode or extract_scene_or_uniform for balanced and token-burner modes.

Configuration and Usage Examples

You can invoke these modes via command-line arguments or by setting the WATCH_DETAIL environment variable. You may also override any mode's frame cap using the --max-frames parameter.

# Transcript-only (no frames, skips video download if captions exist)

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/abc123" --detail transcript

# Efficient mode: fast keyframes, maximum 50 frames

python3 "${SKILL_DIR}/scripts/watch.py" "video.mp4" --detail efficient

# Balanced mode (default): scene-aware extraction, maximum 100 frames

python3 "${SKILL_DIR}/scripts/watch.py" "https://vimeo.com/456789" --detail balanced

# Token-burner: uncapped scene-aware frames (highest token cost)

python3 "${SKILL_DIR}/scripts/watch.py" "movie.mov" --detail token-burner

The mapping logic in skills/watch/scripts/config.py implements the frame cap constraints as follows:

def frame_cap(detail: str) -> int | None:
    if detail == "efficient":   return 50
    if detail == "balanced":    return 100
    if detail == "token-burner":return None   # uncapped

    if detail == "transcript":  return None   # no frames

    return 100

Summary

• Transcript mode eliminates visual extraction entirely, returning None from frame_cap() and potentially skipping video downloads when native captions exist.
• Efficient mode captures fast keyframes with a 50-frame cap using extract_keyframes, optimizing for speed on long videos.
• Balanced mode provides scene-aware extraction capped at 100 frames via extract_scene_or_uniform, serving as the default for general-purpose analysis.
• Token-burner mode removes frame limits entirely, extracting every scene-aware frame for maximum visual fidelity at higher token costs.
• The frame_cap() function in skills/watch/scripts/config.py centralizes the budget logic, while skills/watch/scripts/watch.py coordinates the extraction pipeline based on the selected mode.

Frequently Asked Questions

What is the default detail mode in the watch skill?

The balanced mode serves as the default when no --detail argument is provided. According to the frame_cap() function in skills/watch/scripts/config.py, this default returns a 100-frame cap, providing scene-aware extraction suitable for most video analysis tasks.

Can I override the frame cap while using a specific detail mode?

Yes. While each mode has a default cap defined in frame_cap()—50 for efficient, 100 for balanced, and unlimited for token-burner—you can specify --max-frames N to impose a tighter budget regardless of the selected mode. This allows fine-grained control over token consumption without switching modes.

When should I use transcript mode instead of other detail modes?

Use transcript mode when you only need the spoken content from a video and require no visual analysis. This mode sets the frame cap to None (zero frames) and, as implemented in skills/watch/scripts/watch.py, can skip the video download entirely if native captions exist on the source platform, saving both bandwidth and processing time.

How does token-burner mode differ from balanced mode?

Both modes use scene-aware extraction via extract_scene_or_uniform from skills/watch/scripts/frames.py, but token-burner removes the 100-frame limit imposed by balanced mode. In skills/watch/scripts/config.py, token-burner returns None from frame_cap(), allowing unlimited frame extraction. Use token-burner only when you need exhaustive visual coverage of short clips and can accommodate the significantly higher token costs.

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