# How to Process a Specific Video Section Using `--start` and `--end` in Claude Video

> Learn to process specific video sections with Claude Video using --start and --end flags. Optimize frame density and filter transcripts for focused analysis.

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

---

**Use the `--start` and `--end` CLI flags to limit processing to a specific time range, which triggers focused mode—automatically adjusting frame density and filtering transcripts to match only the selected segment.**

The `bradautomates/claude-video` repository provides a powerful Python-based toolkit for video analysis, and its `watch` command supports precise temporal targeting through command-line arguments. When you need to analyze only a portion of a video rather than the entire duration, these flags integrate with the underlying ffmpeg pipeline and transcript filtering logic to optimize both performance and output relevance.

## Understanding the `--start` and `--end` Arguments

The core entry point for this functionality is located in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), which implements the main `watch` CLI script. When invoked, the script builds an `argparse` parser that accepts `--start` and `--end` as optional string arguments. These parameters accept timestamps in **SS**, **MM:SS**, or **HH:MM:SS** format, allowing you to specify exact boundaries for video processing.

Supplying either flag activates **focused mode** (`focused = True`), which fundamentally alters how the system allocates resources. Instead of distributing the frame budget across the entire video duration, the logic switches to `auto_fps_focus` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py), yielding a denser sampling rate specifically for your selected interval.

## Timestamp Formats and Validation

Before processing begins, the `parse_time` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) converts your input strings into float values representing seconds. This function handles all three supported formats and validates that the values are logically consistent.

The validation logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) enforces three critical constraints:
- **Non-negative start**: The `--start` value must be greater than or equal to zero
- **Sequential ordering**: The `--end` timestamp must exceed the `--start` timestamp
- **Duration bounds**: The start time cannot exceed the video's total duration

If any check fails, the script aborts with a descriptive error message before invoking expensive video processing operations.

## How Range Processing Works

When valid timestamps are provided, the system calculates `effective_start` (defaulting to 0 if unspecified) and `effective_end` (defaulting to the full duration if unspecified). These boundaries propagate through the entire processing pipeline.

### Argument Parsing and Validation

In [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), the argument parser captures raw string inputs into `args.start` and `args.end`. The script then invokes validation logic to ensure the temporal range is valid relative to the video's metadata retrieved during the initial probe phase.

### Timestamp Conversion in frames.py

The `parse_time` utility converts formatted strings into seconds for internal calculations. Conversely, `format_time` prepares human-readable representations for the final report output. These conversions ensure that user-facing displays remain readable while internal ffmpeg commands receive precise numeric values.

### Frame Extraction with ffmpeg

The `extract` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) receives `start_seconds` and `end_seconds` as parameters. It constructs an ffmpeg command incorporating `-ss` (seek to start) and `-to` (terminate at end) flags, causing ffmpeg to seek directly to the start timestamp and cease processing at the end boundary. Only frames within the specified window are written to the output directory, significantly reducing I/O overhead for long videos.

### Transcript Filtering

After potential caption download or Whisper transcription, the `filter_range` function in [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) trims the transcript to match the selected window. This function discards any subtitle segments falling outside the specified time boundaries, ensuring that the reported transcript content synchronizes perfectly with the extracted visual frames.

## Focused Mode and Frame Budgeting

When processing a specific range, the system automatically switches from standard auto-fps logic to `auto_fps_focus` (as implemented in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)). This optimization concentrates the available frame budget onto the narrower time window, providing richer visual coverage for critical sections without exceeding overall processing limits.

The final markdown report includes a "Focus range" line when boundaries are applied, displaying the formatted start and end times. Both the frames list and transcript sections reflect only the chosen segment, creating a cohesive analysis package isolated to your region of interest.

## Practical Code Examples

Extract frames from 1 minute 30 seconds to 2 minutes 15 seconds, limiting resolution to 720px:

```bash
python -m skills.watch.scripts.watch \
    "https://www.youtube.com/watch?v=example" \
    --start 01:30 \
    --end 02:15 \
    --resolution 720

```

Process a local video from 45 seconds to 1 minute 10 seconds with transcript generation:

```bash
python -m skills.watch.scripts.watch \
    ./local_video.mp4 \
    --start 00:45 \
    --end 01:10 \
    --detail transcript

```

Combine a custom frame cap with a precise 10-second range:

```bash
python -m skills.watch.scripts.watch \
    "https://vimeo.com/123456" \
    --start 00:00:10 \
    --end 00:00:20 \
    --max-frames 30

```

In each case, the output includes only frames and transcript lines falling inside the specified interval, and internal logs prefixed with `[watch]` display the calculated effective boundaries and adjusted fps values.

## Summary

- Processing specific video sections 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 define temporal boundaries
- Valid formats include **SS**, **MM:SS**, and **HH:MM:SS**, converted to seconds via `parse_time` in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)
- Range validation ensures logical constraints before processing begins
- The `extract` function passes `-ss` and `-to` flags to ffmpeg for efficient segment extraction
- Transcript content is filtered via `filter_range` in [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) to match the selected window
- Focused mode automatically activates `auto_fps_focus`, concentrating frame budgets on the selected segment

## Frequently Asked Questions

### What timestamp formats does Claude Video accept for --start and --end?

Claude Video accepts three timestamp formats: raw seconds (**SS**), minutes and seconds (**MM:SS**), and hours with minutes and seconds (**HH:MM:SS**). The `parse_time` function in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) handles conversion of all three formats to float values representing seconds, which are then passed to ffmpeg and the transcript filtering logic.

### Does using --start and --end download the entire video or just the selected section?

The system downloads the complete video file but processes only the specified section. The ffmpeg `-ss` and `-to` flags seek to the start position and terminate at the end timestamp during frame extraction, while `filter_range` in [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) discards transcript segments outside the range. This approach ensures accurate keyframe extraction while minimizing actual processing overhead.

### What happens if I specify an end time beyond the video's actual duration?

The validation logic in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) prevents processing when the start time exceeds the video duration, but if the end time extends beyond the actual duration, ffmpeg typically processes until the end of the available media. The `effective_end` value defaults to the full duration when unspecified or when validation determines the provided end exceeds available content.

### How does focused mode affect the number of frames extracted?

When `--start` or `--end` is specified, focused mode activates `auto_fps_focus` instead of the standard auto-fps calculator. This function concentrates the frame budget onto the narrower time window, effectively increasing the frame density for the selected segment while maintaining the overall `--max-frames` limit, ensuring richer visual coverage of the specific section you want to analyze.