# How to Run Specific Features of the bradautomates/claude-video Watch Skill

> Discover how to run specific features of the bradautomates/claude-video watch skill. Download videos, extract frames, and generate transcripts using Python script flags.

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

---

**The bradautomates/claude-video repository provides a command-line interface through [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) that allows you to download videos, extract frames at various detail levels, and generate transcripts using specific flags like `--detail`, `--fps`, and `--timestamps`.**

The **claude-video** repository implements the `/watch` skill, a self-contained package designed for Agent-Skills hosts such as Claude Code, Codex, or Cursor. This guide explains how to run specific features of the watch skill using the command-line entry point and its various configuration options.

## Understanding the Watch Skill Architecture

The watch skill is deliberately host-agnostic, resolving all paths relative to `SKILL_DIR` as defined in [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md). The architecture centers on [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) as the primary orchestrator, which coordinates four specialized modules: [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) handles video retrieval via `yt-dlp`, [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) manages frame extraction algorithms, [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) provides speech-to-text fallback, and [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py) stores default parameters like frame caps for each detail level.

This modular design allows you to invoke specific features—whether extracting keyframes, processing custom timestamps, or generating transcripts—without requiring host-specific environment variables.

## Running the Watch Script Entry Point

All features are accessed through the main entry point at [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py). The script accepts a video URL or local file path as the primary argument, followed by optional flags that control frame extraction, transcription, and output formatting.

The basic invocation syntax follows this pattern:

```bash
python -m skills.watch.scripts.watch "<video_url_or_path>" [OPTIONS]

```

Upon completion, the script prints a Markdown report to `stdout` and outputs extracted frames to a temporary directory (or a user-specified `--out-dir`), referencing paths like `/tmp/watch-abc123/frames`.

## Configuring Frame Extraction Detail Levels

The `--detail` flag controls the frame extraction strategy by selecting specific algorithms implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). Each mode balances token consumption against visual coverage.

### Efficient Mode (Keyframe Extraction)

**Efficient mode** uses `extract_keyframes` to select only visually distinct keyframes, minimizing token usage while preserving scene changes. This mode is ideal for long videos where you need representative coverage without excessive frame counts.

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --detail efficient

```

The underlying logic calculates target FPS using `auto_fps` based on video length and the frame budget defined in [`config.py`](https://github.com/bradautomates/claude-video/blob/main/config.py).

### Balanced Mode (Scene-Aware Extraction)

**Balanced mode** invokes `extract_scene_or_uniform` to perform scene detection, extracting frames at scene boundaries while maintaining uniform coverage within scenes. This provides richer context than efficient mode without reaching token-burner levels.

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --detail balanced

```

### Transcript-Only Mode

To disable frame extraction entirely and retrieve only captions or transcripts, use **transcript mode**. This skips all frame processing and focuses solely on subtitle download or Whisper transcription.

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --detail transcript

```

## Customizing Frame Selection Parameters

Beyond preset detail levels, the watch skill provides granular control over frame selection through timestamp specification, frame rate overrides, and resolution limits.

### Extracting Frames at Specific Timestamps

Use the `--timestamps` flag to extract frames only at explicit cue points. The `extract_at_timestamps` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) handles the precise seeking and extraction logic.

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" \
    --timestamps "00:10,01:23,02:45"

```

When combined with `--detail transcript`, this retrieves only the specified frames without additional scene-based extraction.

### Adjusting FPS, Resolution, and Frame Caps

Override automatic calculations by specifying explicit parameters:

- **`--fps`**: Set target frames per second (bypasses `auto_fps` calculations)
- **`--resolution`**: Set frame width in pixels (e.g., `720` for 720px width)
- **`--max-frames`**: Hard limit the total frame count regardless of detail level defaults

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" \
    --resolution 720 --fps 2.5 --max-frames 30

```

## Processing Local Files and Video Segments

The watch skill handles both remote URLs and local video files, with options to focus processing on specific time ranges.

### Processing Local Video Files

Pass a local file path instead of a URL. Ensure the file path is absolute or relative to the execution context:

```bash
python -m skills.watch.scripts.watch "/path/to/local_video.mp4"

```

### Focusing on Time Ranges (--start and --end)

Use **`--start`** and **`--end`** flags to process only a sub-range of the video. This is particularly effective when combined with efficient mode for targeted analysis:

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" \
    --start 01:00 --end 03:30 --detail efficient

```

## Configuring Transcription and Whisper Integration

When caption files are unavailable, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) falls back to Whisper transcription via [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py). This module supports both Groq and OpenAI backends.

### Disabling Whisper Fallback

To prevent automatic transcription attempts (useful when API keys are unavailable), use the **`--no-whisper`** flag:

```bash
python -m skills.watch.scripts.watch "https://youtu.be/dQw4w9WgXcQ" --no-whisper

```

### Configuring API Keys

The `load_api_key` function in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) reads API credentials from `~/.config/watch/.env`. Create this file with your preferred provider's key:

```bash

# ~/.config/watch/.env

OPENAI_API_KEY=sk-your-key-here

# or

GROQ_API_KEY=gsk-your-key-here

```

### Selecting Whisper Backends

Force a specific transcription backend using the **`--whisper`** flag. Valid options are `openai` or `groq`:

```bash
python -m skills.watch.scripts.watch "local_video.mp4" --whisper openai

```

The `transcribe_video` function routes the request to the specified endpoint and formats the output for inclusion in the final Markdown report.

## Environment Setup and Configuration

Default behaviors are governed by [`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py), which defines frame caps for each detail level and other constants. You do not need to modify this file to run specific features; instead, use the command-line flags to override defaults at runtime.

The skill requires `yt-dlp` for video downloading (handled automatically by [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py)) and optional Whisper dependencies only if transcription fallback is enabled. All paths resolve relative to the skill directory, ensuring portability across different Agent-Skills hosts.

## Summary

- **Entry point**: Run [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) with a URL or file path to access all features.
- **Detail levels**: Use `--detail efficient` for keyframes, `--detail balanced` for scene-aware extraction, or `--detail transcript` for text-only output.
- **Frame customization**: Control extraction with `--timestamps`, `--fps`, `--resolution`, and `--max-frames` flags.
- **Segment processing**: Focus on specific time ranges using `--start` and `--end` parameters.
- **Transcription control**: Manage Whisper via `--no-whisper`, `--whisper openai`, and API keys in `~/.config/watch/.env`.

## Frequently Asked Questions

### How do I extract frames only at specific moments in the video?

Use the **`--timestamps`** flag followed by comma-separated timestamps in HH:MM:SS or MM:SS format. The `extract_at_timestamps` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) processes these cues and extracts frames only at those specific points, bypassing the automatic FPS calculation.

### What is the difference between efficient and balanced detail modes?

**Efficient mode** uses `extract_keyframes` to grab only visually distinct keyframes using `auto_fps_focus` calculations, minimizing token count. **Balanced mode** uses `extract_scene_or_uniform` to detect scene boundaries and extract frames at transitions while maintaining uniform coverage within scenes, providing more context at higher token cost.

### Where does the watch skill store API keys for transcription?

The `load_api_key` function in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py) looks for a file at `~/.config/watch/.env`. Store your `OPENAI_API_KEY` or `GROQ_API_KEY` in this file; the skill reads these values when you use the `--whisper` flag or when automatic transcription is required.

### Can I process only a portion of a long video without downloading the whole file?

Yes. Use the **`--start`** and **`--end`** flags to specify time ranges. While [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) retrieves the video, the frame extraction logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) respects these boundaries when processing, allowing you to focus analysis on specific segments without manual pre-trimming.