How to Customize the Frame Resolution for Video Analysis in Claude-Video

You can customize the frame resolution in Claude-Video by using the --resolution CLI flag (default 512px) or the resolution parameter in Python functions, which sets the maximum width for extracted JPEG frames while automatically preserving aspect ratio and capping height at 1998px.

The bradautomates/claude-video repository provides a watch entry point for video analysis that extracts frames as JPEG images. When you customize the frame resolution, you control the maximum width of these extracted frames, allowing you to balance image detail against processing speed and storage requirements according to the source code implementation.

Understanding the Resolution Control Mechanism

Claude-Video implements frame resolution customization through two core components: the CLI argument parser and an FFmpeg scaling filter.

CLI Argument Parsing in watch.py

In skills/watch/scripts/watch.py, the watch entry point defines the --resolution argument using argparse:

ap.add_argument("--resolution", type=int, default=512, help="Frame width in pixels (default 512)")

This stores the user-provided integer in args.resolution, which defaults to 512 pixels if not specified.

FFmpeg Scaling Filter in frames.py

The actual scaling logic resides in skills/watch/scripts/frames.py within the _scale_filter function:

def _scale_filter(resolution: int) -> str:
    return f"scale=w='min({resolution},iw)':h='min({MAX_READ_DIMENSION},ih)'"

Here, MAX_READ_DIMENSION is hardcoded to 1998, ensuring the height never exceeds this limit regardless of the width setting.

Methods to Customize Frame Resolution

You can adjust the frame resolution through three approaches depending on your integration needs.

Using the Command-Line Interface

The simplest method is passing the --resolution flag when invoking the watch command:

# Default 512px width

watch https://youtu.be/example_video

# Custom 1024px width

watch https://youtu.be/example_video --resolution 1024

The tool outputs a confirmation showing the applied limits:

- **Frame size:** max 1024px wide, max 1998px tall

Using the Python API Directly

For programmatic access, import the extraction functions from skills/watch.scripts.frames:

from pathlib import Path
from skills.watch.scripts.frames import extract

video_path = "path/to/video.mp4"
out_dir = Path("frames_out")

frames = extract(
    video_path,
    out_dir,
    fps=1.0,
    resolution=800,  # Custom width of 800px

    max_frames=50,
)

All extraction functions—including extract_keyframes, extract_at_timestamps, and extract_scene_or_uniform—accept the resolution parameter and forward it to _scale_filter.

Modifying the Default Globally

To change the default resolution across all invocations, edit the argument definition in skills/watch/scripts/watch.py:

# Change default from 512 to 1024

ap.add_argument("--resolution", type=int, default=1024,
                help="Frame width in pixels (default 1024)")

After modification, running watch without the --resolution flag uses your new default.

Technical Implementation Details

The resolution value propagates through every frame extraction pathway in Claude-Video. When you call extract, extract_keyframes, or any other extraction routine, the resolution parameter builds an FFmpeg command that applies the scaling filter before writing JPEG files.

The _scale_filter constructs a filter string using min({resolution},iw), which ensures the output width never exceeds your specified resolution or the source width, whichever is smaller. This preprocessing occurs during extraction, eliminating the need for post-processing.

Summary

• Primary control: Use --resolution CLI flag or resolution parameter in Python functions
• Default value: 512 pixels maximum width
• Height limit: Hardcoded to 1998 pixels via MAX_READ_DIMENSION in frames.py
• Implementation: FFmpeg scale filter applied during frame extraction in skills/watch/scripts/frames.py
• Scope: Affects all extraction methods including keyframes, scene-aware, and uniform sampling

Frequently Asked Questions

What is the default frame resolution in Claude-Video?

The default frame resolution is 512 pixels width, as defined in skills/watch/scripts/watch.py. If you do not specify the --resolution flag or resolution parameter, extracted JPEG frames will be scaled to a maximum width of 512 pixels while preserving aspect ratio.

Why is there a maximum height limit of 1998 pixels?

The MAX_READ_DIMENSION = 1998 constant in skills/watch/scripts/frames.py serves as a safeguard to prevent excessive memory usage and ensure compatibility with downstream analysis components. This limit applies regardless of the width you specify via --resolution.

Can I set a specific height instead of width?

No, the current implementation only supports setting the maximum width via the --resolution parameter. The height is automatically calculated to preserve the original aspect ratio, capped at 1998 pixels. To customize height behavior, you would need to modify the _scale_filter function in skills/watch/scripts/frames.py.

Does changing resolution affect video processing speed?

Yes, higher resolutions generally increase processing time and storage requirements because FFmpeg must handle larger pixel data, and subsequent analysis processes larger JPEG files. Conversely, reducing the resolution below the default 512px can improve performance when high detail is unnecessary.

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