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

> Master Claude-video's --start and --end flags for precise video analysis. Analyze specific time ranges with higher frame density and filtered transcripts. Unlock focused insights.

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

---

**Use the `--start` and `--end` flags with the `watch` command to analyze specific time ranges of a video, enabling higher frame density and filtered transcripts for targeted sections.**

The `watch` command in the bradautomates/claude-video repository provides precision controls for analyzing video subsections. By using the `--start` and `--end` flags, you can limit processing to a specific temporal window, which triggers optimized frame sampling and transcript filtering. This focused analysis approach is ideal for long-form content where only specific segments require detailed examination.

## How the --start and --end Flags Work

The focused analysis pipeline involves several coordinated steps across the codebase, from CLI argument parsing to final report generation.

### Argument Parsing and Time Formats

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the CLI entry point defines both flags as optional string arguments (lines 49-51). These strings are converted to seconds using the `parse_time` function imported from [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py).

The `parse_time` utility (lines 55-72 in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py)) accepts multiple human-readable formats:
- **Seconds only**: `90` (interprets as 90 seconds)
- **Minutes:Seconds**: `01:30` (interprets as 90 seconds)
- **Hours:Minutes:Seconds**: `00:01:30` (interprets as 90 seconds)

### Range Validation and Effective Duration

After conversion, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) validates the temporal constraints (lines 43-49). The script ensures the start time is non-negative, that the end exceeds the start, and that the start does not exceed the video's total duration.

The effective processing window is calculated as:

```python
effective_start = start_sec if start_sec is not None else 0.0
effective_end   = end_sec   if end_sec   is not None else full_duration
effective_duration = max(0.0, effective_end - effective_start)
focused = start_sec is not None or end_sec is not None

```

These values drive all subsequent processing decisions (lines 50-53).

### FPS Budgeting and Frame Extraction

When a focused range is detected, Claude-Video switches from the standard `auto_fps` to `auto_fps_focus` (lines 55-58 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)). This function allocates a denser frame budget appropriate for the shortened interval, ensuring detailed analysis of the subsection.

The lower-level extraction utilities in [`frames.py`](https://github.com/bradautomates/claude-video/blob/main/frames.py) receive explicit `start_seconds` and `end_seconds` parameters. Both `extract_at_timestamps` (lines 86-92) and the scene/keyframe detection engines (lines 126-132) respect these boundaries, ensuring no frames are processed outside the specified window.

### Transcript Filtering

If the video includes subtitles or Whisper-generated transcripts, the `filter_range` function (from [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py)) trims the text to match the selected time window (lines 63-66 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)). This ensures that transcript analysis in the final report corresponds exactly to the visual content being examined.

## CLI Usage Examples

The `--start` and `--end` flags integrate seamlessly with the `watch` command, supporting various time formats and combinations with other flags.

Analyze a specific 45-second segment using MM:SS format:

```bash
watch "https://www.youtube.com/watch?v=example" \
      --start 01:30 --end 02:15 \
      --detail balanced

```

Use absolute seconds for the same range:

```bash
watch my_video.mp4 --start 90 --end 135 --resolution 720

```

Combine focused analysis with high-detail processing and custom frame limits:

```bash
watch "https://youtu.be/xyz" \
      --start 00:05:00 --end 00:10:00 \
      --detail token-burner \
      --max-frames 200 \
      --no-dedup

```

This command processes only the 5-minute slice beginning at 5 minutes, applying the "token-burner" detail level while disabling near-duplicate frame removal.

## Programmatic Usage

Developers can invoke the focused analysis programmatically by calling the `main` function from [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py):

```python
from watch import main as watch_main
import sys

sys.argv = [
    "watch",
    "https://youtu.be/xyz",
    "--start", "00:02:30",
    "--end",   "00:04:00",
    "--detail", "efficient"
]
exit_code = watch_main()
print(f"watch exited with code {exit_code}")

```

This approach allows integration into automated workflows or custom applications requiring precise video segment analysis.

## Summary

- **Precise targeting**: Use `--start` and `--end` with `SS`, `MM:SS`, or `HH:MM:SS` formats to define analysis windows in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py).
- **Automatic optimization**: The system switches to `auto_fps_focus` in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py) when ranges are specified, allocating higher frame density to shorter intervals.
- **Boundary enforcement**: Frame extraction functions and transcript filtering respect the defined range, ensuring complete isolation of the target segment.
- **Validation**: The CLI validates that start times are non-negative, ends exceed starts, and ranges fit within video duration before processing begins.

## Frequently Asked Questions

### What time formats does Claude-Video accept for the --start and --end flags?

Claude-Video accepts three formats parsed by the `parse_time` function in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py): raw seconds (e.g., `90`), minutes and seconds (`01:30`), or full timestamps (`00:01:30`). All formats are normalized to fractional seconds for internal processing.

### Can I use only --start or only --end, or do I need both?

You can use either flag independently or both together. If you specify only `--start`, analysis runs from that timestamp to the video's end. If you specify only `--end`, analysis runs from the beginning (0:00) to that timestamp. The `effective_start` and `effective_end` variables in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) handle these defaults automatically.

### How does focused analysis affect the frame sampling rate?

When a focused range is provided, Claude-Video calls `auto_fps_focus` instead of `auto_fps` (as implemented in [`skills/watch/scripts/frames.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/frames.py)). This function recalculates the frames-per-second budget specifically for the shortened duration, typically resulting in denser sampling and more detailed analysis of the subsection compared to analyzing the full video.

### Does transcript filtering work with Whisper-generated transcripts and existing subtitles?

Yes. The `filter_range` function in [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) processes both Whisper-generated transcripts and embedded subtitle tracks. When `--start` or `--end` are specified, the transcript is trimmed to include only segments that fall within the effective time range (lines 63-66 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)) before being included in the final Markdown report.