# Claude Read Frame Format in bradautomates/claude-video: Resolution and Dimension Requirements

> Discover the Claude Read frame format in bradautomates/claude-video. Learn about JPEG requirements, configurable width up to 512px, and maximum height of 1998px while maintaining aspect ratio.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: api-reference
- Published: 2026-07-09

---

**Claude Read expects JPEG frames scaled to a configurable width (default 512px) with a hard maximum height of 1998px, preserving the original aspect ratio.**

The `bradautomates/claude-video` repository provides a video processing skill that extracts frames optimized for Claude's vision capabilities. Understanding the exact resolution constraints ensures your video content processes correctly without hitting compatibility limits.

## Resolution Specifications for Claude Read

### Default Width Configuration

The frame extraction pipeline defaults to a width of **512 pixels**, configurable via the `resolution` parameter in the `extract` function (lines 66-68 in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)). This default provides sufficient visual detail while maintaining efficient processing speeds for Claude Read.

### Maximum Height Constraint

Regardless of the requested width, the height is strictly capped at **1998 pixels** via the `MAX_READ_DIMENSION` constant. This limitation exists specifically for Claude Read compatibility, as documented in the skill contract at [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) (line 205). The height clamp ensures frames meet Claude's vision model requirements without exceeding maximum dimension limits.

## Implementation in the Source Code

The scaling logic resides in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) within the `_scale_filter` helper function (lines 42-46). This function implements three critical constraints:

- **Width scaling**: Forces the width to the lesser of the requested resolution or the source video width
- **Height capping**: Applies `MAX_READ_DIMENSION = 1998` as the absolute upper limit
- **Aspect ratio preservation**: Uses FFmpeg scaling filters to maintain proportional dimensions

When the scaling filter processes frames, it calculates the target dimensions and automatically adjusts to fit within the 1998px height boundary while preserving the content's aspect ratio.

## Practical Code Examples

Extract frames using the default 512px width configuration:

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

video_path = "example.mp4"
out_dir = Path("/tmp/frames")
metadata = get_metadata(video_path)
fps, _ = auto_fps(metadata["duration_seconds"])

frames = extract(
    video_path,
    out_dir,
    fps=fps,               # Auto-chosen fps (capped at 2 fps)

    resolution=512,       # Default width; height scales to ≤1998px

    max_frames=100,
)
print(frames)   # Each entry contains the JPEG path and timestamp

```

Process videos via the command-line interface with custom resolutions:

```bash

# Default resolution (512px width, height ≤1998px)

python3 "$SKILL_DIR/scripts/watch.py" "example.mp4" --resolution 512

# Higher resolution configuration (height still capped at 1998px)

python3 "$SKILL_DIR/scripts/watch.py" "example.mp4" --resolution 1024

```

Even when specifying widths above 512px, the `_scale_filter` function ensures the output never exceeds the 1998px height limit required for Claude Read compatibility.

## Key Source Files and Functions

- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**: Implements the `_scale_filter` function that enforces `max(width, resolution)` and `MAX_READ_DIMENSION = 1998` for height constraints
- **[`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md)**: Documents the 1998px height cap specifically for Claude Read compatibility (line 205)
- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Entry-point script that passes the `--resolution` argument to the frame extractor
- **[`README.md`](https://github.com/bradautomates/claude-video/blob/main/README.md)**: Notes the default 512px width and the 1998px height clamp for Claude Read (line 47)

## Summary

- Claude Read expects **JPEG images** with dimensions constrained to **width ≤ requested resolution** (default 512px) and **height ≤ 1998px**
- The `MAX_READ_DIMENSION` constant in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) enforces the absolute height limitation
- Aspect ratio is always preserved during the scaling process via FFmpeg filters
- While the width is configurable via the `resolution` parameter, the 1998px height cap is non-negotiable for Claude Read compatibility

## Frequently Asked Questions

### What is the default frame resolution for Claude Read?

The default output width is **512 pixels**, as specified in the `extract` function's default parameters in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). The height scales proportionally based on the source video's aspect ratio but cannot exceed 1998 pixels under any configuration.

### Why is there a 1998px height limit for Claude Read frames?

The 1998 pixel maximum height is a **compatibility requirement for Claude Read**, enforced by the `MAX_READ_DIMENSION` constant in the source code. This limit ensures optimal processing performance and compatibility with the Claude vision system, as documented in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md).

### Can I extract frames at resolutions higher than 512px?

**Yes.** You can specify custom widths (e.g., 1024px or 1920px) via the `--resolution` parameter in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) or the `resolution` argument in the `extract` function. However, the height will still be clamped to the 1998px maximum, and the `_scale_filter` function handles this constraint automatically while preserving aspect ratio.

### What image format does Claude Read expect from claude-video?

Claude Read expects **JPEG format** exclusively. The `extract` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) outputs JPEG files with the constrained dimensions described above, ensuring compatibility with Claude's vision processing capabilities.