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

> Explore the four detail modes transcript, efficient, balanced, and token-burner in the Watch skill. Optimize frame extraction density and token costs for your video analysis.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-07-17

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 35-40), the argument parser declares the `--detail` flag with specific choices:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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.

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) implements the frame cap constraints as follows:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py) centralizes the budget logic, while [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), but **token-burner** removes the 100-frame limit imposed by balanced mode. In [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/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.