# What Happens When a Video Exceeds 10 Minutes in Capped Mode: Frame Limiting Behavior Explained

> Discover capped mode video frame limiting behavior when exceeding 10 minutes. Learn how FFmpeg truncates processing and generates capped samples.

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

---

**When a video exceeds the IO‑minute limit in capped mode, the system automatically limits frame extraction to a configurable maximum (default 100 frames), truncates processing via FFmpeg, and notifies the user that the output represents a capped sample rather than full video analysis.**

The **claude-video** repository by bradautomates implements a budget‑by‑duration approach in its `watch` skill to prevent runaway token costs. When processing long videos that would otherwise exceed the allotted IO‑minute ceiling, the **capped mode** enforces strict frame limits to maintain predictable resource usage. This article examines the technical implementation in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) and explains exactly how the system handles videos that surpass the 10‑minute threshold.

## Understanding Capped Mode and the IO‑Minute Ceiling

The `watch` skill operates in **capped mode** by default, employing a budget‑by‑duration strategy that balances detail against processing costs. This mode calculates the required processing time based on video duration and imposes a hard limit when that calculation exceeds the configured IO‑minute budget.

When a video’s length would require more processing time than allowed, the system treats the extraction as *capped* rather than comprehensive. The core logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), where the implementation ensures that long videos do not exhaust computational resources or token budgets.

### The Frame Budget Calculation

The system uses the `auto_fps` function to determine appropriate sampling rates based on `duration_seconds`. For videos exceeding the threshold, this calculation returns a capped target that limits the total frame count regardless of the video’s actual length. The default configuration sets `max_frames = 100`, creating a predictable ceiling for token usage across all video processing operations.

## Technical Implementation of Automatic Capping

When a video exceeds 10 minutes in capped mode, three distinct technical behaviors ensure compliance with the IO‑minute limit.

### Frame Extraction Limits in frames.py

The extraction logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) contains explicit comments defining this behavior: *“budget‑by‑duration keeps short videos dense and long videos capped.”* This philosophy manifests in the `extract` function, which receives the capped `max_frames` value and passes it to FFmpeg via the `-frames:v` argument.

The capped value forces FFmpeg to stop emitting frames after reaching the limit, even if the video continues beyond that point. This hard stop prevents any additional processing time from accumulating.

### Uniform Sampling Across Detail Modes

All detail modes share identical capping behavior to ensure consistency. As noted in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) at lines 397‑399: *“Shared by every capped engine so all detail modes sample the same way.”* This means whether using low, medium, or high detail settings, the capped engine samples frames uniformly up to the 100‑frame limit (or configured maximum) when the IO‑minute ceiling is reached.

### User Notification of Truncation

After capping occurs, the skill reports the limitation to the user with a notification such as “capped at 100 frames.” This transparency ensures users understand they are viewing a truncated representation rather than a complete frame‑by‑frame analysis of the entire video duration.

## Practical Code Examples

The following examples demonstrate how capped mode behaves when processing long videos in the claude-video framework.

### Standard Capped Extraction

This example shows the default behavior when processing a video that exceeds the 10‑minute threshold:

```python
from skills.watch.scripts.frames import extract, get_metadata, auto_fps
from pathlib import Path

video = "long_video.mp4"
metadata = get_metadata(video)

# Calculates fps and target, but caps at max_frames=100 for long videos

fps, target = auto_fps(metadata["duration_seconds"], max_frames=100)

frames = extract(
    video_path=video,
    out_dir=Path("./frames"),
    fps=fps,
    max_frames=target,  # Will be capped to 100 for videos exceeding IO-minute budget

)

print(f"Extracted {len(frames)} frames (capped).")

```

### Overriding the Cap (Not Recommended)

While you can force a higher frame budget, this may cause the skill to exceed IO‑minute limits:

```python

# Forces larger budget; risks exceeding IO-minute limits

frames = extract(
    video_path=video,
    out_dir=Path("./frames"),
    fps=fps,
    max_frames=500,  # Override default cap

)

# Note: The skill may still enforce internal capping if IO budget is exceeded

```

## Summary

- **Automatic capping** limits frame extraction to 100 frames (configurable) when a video exceeds the IO‑minute budget in capped mode.
- **FFmpeg truncation** occurs via the `-frames:v` argument, which stops frame generation at the capped value regardless of remaining video duration.
- **Uniform sampling** applies across all detail modes, ensuring consistent behavior whether processing short clips or long videos.
- **User notification** clearly indicates when capping has occurred, distinguishing between full analysis and sampled representation.
- **Source implementation** resides primarily in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), with orchestration in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).

## Frequently Asked Questions

### How does capped mode differ from uncapped mode in claude-video?

**Capped mode** enforces a maximum frame limit (default 100) when video duration would exceed the IO‑minute budget, sampling uniformly across the timeline. **Uncapped mode** processes every frame without this limit, potentially consuming significantly more tokens and processing time for long videos.

### Can I increase the 100‑frame limit for long videos?

Yes, you can pass a higher `max_frames` value to the `extract` function, but this risks exceeding the IO‑minute ceiling. The system may still enforce internal capping if the calculated processing time exceeds the configured budget, protecting against runaway costs.

### Where is the capping logic implemented in the source code?

The capping logic is implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py), specifically within the `auto_fps` function and the `extract` function. Lines 5‑6 and 397‑399 contain comments explaining the budget‑by‑duration philosophy and the shared capping behavior across all detail modes.

### What happens if a video is exactly 10 minutes long?

Videos at or near the 10‑minute threshold trigger the same budget calculation. If the processing time calculation stays within the IO‑minute ceiling, the video processes without capping. If the calculation exceeds the limit—due to high frame rates or resolution—the system applies the standard capped mode behavior, limiting extraction to the configured `max_frames` value.