How Claude Video Estimates Token Cost for Different Detail Modes

Claude Video uses a four-level detail dial that trades off extraction speed, visual fidelity, and token consumption, with costs ranging from 0 image tokens (transcript-only) to 22,800+ tokens (uncapped scene detection).

The claude-video repository by bradautomates implements a /watch skill that processes YouTube videos through Claude's vision API. The token cost estimation depends entirely on how many frames are extracted and sent to the model, controlled by the --detail flag parsed in skills/watch/scripts/watch.py.

---

Detail Modes and Their Token Costs

The four modes use different extraction engines with varying frame caps. Each extracted frame becomes an image that Claude reads at approximately 197 tokens per frame (calculated via Anthropic's formula: (width × height) ÷ 750 for 512×288 px frames).

Mode	Engine	Frame Cap	Extraction Time	Image Tokens
transcript	None (text-only)	0	~4.5 s	0 (~26.6K text tokens)
efficient	ffmpeg -skip_frame nokey	50	~0.5 s	~9,800
balanced	Scene-change detection	100	~20.9 s	~19,700
token-burner	Scene-change (uncapped)	Unlimited	~21.0 s	~22,800+

Source measurements are documented in README.md under the "Detail modes — measured" section and in skills/watch/SKILL.md.

---

How Frame Extraction Maps to Token Cost

Transcript Mode: Zero Image Tokens

The cheapest option skips visual analysis entirely. In watch.py, this mode bypasses ffmpeg frame extraction and returns only Whisper transcripts or YouTube captions.

# No image tokens consumed

/watch https://youtu.be/example --detail transcript

Efficient Mode: Fast Key-Frame Sampling

Uses ffmpeg -skip_frame nokey to grab up to 50 intra-coded frames rapidly. The hard cap keeps token costs predictable for long videos.

# ~50 frames, ~9,800 image tokens

/watch https://youtu.be/example --detail efficient

Balanced Mode: Scene-Aware Default

The recommended default runs scene-change detection with a 100-frame ceiling. If scene detection fails, it falls back to uniform sampling. This mode appears in SKILL.md as the "detail dial" sweet spot.

# ~100 frames, ~19,700 image tokens (default)

/watch https://youtu.be/example --detail balanced

Token-Burner Mode: Uncapped Fidelity

Removes the frame cap entirely, keeping every detected scene change. A 49-minute test video yielded 116 frames (~22,800 tokens). Use sparingly for analysis requiring maximum visual context.

# Uncapped frames, highest token cost

/watch https://youtu.be/example --detail token-burner

---

Overriding Token Budgets Manually

The --max-frames argument in watch.py allows capping any mode regardless of its default:

# Force 40-frame maximum on balanced mode

watch https://youtu.be/example --detail balanced --max-frames 40

This overrides the built-in caps (50/100/unlimited) and directly controls token expenditure.

---

Implementation Details in watch.py

The token cost estimation logic resides in skills/watch/scripts/watch.py. The script:

1. Parses --detail and --max-frames arguments
2. Selects the ffmpeg pipeline (key-frame skip, scene detection, or none)
3. Extracts frames to temp storage with timestamps
4. Returns frame paths for Claude's Read tool

The 197 tokens per frame calculation assumes default 512px width maintained across all modes. Actual costs scale linearly with frame count, making the --detail flag the primary cost control mechanism.

---

Summary

• Token cost is frame-count linear: Each extracted frame ≈ 197 image tokens via (width × height) / 750
• Four detail modes provide predictable cost tiers: 0, ~10K, ~20K, or uncapped tokens
• balanced is the default with 100-frame cap; transcript eliminates image tokens entirely
• Manual override via --max-frames in watch.py caps any mode's token consumption
• Source documentation in README.md and skills/watch/SKILL.md provides measured benchmarks

---

Frequently Asked Questions

How does Claude Video calculate tokens per image frame?

Claude Video applies Anthropic's documented formula: (width × height) ÷ 750. With the default 512×288 pixel frames, this yields approximately 197 tokens per frame. The calculation is implicit in the token estimates provided in README.md rather than computed at runtime.

Can I use Claude Video without consuming any image tokens?

Yes. The transcript detail mode skips frame extraction entirely, consuming only text tokens (~26,600 for typical transcripts). Pass --detail transcript to watch.py or the /watch skill to enable this mode.

What happens if a video has more scene changes than the frame cap?

In balanced mode, scene-change detection runs but results are truncated to the 100-frame cap. In token-burner mode, no cap applies—all detected scenes are preserved. The --max-frames flag can impose stricter limits on either mode.

Where is the detail mode logic implemented in the codebase?

The implementation spans three files: skills/watch/scripts/watch.py handles argument parsing and ffmpeg orchestration; skills/watch/SKILL.md defines the skill contract; and README.md documents measured token benchmarks and usage patterns.

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