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

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 (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.
• --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:
  • 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 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.
• --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.

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 argument structure.

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

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:

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:

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):

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: Main CLI entry point that constructs the ArgumentParser (lines 30–64) and validates inputs before dispatching to helper modules.
• 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: Handles video and caption acquisition via yt-dlp, respecting --out-dir and time range constraints.
• 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: 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.
• 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 and consumed across the download.py, frames.py, and 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. The 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. 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 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.

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