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

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). 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 (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 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:

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:

# 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: Implements the _scale_filter function that enforces max(width, resolution) and MAX_READ_DIMENSION = 1998 for height constraints
• skills/watch/SKILL.md: Documents the 1998px height cap specifically for Claude Read compatibility (line 205)
• skills/watch/scripts/watch.py: Entry-point script that passes the --resolution argument to the frame extractor
• 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 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. 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.

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 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 outputs JPEG files with the constrained dimensions described above, ensuring compatibility with Claude's vision processing capabilities.

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