How to Control Frame Resolution Using the `--resolution` Flag in Claude-Video

Use the --resolution command-line flag in Claude-Video to set the output frame width in pixels, directly balancing visual detail against Anthropic API token consumption.

Claude-Video is an open-source video processing tool designed for frame extraction and analysis with Claude. You can control the output quality and token costs using the --resolution flag, which adjusts the frame width before images are sent to the API.

Where the --resolution Flag is Defined

The argument is defined in the main entry point at skills/watch/scripts/watch.py (lines 30-33). The parser accepts an integer value representing the desired width in pixels, defaulting to 512:

parser.add_argument(
    '--resolution',
    type=int,
    default=512,
    help='Width of extracted frames in pixels'
)

How Resolution Propagates to Frame Extraction

When you execute the watch command, the resolution value flows through the codebase in three stages:

1. Capture: watch.py reads the value from args.resolution
2. Propagation: The value passes to frame extraction helpers including extract_at_timestamps and extract
3. Execution: These helpers invoke the FFmpeg command in skills/watch/scripts/frames.py (lines 98-104), where the resolution parameter constrains the output width while maintaining the video's aspect ratio

Understanding Token Cost Implications

The --resolution setting directly impacts your Anthropic API token usage. The cost calculation follows the formula: (width × height) / 750.

• Default (512px): Produces frames approximately 512 × 288 pixels, costing roughly 197 tokens per frame
• High (1024px): Doubles the width and roughly quadruples the token cost per frame due to the area increase
• Low (256px): Reduces token consumption significantly for faster, cheaper processing

Practical Usage Examples

Use the default 512px for most video analysis tasks:

watch https://example.com/video.mp4

Increase to 1024px when you need to read on-screen text or small details:

watch https://example.com/video.mp4 --resolution 1024

Reduce to 256px to minimize token usage for high-framerate extraction:

watch https://example.com/video.mp4 --resolution 256

Direct Module Invocation

You can also invoke the frames module directly with the same flag:

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

Summary

• The --resolution flag in watch.py defaults to 512 pixels and accepts any positive integer
• The value propagates through extract_at_timestamps and extract helpers to the FFmpeg command in frames.py
• Token costs scale quadratically with resolution following the (width × height) / 750 formula
• Use 1024px for detailed text, 512px for general analysis, and 256px for token-sensitive workflows

Frequently Asked Questions

What is the default resolution in Claude-Video?

The default resolution is 512 pixels width, which produces frames approximately 512 × 288 pixels and costs roughly 197 tokens per frame according to the Anthropic pricing formula documented in the repository's README.

How does changing the resolution affect API costs?

Token costs scale with pixel area following the formula (width × height) / 750. Doubling the resolution from 512px to 1024px quadruples the token cost per frame, not doubles it, because both width and height increase proportionally while maintaining aspect ratio.

Can I use the --resolution flag when calling frames.py directly?

Yes. When invoking the frame extraction module directly with python -m skills.watch.scripts.frames, you can pass --resolution followed by the desired width in pixels, along with other parameters like --fps and --timestamps.

Where is the --resolution flag defined in the source code?

The flag is defined in skills/watch/scripts/watch.py (lines 30-33) as an integer argument with a 512px default, and it is consumed in skills/watch/scripts/frames.py (lines 98-104) to configure the FFmpeg output width via the scale filter.

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