# When to Use `--start/--end` Focused Mode vs. Scanning the Full Video

> Choose between --start/--end focused mode or full video scanning. Learn when to use each for optimal video analysis and dense frame coverage in your bradautomates/claude-video projects.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: best-practices
- Published: 2026-08-08

---

**Use `--start/--end` focused mode for videos longer than 10 minutes or when you need dense frame coverage of a specific segment, and reserve full-video scanning for short clips where you need complete coverage across the entire timeline.**

The `watch` skill in the `bradautomates/claude-video` repository extracts frames and transcripts from video URLs using two distinct processing strategies. Understanding when to use **focused mode** versus **full-video scanning** ensures you maximize the frame budget and avoid missing critical moments in lengthy content.

## Full-Video Scan vs. Focused Mode

The `watch` skill, implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), operates in two mutually exclusive modes depending on whether you provide time boundaries.

### Full-Video Scan Mode

By default, the skill extracts frames (keyframes, scene-aware frames, or token-burner frames) across the **entire duration** of the video. This mode works best for small-to-medium videos where you want coverage of the whole clip, or when you need every scene-change frame using `--detail token-burner`.

However, for long videos, the default frame cap spreads samples thinly across the timeline, potentially missing important moments between distant keyframes.

### Focused Mode (`--start` / `--end`)

When you provide `--start` and/or `--end` timestamps, the tool enters focused mode. In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the script sets `focused = start_sec is not None or end_sec is not None` (lines 150-155) and then calls `auto_fps_focus` to compute a higher FPS target for the shortened interval (lines 155-159).

This mode is essential when:
- Processing videos longer than 600 seconds (10 minutes), where the script prints a warning recommending focused mode (lines 26-33)
- You know the exact segment containing the information you need (e.g., a specific interview segment or demo portion)
- You need to stay within token limits, since the same `max-frames` budget applies to a shorter interval, yielding **more frames per second** inside the region of interest

## Why Focused Mode Matters

### Frame-Budget Efficiency

The tool caps the number of frames using `max-frames` or the default cap from `frame_cap(detail)`. In full-video mode, a 30-minute video might receive only a handful of frames, missing nuanced details. Focused mode concentrates the frame budget on your chosen interval, providing richer visual coverage where it counts.

### Performance and Cost

Downloading full-length videos and running scene-detection across the entire timeline consumes more bandwidth, CPU, and (if using Whisper) token credits. By slicing out a segment, the download can be trimmed and subsequent frame extraction runs on a smaller file, reducing compute overhead.

### User-Controlled Precision

You can combine `--timestamps` with `--start/--end`. The script first extracts cue frames at the supplied timestamps, then applies the focused range to filter transcript segments using `filter_range` (lines 63-66). This allows you to **pin** exact moments while still benefiting from automatic frame selection within the same window.

## Implementation Details in watch.py

### Parsing and Validation

The `--start` and `--end` arguments accept `SS`, `MM:SS`, or `HH:MM:SS` strings, converted to seconds by the `parse_time` function. Validation ensures non-negative start times and that end exceeds start (lines 143-148).

```python

# From skills/watch/scripts/watch.py

start_sec = parse_time(args.start) if args.start else None
end_sec = parse_time(args.end) if args.end else None
focused = start_sec is not None or end_sec is not None

```

### Effective Window Calculation

If you omit a bound, the script defaults to the start of the video (`0.0`) or the full duration (`full_duration`). This creates an effective window that defines the processing scope.

### Dynamic FPS Calculation

In focused mode, the script calls `auto_fps_focus(effective_duration, max_frames=budget_cap)` to compute a higher frame-rate that fits the desired `max-frames` within the shortened window. This ensures dense sampling without exceeding the token budget.

### Long-Video Warnings

For videos longer than 600 seconds where the detail mode isn't `transcript` or `token-burner`, [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) prints a warning advising users to run the command with `--start/--end` for better results (lines 26-33).

## Practical Code Examples

```bash

# Full-video scan (default) - best for short clips under 10 minutes

watch https://youtu.be/xyz123 --detail efficient

# Focused mode: extract frames only between 02:15 and 04:00

# This concentrates the frame budget on a 1 minute 35 second slice

watch https://youtu.be/xyz123 --start 02:15 --end 04:00 --detail efficient

# Combine focused mode with explicit cue timestamps

# Pins exact moments while still using automatic selection in the window

watch https://youtu.be/xyz123 \
      --start 01:30 --end 03:00 \
      --timestamps 01:45,02:30 \
      --detail balanced

```

The first command processes the entire video with the "efficient" detail engine. The second command limits processing to a specific 95-second slice, allowing the same frame budget to provide more granular coverage. The third command ensures the moments at `01:45` and `02:30` are always included while still benefiting from automatic frame selection within the `01:30` to `03:00` window.

## Summary

- **Use full-video scanning** for videos under 10 minutes where you need complete coverage, or when using `--detail token-burner` to capture every scene change.
- **Use `--start/--end` focused mode** for videos longer than 10 minutes (the tool will warn you otherwise), when analyzing specific segments, or when you need higher frame density in a constrained time window.
- **Combine with `--timestamps`** to pin exact moments inside your focused window while maintaining automatic frame selection for the surrounding interval.
- **Remember the frame budget**: The same `max-frames` cap applies regardless of video length, so focused mode yields richer visual data per second of video.

## Frequently Asked Questions

### What happens if I only specify `--start` without `--end`?

The tool defaults the end boundary to the video's full duration. As implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), if `end_sec` is `None`, the effective window extends from your start timestamp to the end of the video, still triggering focused mode with its higher FPS calculation.

### Can I use `--timestamps` together with `--start/--end` focused mode?

Yes. The script extracts cue frames at your specified timestamps first, then applies the focused range filter to transcript segments using `filter_range` (lines 63-66). This hybrid approach ensures critical moments are captured while optimizing the frame budget for the surrounding interval.

### How does the frame budget work differently in focused mode?

The same `max-frames` cap (or default from `frame_cap(detail)`) applies in both modes. However, in focused mode, the script calls `auto_fps_focus` to calculate a higher effective FPS that distributes this fixed budget across the shorter duration. This results in more frames extracted per second of actual video, providing denser coverage of the region of interest.

### What timestamp formats does the `watch` skill accept?

The `parse_time` function in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) accepts `SS` (seconds), `MM:SS` (minutes:seconds), or `HH:MM:SS` (hours:minutes:seconds) formats. The function validates that start times are non-negative and that the end timestamp exceeds the start timestamp (lines 143-148).