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

> Boost Claude Video text clarity with --resolution. Increase frame width to 1800px for sharper slides & code demos, ensuring optimal readability.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```text
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:

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

```

Increase to 1024px for slide-heavy presentations:

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

```

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

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

```

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

```python
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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)
- The `_scale_filter()` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) where the ffmpeg command is constructed.