How to Customize Frame Resolution Using the `--resolution` Option in Claude Video

Use the --resolution flag to override the default 512‑px width limit when extracting frames from videos in Claude Video, which passes the value directly to FFmpeg's scale filter while maintaining aspect ratio and capping height at 1998 px.

Claude Video (bradautomates/claude-video) extracts JPEG frames from video files using FFmpeg. By default, frames are scaled so the width never exceeds 512 pixels, but you can customize this limit to balance image quality against token usage by using the --resolution command‑line option.

How the --resolution Flag Works

When you invoke the watch command with --resolution, the value is parsed in skills/watch/scripts/watch.py (lines 30‑34) and forwarded through the call chain to every frame‑extraction function. These functions—all residing in skills/watch/scripts/frames.py—include extract(), extract_keyframes(), extract_scene_or_uniform(), and extract_at_timestamps(). Each function passes the resolution parameter to the internal helper _scale_filter(), which constructs an FFmpeg scale= filter string that limits the output width while respecting a hard‑coded height ceiling.

Understanding the Scaling Logic

The actual scaling behavior is defined in the _scale_filter() helper inside skills/watch/scripts/frames.py (lines 42‑46):

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

In this filter:

• w='min({resolution},iw)' sets the output width to the smaller of your specified value or the input video’s original width.
• h='min({MAX_READ_DIMENSION},ih)' caps the height at 1998 px (the MAX_READ_DIMENSION constant defined on line 30 of frames.py).
• force_original_aspect_ratio=decrease ensures the frame scales proportionally.
• force_divisible_by=2 guarantees even pixel dimensions for codec compatibility.

Thus, specifying --resolution 720 produces frames up to 720 px wide (or narrower if the source is smaller) while keeping the height within the 1998 px limit.

Usage Examples

Basic Usage

Run the default 512‑px extraction:

watch https://youtu.be/example-video

High‑Resolution Extraction

Increase the width limit to 720 px for finer detail:

watch https://youtu.be/example-video --resolution 720

Direct Script Execution

For debugging or development, invoke the module directly:

python -m skills.watch.scripts.watch \
    https://youtu.be/example-video \
    --resolution 720 \
    --out-dir ./my-output

Implementation Details in the Source Code

Argument Parsing in watch.py

The CLI entry point in skills/watch/scripts/watch.py defines the optional argument on lines 30‑34 and forwards it to the extraction pipeline. Any integer value supplied here propagates unchanged to the underlying frame functions.

Frame Scaling in frames.py

The skills/watch/scripts/frames.py module implements the scaling constraint. In addition to _scale_filter(), it defines MAX_READ_DIMENSION = 1998 to prevent excessively tall images. Every extraction variant—uniform sampling, keyframe extraction, scene‑aware selection, and timestamp‑based extraction through extract(), extract_keyframes(), extract_scene_or_uniform(), and extract_at_timestamps()—honors this resolution parameter, ensuring consistent output dimensions across all generated JPEGs.

Summary

• The default frame width in Claude Video is 512 px, controlled by the resolution parameter in frames.extract().
• Override the default by passing --resolution N to the watch command.
• The scaling logic in _scale_filter() uses FFmpeg’s scale filter with min() constraints to respect both your width limit and the 1998‑px height ceiling.
• Aspect ratio is preserved via force_original_aspect_ratio=decrease, and dimensions are forced to even numbers for codec compatibility.
• All extraction modes (uniform, keyframes, scene‑aware, timestamps) respect the same resolution setting.

Frequently Asked Questions

What is the maximum resolution I can specify?

While you can pass any integer to --resolution, the implementation caps the height at 1998 px via the MAX_READ_DIMENSION constant in skills/watch/scripts/frames.py. The width will not exceed your specified value or the source video’s width, whichever is smaller.

Does changing the resolution affect aspect ratio?

No. The _scale_filter() function includes force_original_aspect_ratio=decrease, which ensures frames scale proportionally. Your video’s original aspect ratio is preserved while fitting within the width and height constraints.

Which extraction modes support custom resolution?

All modes support it. The resolution parameter is accepted by extract(), extract_keyframes(), extract_scene_or_uniform(), and extract_at_timestamps() in skills/watch/scripts/frames.py, and the watch.py entry point passes the CLI value to each of these functions uniformly.

Why is the default resolution set to 512 px?

The default value of 512 balances image clarity with token consumption and storage efficiency when processing video frames through LLM vision APIs. You can increase this value for higher fidelity or decrease it to reduce file size and processing time.

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