When to Use Claude Video's Focused Mode with `--start` and `--end` Flags

Use Claude Video's focused mode with --start and --end flags when you need to analyze a specific time segment of a video rather than processing the entire file, which saves processing time and increases frame density for better detail capture.

Claude Video's focused mode is a precision analysis feature in the bradautomates/claude-video repository that lets you isolate and examine targeted portions of video content. By supplying time boundaries, you trigger specialized frame extraction and transcript filtering that optimizes for segment-level detail rather than whole-video summarization.

What the --start and --end Flags Do

The --start and --end flags define a temporal window for video analysis. When either flag is provided, Claude Video activates focused mode and restricts all downstream processing—including frame extraction, deduplication, scene detection, and transcript rendering—to that specific interval.

According to the source code in skills/watch/scripts/watch.py (lines 49-50), the flags accept flexible time formats:

• SS — seconds only (e.g., 45)
• MM:SS — minutes and seconds (e.g., 01:30)
• HH:MM:SS — full timestamp (e.g., 00:05:30)

The parse_time function in skills/watch/scripts/frames.py (lines 55-72) converts these strings into floating-point seconds for internal calculations.

When to Use Focused Mode

Analyze Long Videos Efficiently

Processing an entire multi-hour video consumes significant compute and returns diluted results. Focused mode lets you isolate relevant sections—such as a specific interview segment, a product demonstration, or a critical meeting portion—without wasting resources on irrelevant content.

Capture Higher Detail Density

Focused mode automatically increases frame density within your specified window. The auto_fps_focus function in skills/watch/scripts/frames.py (lines 41-58) replaces the standard auto_fps call, selecting a higher frames-per-second target specifically for your time range. This ensures Claude receives more visual information per second of content than it would in standard full-video mode.

Synchronize Frame and Text Analysis

When captions are available, focused mode filters the transcript to match your time window. The filter_range function (called in watch.py lines 63-66) trims transcript segments so that displayed text corresponds precisely to extracted frames, eliminating temporal mismatch between visual and textual analysis.

Validate Time Ranges Before Processing

The entry script performs strict validation in watch.py (lines 43-48):

• --start must be non-negative
• --end must exceed --start
• --start cannot exceed the video's total duration

Failed validation aborts execution immediately with descriptive error messages, preventing wasted processing on invalid ranges.

How Focused Mode Works: Technical Implementation

1. Argument Parsing and Conversion

Raw input strings pass through parse_time in frames.py, which handles integers, floats, and formatted strings uniformly:

# From frames.py lines 55-72

def parse_time(t):
    if t is None:
        return None
    if isinstance(t, (int, float)):
        return float(t)
    # Handles "01:30", "00:05:30" formats via splitting

2. Effective Window Computation

The script calculates effective_start and effective_end values (lines 50-55 in watch.py), defaulting to 0 and full duration when flags are omitted. A boolean focused flag tracks whether specialized processing is needed.

3. Frame Budget Allocation

For focused windows, auto_fps_focus computes a denser sampling rate appropriate for the smaller time scale, ensuring detailed frame coverage without overwhelming token limits.

4. Segmented Extraction

Frame extraction functions—including extract_at_timestamps and extract_keyframes—receive the computed start/end seconds and restrict output accordingly. Transcript filtering via filter_range in skills/watch/scripts/transcribe.py applies matching temporal bounds.

Practical Examples

Extract and analyze a 30-second product demonstration from a longer video:

# Using MM:SS format for precise targeting

watch https://youtu.be/abcdefg --start 00:45 --end 01:15

Process a specific meeting segment using plain seconds:

watch meeting_recording.mp4 --start 600 --end 900

Both commands:

1. Parse time values into seconds (45→75s and 600→900s respectively)
2. Validate the range against video duration
3. Invoke auto_fps_focus for enhanced frame density
4. Extract frames and transcript segments only within the specified window
5. Generate a markdown report containing focused visual and textual analysis

Summary

• Use --start and --end to isolate specific video segments for detailed analysis rather than processing entire files
• Focused mode increases frame density automatically via auto_fps_focus for richer visual detail within your window
• Time formats are flexible—accepting seconds, MM:SS, or HH:MM:SS through the parse_time helper
• Validation is strict—ensuring logical, in-bounds ranges before any processing begins
• Transcript synchronization happens automatically via filter_range when captions are available

Frequently Asked Questions

What happens if I only provide --start without --end?

Claude Video treats the missing flag as the video's full duration. The effective window runs from your specified start time to the end of the file. The effective_end calculation in watch.py (line 55) defaults to total video duration when --end is omitted.

Can I use decimal seconds for precise frame targeting?

Yes. The parse_time function accepts float values directly and returns them unchanged, allowing millisecond-level precision when needed. Integer and float inputs bypass string parsing entirely (frames.py lines 58-59).

Does focused mode affect the output format or report structure?

No. The markdown report structure remains identical—focused mode only changes which frames and transcript segments appear, not how they are formatted. The same deduplication, scene detection, and caption integration logic applies within the constrained window.

What error messages appear for invalid time ranges?

Validation failures in watch.py (lines 43-48) produce specific messages: negative start times trigger one error, end-start ordering failures trigger another, and exceeding video duration produces a third. All errors abort before any expensive frame extraction begins.

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