# How to Use the --start and --end Flags in Claude-Video for Focused Frame Extraction

> Effortlessly extract specific video frames with Claude-Video's --start and --end flags. Focus your analysis on precise time windows for efficient frame extraction and transcript filtering.

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

---

**Pass `--start` and `--end` to the [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script to activate focus mode, which extracts frames at a denser rate (up to 2 fps) from a specific time window while filtering transcripts to match.**

Claude-Video, the open-source video analysis toolkit from `bradautomates/claude-video`, provides precise temporal control through its `--start` and `--end` command-line flags. These flags enable **focus mode**, allowing you to extract high-density frames from specific segments rather than processing the entire video. Understanding how to use the `--start` and `--end` flags in claude-video for focused frame extraction ensures you get detailed visual analysis exactly where you need it.

## Understanding Focus Mode in Claude-Video

When you provide either `--start` or `--end` to [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the script switches from full-video scanning to focus mode. In this mode, the system concentrates its frame extraction budget on your specified window rather than distributing frames across the entire duration.

The focus mode logic resides in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which orchestrates the entire pipeline including argument parsing, validation, and user feedback.

### Timestamp Filtering for Transcripts

Focus mode also affects transcription handling. According to [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), any transcript cue falling outside the `[start, end]` window is automatically dropped (lines 218-220), while remaining timestamps are reported as absolute source times.

## Supported Time Formats and Validation

The `--start` and `--end` flags accept flexible human-readable time formats validated by the main orchestrator.

### Time Format Options

As implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 49-52), the flags accept string values in three formats:
- **`SS`** – Seconds only (e.g., `50`)
- **`MM:SS`** – Minutes and seconds (e.g., `2:15`)
- **`HH:MM:SS`** – Hours, minutes, and seconds (e.g., `1:12:00`)

### Validation Rules

The script enforces strict temporal boundaries at lines 144-148 of [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py):
- **Start time** must be greater than or equal to 0
- **End time** must be strictly greater than the start time
- **Start time** cannot exceed the total video duration

## Frame Budget Adjustments in Focus Mode

Focus mode automatically increases frame density while maintaining overall caps. According to [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md) (lines 156-162), the per-second frame budget becomes denser (up to 2 fps) when these flags are present, though it still respects the overall mode caps: approximately 100 frames for balanced mode and 50 for efficient mode.

This means a 30-second clip extracted with `--start` and `--end` receives significantly more frames per second than the same duration would receive in a full-video scan.

## How to Extract Frames from a Specific Time Range

Here are practical examples for both local files and remote URLs using the [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point.

Extract frames from a local video file between 50 and 60 seconds:

```bash
python3 "${SKILL_DIR}/skills/watch/scripts/watch.py" video.mp4 --start 50 --end 60

```

Zoom into a specific range of a YouTube video with custom FPS:

```bash
python3 "${SKILL_DIR}/skills/watch/scripts/watch.py" "$URL" --start 2:15 --end 2:45 --fps 2

```

Extract everything from a specific time onward (omitting `--end`):

```bash
python3 "${SKILL_DIR}/skills/watch/scripts/watch.py" "$URL" --start 1:12:00

```

In slash-command environments (Claude Code, Codex, or Cursor), pass the flags after the URL or file path:

```

/watch https://youtu.be/abc --start 2:15 --end 2:45
/watch video.mp4 --start 50 --end 60

```

## Technical Implementation Details

The frame extraction logic in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (lines 689-713) receives the `--start` and `--end` arguments directly, computing the frame-extraction schedule to ensure extracted images correspond exactly to the requested segment.

If you attempt to process a long video without these flags, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 332-335) detects when a full-video scan would produce sparse results and prints a warning suggesting you re-run with `--start` and `--end` to obtain a richer view.

## Summary

- **Focus mode activation**: Adding `--start` or `--end` to [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) switches from full-video scanning to concentrated segment analysis
- **Flexible time syntax**: Accepts seconds (`50`), minutes:seconds (`2:15`), or hours:minutes:seconds (`1:12:00`) formats
- **Denser extraction**: Up to 2 fps budget allocation within the specified window compared to sparse full-video distribution
- **Transcript filtering**: Automatically excludes cues outside the time window while preserving absolute timestamps
- **Validation enforcement**: [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) ensures start ≥ 0, end > start, and start does not exceed video duration

## Frequently Asked Questions

### What time formats does claude-video accept?

Claude-Video accepts three time formats in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py): raw seconds (`50`), minutes and seconds (`2:15`), and full hours-minutes-seconds notation (`1:12:00`). The argument parser at lines 49-52 converts these to seconds internally for processing.

### How does focus mode affect frame extraction quality?

Focus mode increases the per-second frame budget to up to 2 fps according to [`SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/SKILL.md), while maintaining the total frame caps (balanced ~100, efficient ~50). This produces denser visual coverage of your specific segment compared to the sparse distribution used for full-video scans.

### Can I use --start without --end?

Yes. You can specify only `--start` to extract from that timestamp to the end of the video. The validation logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) requires that when both are present, the end time must exceed the start time.

### Where is the focus mode logic implemented?

The focus mode logic spans three key files: [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) handles argument parsing and validation, [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) implements the actual frame extraction schedule (lines 689-713), and [`skills/watch/SKILL.md`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/SKILL.md) defines the behavior specifications including budget adjustments and transcript filtering.