How Frame Resolution Scaling Works in Claude Video: The --resolution Parameter Explained

The --resolution parameter in Claude Video sets the maximum width of extracted frames while automatically preserving the aspect ratio and ensuring dimensions are divisible by two, preventing upscaling beyond the source resolution.

The bradautomates/claude-video repository provides intelligent video analysis capabilities through frame extraction and processing. Understanding how frame resolution scaling works is essential for optimizing storage, processing speed, and API costs when working with video content. This guide examines the internal mechanics of the --resolution flag as implemented in the project's frame extraction pipeline.

The Resolution Scaling Pipeline

In skills/watch/scripts/frames.py, the --resolution value flows through a dedicated helper function that constructs an ffmpeg video filter. The entry point in skills/watch/scripts/watch.py parses this CLI argument and passes it unchanged to the extraction functions, ensuring consistent behavior across all processing modes.

The _scale_filter Function

The core logic resides in the _scale_filter helper function defined at line 42 of skills/watch/scripts/frames.py. This function generates an ffmpeg scale filter string that balances user requirements with technical constraints:

scale=w='min(<resolution>,iw)':h='min(1998,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2

This filter is injected into the -vf (video filter) chain for every extraction routine, including extract, extract_scene_candidates, extract_keyframes, and extract_at_timestamps.

Resolution Constraints and Safeguards

The scaling implementation enforces three critical constraints to ensure compatibility and quality.

Maximum Width Protection

The filter expression w='min(<resolution>,iw)' prevents upscaling by selecting the smaller value between the user-requested resolution and the input video's native width (iw). If you specify --resolution 1024 on a 640×480 video, the output remains 640 pixels wide.

Height Ceiling and Aspect Ratio

The height parameter h='min(1998,ih)' references a hard-coded maximum dimension constant (MAX_READ_DIMENSION = 1998) while preserving the original aspect ratio through the force_original_aspect_ratio=decrease flag. This ensures the frame never exceeds safe processing dimensions regardless of input size.

Codec Compatibility

The force_divisible_by=2 parameter guarantees both dimensions are even numbers, satisfying requirements for JPEG encoding and H.264/H.265 codecs that demand divisible-by-2 dimensions for macro block alignment.

Practical Usage Examples

Apply the --resolution parameter through the main CLI interface or directly via the frames module.

Standard CLI Usage

Extract frames with a maximum width of 720 pixels:

watch <video-url-or-path> --resolution 720

Request a specific 300-pixel width (will not upscale smaller sources):

watch <video-url-or-path> --resolution 300

Direct Module Invocation

For scripting or advanced workflows, invoke the frames module directly:

python -m skills.watch.scripts.frames \
    path/to/video.mp4 out_dir \
    --resolution 1024

Both approaches generate an ffmpeg command incorporating the scale filter:

-vf "fps=2.0,scale=w='min(720,iw)':h='min(1998,ih)':force_original_aspect_ratio=decrease:force_divisible_by=2"

Summary

• The --resolution parameter controls maximum frame width while preserving aspect ratio through the _scale_filter function in skills/watch/scripts/frames.py.
• The system prevents upscaling by comparing the requested resolution against the input width (iw) and caps height at 1998 pixels.
• All extraction methods—extract, extract_scene_candidates, extract_keyframes, and extract_at_timestamps—utilize identical scaling logic.
• Output dimensions are always forced to even numbers (force_divisible_by=2) to maintain codec compatibility.
• The default resolution value is 512 pixels when the parameter is omitted.

Frequently Asked Questions

What is the default resolution if I don't specify --resolution?

The CLI parser in skills/watch/scripts/frames.py defaults to 512 pixels when the --resolution flag is omitted. This default applies uniformly across all frame extraction routines including uniform sampling and scene-based extraction.

Does --resolution upscale videos to the specified width?

No. The filter expression w='min(<resolution>,iw)' explicitly prevents upscaling by selecting the smaller value between your requested resolution and the input video's native width. If the source video is 640 pixels wide and you request --resolution 1920, the output frames will remain 640 pixels wide.

Why are frame dimensions forced to be divisible by 2?

The force_divisible_by=2 parameter ensures compatibility with downstream codecs and image formats. Many video codecs (including H.264 and H.265) require even dimensions for macro block processing, and JPEG encoding performs optimally with divisible-by-2 dimensions. This constraint prevents encoding errors during frame extraction.

Which extraction methods support the --resolution parameter?

All major extraction functions in skills/watch/scripts/frames.py support the parameter: extract (uniform sampling), extract_scene_candidates (scene change detection), extract_keyframes (keyframe extraction), and extract_at_timestamps (cue-based extraction). The _scale_filter helper ensures consistent resolution handling across every extraction mode.

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