# How Focus Mode with `--start` and `--end` Works in claude-video for Specific Sections

> Learn how claude-video's focus mode uses --start and --end to precisely extract video sections. The watch command validates ranges before ffmpeg isolates frames for efficient analysis.

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

---

**Focus mode in `claude-video` lets you isolate specific video segments by passing `--start` and `--end` time strings to the `watch` command, which validates the range before invoking ffmpeg to extract frames only from that window.**

The `claude-video` repository provides a `watch` skill that downloads videos, extracts frames, and optionally transcribes audio. When working with long videos, processing the entire file is often unnecessary. Focus mode solves this by allowing you to specify exact time ranges using `--start` and `--end` flags, ensuring that only the relevant segment is analyzed.

## Parsing Focus Mode Arguments

The entry-point script [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) defines the focus mode interface at line 49. The CLI accepts two optional parameters:

- `--start` – Accepts a time string in seconds, `MM:SS`, or `HH:MM:SS` format. Defaults to `None`.
- `--end` – Accepts the same time formats to mark the end of the extraction window.

These arguments are processed before any network or disk activity begins, ensuring that malformed inputs trigger immediate feedback.

## Validation Logic

After parsing, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) converts the time strings into seconds and performs three critical validations at lines 144-148:

1. **Non-negative start** – The start time must be ≥ 0. If negative, the script aborts with:
   ```bash
   SystemExit: --start must be non-negative
   ```

2. **End greater than start** – The end time must exceed the start time. If not, the script aborts with:
   ```bash
   SystemExit: --end must be greater than --start
   ```

3. **Start within duration** – The start time cannot exceed the video's total length. If it does, the script aborts with:
   ```bash
   SystemExit: --start {start_sec:.1f}s is past end of video ({full_duration:.1f}s)
   ```

This validation sequence ensures that downstream processes receive only valid, bounded time ranges.

## Frame Extraction Pipeline

Once validated, the `start_sec` and `end_sec` values are forwarded to [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py). This script receives the same `--start` and `--end` flags (documented in its help string at line 689) and passes them directly to **ffmpeg**.

The ffmpeg invocation seeks to the start timestamp and terminates at the end timestamp, effectively limiting frame extraction to the requested slice without processing the entire video file.

## Usage Examples

**Basic focus mode with timestamps**

```bash

# Extract frames only from 1:30 to 2:45 of a YouTube video

watch "https://youtu.be/abcd1234" --start 01:30 --end 02:45

```

**Using plain seconds**

```bash
watch "./local-video.mp4" --start 90 --end 165

```

**Combining with other flags**

```bash
watch "https://vimeo.com/123456" \
  --start 00:00:30 --end 00:01:00 \
  --max-frames 200 \
  --no-dedup \
  --question "What is being shown in this segment?"

```

If you omit `--start` and `--end`, the CLI prints a reminder at line 332 suggesting you re-run with `--start HH:MM:SS --end HH:MM:SS` to zoom into a specific section.

## Error Handling Examples

**Negative start time**

```bash
watch video.mp4 --start -5

# → SystemExit: --start must be non-negative

```

**End before start**

```bash
watch video.mp4 --start 00:02:00 --end 00:01:00

# → SystemExit: --end must be greater than --start

```

**Start beyond video duration**

```bash
watch video.mp4 --start 10:00

# → SystemExit: --start 600.0s is past end of video (300.0s)

```

## Summary

- **Focus mode** uses `--start` and `--end` flags in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) to limit processing to specific video segments.
- **Time formats** supported include seconds, `MM:SS`, and `HH:MM:SS` strings.
- **Validation occurs early** (lines 144-148), checking for non-negative start, end > start, and start within video duration.
- **Frame extraction** is handled by [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) (line 689), which passes the range to ffmpeg for efficient segment processing.
- **Error messages** provide immediate feedback before any network or disk operations begin.

## Frequently Asked Questions

### What time formats does claude-video accept for --start and --end?

`claude-video` accepts three formats: plain seconds (e.g., `90`), minutes:seconds (`01:30`), or hours:minutes:seconds (`00:01:30`). The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script parses these strings and converts them to seconds before validation.

### Why does the validation happen before downloading the video?

The `watch` command retrieves the video's metadata and duration before frame extraction begins. This allows [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) to validate that your `--start` time exists within the video bounds at line 148, preventing wasted bandwidth and processing on invalid ranges.

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

While the argument parser allows omitting either flag, the validation logic requires `--end` to be greater than `--start` if both are provided. If you specify only `--start`, the extraction will begin at that timestamp and continue to the end of the video, depending on how [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) handles the `None` value for end time.

### How does focus mode affect transcription?

Focus mode limits the audio segment sent to transcription models to the same `--start` and `--end` window used for frame extraction. Because [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) handles the ffmpeg invocation that slices the video, both visual frames and audio tracks are constrained to your specified range, ensuring transcription covers only the relevant section.