# Claude-Video Watch Command-Line Arguments: Complete CLI Reference

> Explore the claude-video watch command line arguments. Learn about flags like --detail, --max-frames, and --whisper to customize frame extraction and transcription for your video analysis tasks.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: api-reference
- Published: 2026-07-15

---

**The `claude-video` watch tool accepts a positional video source followed by thirteen optional flags—including `--detail`, `--max-frames`, `--resolution`, `--start`, `--end`, and `--whisper`—to control frame extraction strategies, time ranges, transcription backends, and output behavior.**

The `bradautomates/claude-video` repository provides a video analysis pipeline that converts visual content into LLM-ready context through its `watch` entry point. Located at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 30–64), the CLI uses Python's `argparse` module to orchestrate downloading, frame extraction, and transcription workflows. Understanding these command-line arguments allows you to optimize token usage, control processing costs, and extract precisely the visual information needed for your analysis.

## Core Positional Argument

The only required input is the video source itself.

- **`source`** (positional `str`): The video URL (e.g., YouTube) or local file path to process. This argument has no default and must be provided as the first parameter after the script name.

## Frame Extraction Options

Control how the tool samples visual information from the video file.

- **`--max-frames`** (`int`, default: `None`): Manually caps the number of frames extracted from the video. When omitted, the tool falls back to a detail-specific cap defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).
- **`--resolution`** (`int`, default: `512`): Sets the desired frame width in pixels; height scales proportionally up to a maximum of 1998 pixels tall.
- **`--fps`** (`float`, default: `None`): Overrides the automatically calculated frame-rate. The actual applied rate is capped at the internal `MAX_FPS` constant defined in the frame extraction logic.
- **`--detail`** (`transcript`, `efficient`, `balanced`, `token-burner`, or `None`, default: `None`): Determines the extraction strategy and frame budget. Each mode implements different sampling algorithms in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py):
  - **`transcript`**: Optimizes for speech content over visual density.
  - **`efficient`**: Minimizes token usage with conservative frame sampling.
  - **`balanced`**: Moderate frame sampling for standard analysis.
  - **`token-burner`**: Aggressive sampling for maximum visual detail.
- **`--no-dedup`** (flag): Disables near-duplicate frame removal. By default, the pipeline in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) filters visually identical frames to reduce redundancy; this flag preserves all extracted frames.

## Time Range and Timestamp Controls

Process only specific segments or force frames at exact moments.

- **`--start`** (`str`, default: `None`): Beginning of a time range, accepting formats `SS`, `MM:SS`, or `HH:MM:SS`.
- **`--end`** (`str`, default: `None`): End of a time range using the same format as `--start`.
- **`--timestamps`** (`str`, default: `None`): Comma-separated absolute timestamps (e.g., `30,01:15,00:02:45`) that force frame extraction at specific moments, operating in addition to frames chosen by the selected `--detail` strategy.

## Transcription Backend Options

Configure how the tool handles audio transcription when video captions are unavailable.

- **`--no-whisper`** (flag): Skips the Whisper transcription fallback entirely. When enabled, the tool reports only frames and any existing captions, bypassing the logic in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py).
- **`--whisper`** (`groq`, `openai`, or `None`, default: `None`): Forces a specific Whisper backend API. If omitted, the system defaults to Groq with OpenAI as a fallback. This setting reads API keys from `~/.config/watch/.env` as configured in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py).

## Output and Processing Flags

Manage file system operations and temporary storage.

- **`--out-dir`** (`str`, default: `None`): Directory where downloads, extracted frames, and interim files are written. If not specified, the tool uses a temporary directory that is cleaned up after execution.

## Practical Usage Examples

The following commands demonstrate common workflows using the [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) argument structure.

Process a YouTube video with balanced frame sampling and 720px width:

```bash
python -m skills.watch.scripts.watch \
    https://www.youtube.com/watch?v=example \
    --detail balanced \
    --resolution 720

```

Limit extraction to 30 frames and force a specific timestamp at 00:45:

```bash
python -m skills.watch.scripts.watch \
    https://www.youtube.com/watch?v=example \
    --max-frames 30 \
    --timestamps 00:45

```

Extract only a 10-second clip without transcription:

```bash
python -m skills.watch.scripts.watch \
    https://www.youtube.com/watch?v=example \
    --start 00:30 \
    --end 00:40 \
    --no-whisper

```

Force OpenAI Whisper backend for a local video file (requires API key in `~/.config/watch/.env`):

```bash
python -m skills.watch.scripts.watch \
    video.mp4 \
    --whisper openai

```

## Key Implementation Files

These source files define and consume the command-line arguments:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)**: Main CLI entry point that constructs the `ArgumentParser` (lines 30–64) and validates inputs before dispatching to helper modules.
- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)**: Supplies default configuration values (including the default `detail` preset) and manages environment variable loading from `~/.config/watch/.env`.
- **[`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py)**: Handles video and caption acquisition via `yt-dlp`, respecting `--out-dir` and time range constraints.
- **[`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)**: Implements frame extraction strategies (`keyframes`, `scene-aware`) and deduplication logic controlled by `--detail`, `--resolution`, and `--no-dedup`.
- **[`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)**: Wraps the Groq and OpenAI Whisper API backends selected via `--whisper` or bypassed via `--no-whisper`.

## Summary

- The `claude-video` watch tool requires only a `source` argument but exposes thirteen optional flags for granular control.
- **Frame extraction** is managed through `--detail`, `--max-frames`, `--resolution`, `--fps`, and `--no-dedup`, with implementation details in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py).
- **Time targeting** uses `--start`, `--end`, and `--timestamps` to limit processing to relevant video segments.
- **Transcription** defaults to Groq → OpenAI fallback unless overridden by `--whisper` or disabled with `--no-whisper`.
- **Output** location is controlled via `--out-dir`; otherwise temporary storage is used.
- All arguments are parsed in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) and consumed across the [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py), [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), and [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) pipeline.

## Frequently Asked Questions

### What is the default frame extraction strategy if I don't specify `--detail`?

If you omit the `--detail` flag, the tool defaults to `None` and falls back to values defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). The [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) file typically sets `efficient` as the default strategy when no detail level is explicitly requested, minimizing token usage while maintaining useful visual coverage.

### Can I combine `--timestamps` with `--start` and `--end` time ranges?

Yes. The `--timestamps` argument operates independently of `--start` and `--end`. When you specify a time range with `--start` and `--end`, the tool limits processing to that segment, while `--timestamps` forces additional frame grabs at absolute positions you specify (formatted as `SS`, `MM:SS`, or `HH:MM:SS`), even if those timestamps fall outside the standard sampling grid for your chosen `--detail` level.

### How does the `--max-frames` cap interact with the `--detail` preset?

The `--max-frames` value acts as a hard ceiling that overrides any detail-specific frame budgets defined in [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py). For example, if you select `--detail token-burner` (which typically extracts many frames) but set `--max-frames 10`, the extraction logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) will stop after capturing ten frames, regardless of the detail strategy's default behavior.

### Where does the tool store downloaded videos and extracted frames by default?

Without the `--out-dir` argument, the tool uses Python's temporary directory mechanisms to store downloads and frame images, cleaning up files after execution. Specifying `--out-dir /path/to/folder` persists all intermediate files—including raw videos, extracted frames, and transcription text—to that location for debugging or reuse.