# How to Process Videos Longer Than 10 Minutes Using the Claude-Video Watch Skill

> Learn to process long videos with Claude-Video Watch skill. Use start/end flags, token-burner mode, or transcript-only processing for videos over 10 minutes.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-29

---

**To effectively handle videos longer than 10 minutes in Claude-Video, use the `--start` and `--end` flags to limit analysis to specific segments, enable `--detail token-burner` mode to remove frame caps entirely, or switch to `--detail transcript` for text-only processing.**

The `bradautomates/claude-video` repository provides a **watch** skill designed to analyze video content through frame extraction and transcription. When processing videos longer than 10 minutes, the tool implements specific architectural safeguards to prevent sparse frame sampling while managing API token costs.

## Understanding the 10-Minute Warning System

The watch skill automatically detects when video duration exceeds the 600-second threshold. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 26-33, the code compares `full_duration` against 600 seconds and emits a warning if the video exceeds 10 minutes while using detail levels other than `transcript` or `token-burner`. This warning alerts users that the default frame cap may result in overly sparse sampling across the timeline.

The warning system triggers because [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) defines default frame caps (often 100 frames) that automatically calculate a reduced frame-per-second rate for long durations. For a 15-minute video, this might result in one frame every 9 seconds, potentially missing important visual context.

## Strategy 1: Zoom Into Specific Time Ranges

The most efficient method for handling long videos is limiting the effective duration using time-range selectors. The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point accepts `--start` and `--end` arguments (defined at lines 49-50) that restrict analysis to a specific window, allowing the `auto_fps_focus()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) to maintain higher frame density within that slice.

When you specify a range, the tool calls `auto_fps_focus()` rather than `auto_fps()`, calculating frame rates based only on the selected duration rather than the full video length. This produces more meaningful visual context for the specific segment of interest.

Process a 20-minute video, analyzing only the critical middle section:

```bash
watch \
  "https://www.youtube.com/watch?v=example" \
  --detail balanced \
  --start 00:08:00 \
  --end 00:12:00 \
  --resolution 640

```

## Strategy 2: Remove Frame Caps with Token-Burner Mode

For comprehensive visual analysis of entire long videos, bypass the default frame caps using the `token-burner` detail level. In [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) at lines 95-99, the code calculates `detail_budget = max_frames - len(cue_frames)`, but when `detail == "token-burner"`, this cap is removed entirely, allowing extraction of every scene-change frame regardless of duration.

Alternatively, manually raise the cap using `--max-frames` while keeping the `balanced` or `efficient` detail levels. This increases the budget available to the auto-fps algorithm without removing limits entirely.

Analyze a full 30-minute video with maximum frame extraction:

```bash
watch \
  "https://www.youtube.com/watch?v=example" \
  --detail token-burner \
  --resolution 512

```

## Strategy 3: Transcript-Only Analysis

When visual frame extraction is unnecessary, use the `transcript` detail level to process videos longer than 10 minutes without triggering frame-related warnings. This mode utilizes [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) to parse existing VTT subtitles, or falls back to [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) to invoke the Groq or OpenAI Whisper API (requires API key configuration via [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py)).

This approach consumes significantly fewer tokens than image-based analysis while providing complete textual context for long-form content.

Generate a full transcript for a 45-minute lecture:

```bash
watch \
  "https://www.youtube.com/watch?v=example" \
  --detail transcript \
  --whisper groq

```

## How Frame Extraction Scales with Duration

The [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) module implements two primary algorithms for frame rate calculation:

- **`auto_fps()`** – Calculates frame distribution across the full video duration to stay under `max_frames` defined in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py)
- **`auto_fps_focus()`** – Calculates frame distribution for a specific time range, enabling denser sampling when using `--start` and `--end` flags

Both functions attempt to distribute frames evenly while respecting the `detail_budget` constraints. For long videos, the default `balanced` detail level (typically capped at 100 frames) automatically reduces the sampling rate to cover the entire timeline, which is why the 10-minute warning recommends either zooming in or increasing the budget.

## Summary

- **The 10-minute threshold** triggers at 600 seconds in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), warning users about potential sparse frame sampling
- **Time-range selection** (`--start` and `--end`) limits effective duration, allowing `auto_fps_focus()` to maintain higher frame density within specific segments
- **Token-burner mode** removes frame caps entirely, extracting every scene-change frame regardless of video length
- **Transcript mode** bypasses frame extraction for long videos, using [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) or [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) for text-only analysis
- **Frame budgets** are calculated as `max_frames - len(cue_frames)` unless overridden by detail level or `--max-frames` argument

## Frequently Asked Questions

### What happens if I process a 30-minute video without any special flags?

The tool will emit a warning at lines 26-33 of [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) indicating that the video exceeds 600 seconds. It will then apply the default frame cap (typically 100 frames), resulting in approximately one frame every 18 seconds, which may miss fine-grained visual details. The warning suggests using `--start`/`--end` ranges or `--detail token-burner` to improve coverage.

### How does the auto-fps calculation work for long videos?

The `auto_fps()` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) divides the target frame cap by the video duration to determine sampling intervals. For videos longer than 10 minutes using `balanced` detail, this often results in sub-1fps rates. When using `--start` and `--end` flags, `auto_fps_focus()` recalculates based on the shortened duration, effectively increasing the frame rate for that specific window.

### Can I use Whisper transcription for videos longer than 10 minutes?

Yes, the [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) module handles long videos through API-based transcription. Configure your Groq or OpenAI API key using [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py), then add the `--whisper` flag (e.g., `--whisper groq`). This functions independently of frame extraction and works efficiently regardless of video duration, though API costs scale with audio length.

### What's the difference between balanced and token-burner detail levels?

**Balanced** applies a strict frame cap (around 100 frames) to manage token costs, forcing sparse sampling for long videos. **Token-burner** removes this cap entirely at lines 31-34 of [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), allowing the frame extractor to capture every scene-change frame. Use `balanced` for cost-efficient overviews and `token-burner` when visual completeness is critical, accepting higher token consumption.