How to Set Frame Resolution for Text-Heavy Content in Claude Video

Use the --resolution flag with the /watch command to increase frame width from the default 512px up to 1800px, which automatically scales height proportionally up to a 1998px limit for sharper text rendering in slides and code demos.

When processing videos with dense on-screen text, the bradautomates/claude-video repository provides a configurable resolution parameter that controls the pixel density of extracted frames. This setting directly impacts readability for programming tutorials, presentation decks, and subtitled media while balancing token consumption.

Using the --resolution CLI Flag

The watch entry point exposes the --resolution argument to specify the target width for extracted frames in pixels.

• Default value: 512px
• Location: Defined in skills/watch/scripts/watch.py at lines 32-33
• Accepted range: Any positive integer, though values above 1800px typically hit the internal height ceiling

When you invoke the /watch command without this flag, the system exports frames at 512 pixels wide. For text-heavy content, increase this value to capture finer details in fonts and UI elements.

How the Scaling Algorithm Works

Inside skills/watch/scripts/frames.py, the _scale_filter(resolution) function constructs an ffmpeg scale filter that preserves aspect ratio while enforcing dimensional constraints.

The filter string generated at lines 42-46 follows this pattern:

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

Where N represents your specified resolution. This command instructs ffmpeg to:

• Limit width to the smaller of your requested resolution or the source width (iw)
• Cap height at 1998px (the MAX_READ_DIMENSION constant defined at lines 30-31)
• Preserve original aspect ratio using force_original_aspect_ratio=decrease
• Ensure dimensions are divisible by 2 for codec compatibility

The scaled frames export as JPEG images with quality level 4 (-q:v 4) before being embedded in the markdown report Claude processes.

Recommended Resolutions by Content Type

Different video formats require different pixel densities to maintain text clarity without excessive token usage.

• 512px (default): Optimal for spoken-word interviews or vlogs with minimal on-screen text. Processes quickly with lower token costs.
• 1024px to 1536px: Ideal for slide decks, code demonstrations, and videos with dense subtitles. Text remains legible without excessive file size.
• 1800px+: Reserved for 4K source material where you need maximum clarity. The system automatically constrains height to 1998px, so width scales proportionally based on the source aspect ratio.

Command Examples

Run the /watch command from your terminal to extract frames at custom resolutions.

Default 512px width for general content:

claude-video watch "https://youtu.be/abc123"

Increase to 1024px for slide-heavy presentations:

claude-video watch "https://youtu.be/abc123" --resolution 1024

Maximum quality for 4K sources (height automatically capped at 1998px):

claude-video watch "https://youtu.be/abc123" --resolution 1800

For programmatic integration, invoke the watch module via Python subprocess:

import subprocess

subprocess.run([
    "python", "-m", "skills.watch.scripts.watch",
    "https://youtu.be/abc123",
    "--resolution", "1024"
])

This calls the same extraction functions (extract_at_timestamps, extract_keyframes) used by the CLI, passing your resolution value through to the ffmpeg pipeline.

Summary

• The --resolution flag in /watch controls frame width, defaulting to 512px in skills/watch/scripts/watch.py
• The _scale_filter() function in skills/watch/scripts/frames.py generates ffmpeg commands that preserve aspect ratio and cap height at 1998px
• Text-heavy content benefits from 1024px–1536px widths, while 1800px+ suits 4K sources
• All scaled frames output as JPEGs and render in the final markdown report

Frequently Asked Questions

What is the maximum frame resolution supported?

Claude Video enforces a maximum height of 1998px via the MAX_READ_DIMENSION constant in skills/watch/scripts/frames.py. While you can specify any width value, ffmpeg automatically scales the output to fit within this height constraint while maintaining the aspect ratio, effectively creating a practical ceiling around 1800px width for standard 16:9 content.

Does increasing the resolution affect token costs?

Yes. Higher resolutions produce larger JPEG files with more visual detail, which increases the token count when Claude processes the generated markdown report. The default 512px setting optimizes for token efficiency, while 1024px or 1536px settings trade higher token usage for improved text legibility in dense content.

How does Claude Video preserve aspect ratio during scaling?

The ffmpeg filter generated by _scale_filter() includes force_original_aspect_ratio=decrease, which ensures the output dimensions never exceed the source aspect ratio. If your requested width would require a height greater than 1998px, ffmpeg automatically reduces the width proportionally to maintain the original video's proportions.

Where is the resolution parameter defined in the source code?

The CLI argument is defined at lines 32-33 of skills/watch/scripts/watch.py using the argparse library. This value propagates to frame extraction functions like extract_at_timestamps and extract_keyframes, ultimately reaching the _scale_filter() implementation at lines 42-46 of skills/watch/scripts/frames.py where the ffmpeg command is constructed.

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