How to Configure Custom Frame Resolution with `--resolution` in Claude-Video

Use the --resolution flag in Claude-Video’s /watch skill to override the default 512-pixel frame width, allowing you to extract higher-detail JPEG frames from videos while preserving aspect ratio.

Claude-Video’s watch skill extracts JPEG frames from video sources using ffmpeg for analysis by Claude. By default, frames are scaled to 512 pixels wide (with height auto-scaled to a maximum of 1998 pixels) to balance visual detail against token consumption. When you configure custom frame resolution with --resolution, you override this default to capture finer visual details such as on-screen text, code snippets, or presentation slides.

How the --resolution Flag Works

The resolution parameter flows through three core components before reaching the ffmpeg execution layer.

In skills/watch/scripts/config.py, the CLI argument parser captures the --resolution value and stores it in the Config.resolution attribute. This value is then forwarded through skills/watch/scripts/watch.py (the main orchestration module) to the frames.extract_frames() function in skills/watch/scripts/frames.py.

Inside frames.py, the resolution value is injected into an ffmpeg filter string using the scale video filter:

ffmpeg -i INPUT -vf "scale=W:-2" -qscale:v 2 FRAME_%05d.jpg

Here, W represents the integer value passed to --resolution (e.g., 1024), while -2 instructs ffmpeg to automatically calculate the height that preserves the original aspect ratio. The generated frames are subsequently listed with timestamps (e.g., t=00:01:23) and fed to Claude via the Read tool.

Using the --resolution Flag

Basic Usage with Default Resolution

If you omit the flag, the system defaults to 512 pixels wide:

/watch https://youtu.be/dQw4w9WgXcQ "What does the presenter say at 45 seconds?"

Increasing Resolution for Text-Heavy Content

For videos containing small fonts, code, or detailed slides, increase the width to 1024 pixels or higher:

/watch https://youtu.be/dQw4w9WgXcQ "Summarize the slide content" --resolution 1024

Combining with Other Options

The --resolution flag integrates seamlessly with time range and frame rate controls:

/watch video.mp4 \
  --start 1:15 --end 1:45 \
  --detail balanced \
  --resolution 1024 \
  --fps 3

Python API Usage

Developers can invoke the resolution setting programmatically via the run_watch function:

from skills.watch.scripts.watch import run_watch

run_watch(
    source="https://youtu.be/dQw4w9WgXcQ",
    query="Explain the key point at 30 seconds",
    resolution=1024,          # Custom width override

    detail="balanced",
)

Technical Implementation Details

The skill contract in skills/watch/SKILL.md declares the --resolution option, ensuring compatibility across Claude Code, Codex, and other hosts. The actual implementation spans three critical source files:

• skills/watch/scripts/config.py: Parses CLI arguments and validates the resolution value, making it available as Config.resolution throughout the pipeline.
• skills/watch/scripts/watch.py: Acts as the entry point and coordinator, passing the resolution parameter to the frame extraction layer.
• skills/watch/scripts/frames.py: Constructs the final ffmpeg command, applying the scale=W:-2 filter where W equals the configured resolution.

Performance and Token Cost Considerations

Each pixel in a JPEG frame consumes approximately 4 image tokens when processed by Claude. While higher resolutions improve OCR accuracy and detail recognition, they proportionally increase your token budget usage.

The default 512-pixel width optimizes for general video comprehension while staying within typical context window limits. Reserve resolutions above 1024 pixels for scenarios requiring precise text extraction or analysis of dense visual information, as documented in the repository’s README token-cost table.

Summary

• The --resolution flag overrides the default 512-pixel frame width in Claude-Video’s /watch skill.
• Resolution values flow from config.py through watch.py to frames.py, where they generate an ffmpeg scale=W:-2 filter.
• Higher resolutions preserve aspect ratio automatically but increase image token consumption by roughly 4 tokens per pixel.
• Use resolutions above 1024 pixels specifically for text-heavy content, code demonstrations, or detailed slides.

Frequently Asked Questions

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

If you omit the flag, Claude-Video defaults to 512 pixels wide, automatically calculating the height to preserve the video’s original aspect ratio while capping the maximum height at 1998 pixels. This default balances sufficient visual detail with reasonable token consumption.

How does the --resolution flag affect the ffmpeg command?

The flag modifies the video filter chain in skills/watch/scripts/frames.py, specifically inserting your custom width into the scale=W:-2 parameter. The -2 value ensures ffmpeg computes a height that maintains the aspect ratio using even numbers, which is required for JPEG compatibility.

Will increasing the resolution help Claude read small text in videos?

Yes. Increasing the resolution to 1024 or higher significantly improves Claude’s ability to recognize small fonts, code syntax, and presentation slides. However, each resolution doubling quadruples the pixel count (and thus token cost), so use higher resolutions selectively for text-critical segments rather than entire videos.

Can I use the --resolution flag with local video files as well as URLs?

Absolutely. The --resolution flag works identically for both local file paths and remote URLs, as the frame extraction pipeline in skills/watch/scripts/frames.py processes both input types through the same ffmpeg scaling logic after the source is validated.

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