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

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, 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, 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).

# 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 prints a warning advising users to run the command with --start/--end for better results (lines 26-33).

Practical Code Examples

# 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, 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 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).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}