How Claude Video's Focused Mode Works with `--start` and `--end` Flags

Claude Video's focused mode isolates specific video segments by accepting --start and --end timestamps, converting them to seconds, validating the range, and switching to high-density frame extraction for precise analysis.

Claude Video is an open-source CLI tool for video analysis that includes a focused mode for targeting specific temporal windows. When you supply --start and --end flags, the tool defined in bradautomates/claude-video shifts from full-video processing to concentrated analysis of your specified interval, adjusting frame budgets and transcript filtering accordingly.

Parsing Time Inputs in watch.py

The focused mode begins with argument parsing in the entry script. In skills/watch/scripts/watch.py (lines 49‑50), the CLI defines --start and --end flags that accept timestamps in SS, MM:SS, or HH:MM:SS format, or plain numeric seconds.

The parser captures these raw strings and prepares them for conversion, setting the stage for the focused extraction pipeline.

Converting Time Strings to Seconds with parse_time

Raw timestamp strings are converted to floating-point seconds by the parse_time function in skills/watch/scripts/frames.py (lines 55‑72). This helper accepts strings, integers, or floats and returns the equivalent number of seconds, or None if the argument is omitted.

# From frames.py - converts "01:30" to 90.0

def parse_time(time_input):
    if isinstance(time_input, (int, float)):
        return float(time_input)
    # Handles HH:MM:SS and MM:SS parsing logic

    # Returns seconds as float or None

This conversion ensures that all subsequent calculations work with consistent numeric values regardless of the input format you provide.

Validating the Time Range

After parsing, watch.py enforces strict validation rules (lines 43‑48) to ensure the focused window is valid:

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

If any check fails, the script aborts with a descriptive error message before processing begins. This prevents invalid ranges from causing extraction errors downstream.

Calculating the Effective Window

Once validated, the script computes the effective boundaries in watch.py (lines 50‑55). If either flag is supplied, a focused mode flag is set internally. The code establishes:

• effective_start: defaults to 0 seconds if --start is omitted
• effective_end: defaults to the video's full duration if --end is omitted

These calculated boundaries are passed to all downstream processing functions, ensuring every subsequent operation respects the temporal constraints.

Increasing Frame Density with auto_fps_focus

For focused windows, Claude Video switches from the standard frame selection algorithm to auto_fps_focus in skills/watch/scripts/frames.py (lines 41‑58). Unlike the normal auto_fps function, this specialized routine allocates a higher frames‑per‑second target specifically for your selected interval.

This density increase ensures that the limited time window receives proportionally more analytical attention, capturing finer detail within the segment you care about rather than spreading the frame budget across the entire video duration.

Filtering Transcripts to the Focused Window

If the video includes captions, the transcript processing pipeline filters segments to match your temporal window. In skills/watch/scripts/watch.py (lines 63‑66), the code calls filter_range (located in transcribe.py) to trim the transcript data.

This synchronization ensures that any text analysis, summaries, or captions displayed alongside the extracted frames correspond exactly to the video segment being processed, maintaining alignment between visual and textual data.

Frame Extraction and Processing

Finally, the extraction functions—extract_at_timestamps, extract_keyframes, and related utilities—receive the calculated effective_start and effective_end values. Every subsequent step, including frame deduplication and scene detection, operates exclusively within these temporal bounds.

This boundary enforcement applies to all processing modules, ensuring that the focused mode truly isolates your target segment from the rest of the video content.

Practical Usage Examples

Execute focused mode using flexible timestamp formats:

# Focus on a 30-second segment using HH:MM:SS format

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

# Use plain seconds for the same window

watch video.mp4 --start 45 --end 75

Both commands perform the following operations:

• Parse the timestamp strings into 45.0 and 75.0 seconds
• Validate that 45 < 75 and that 75 seconds exists within the video duration
• Activate auto_fps_focus to allocate a dense frame budget for the 30-second window
• Extract frames only between the specified timestamps
• Generate a markdown report containing the focused frames and matching transcript segments

Summary

• Claude Video's focused mode activates when you supply --start or --end flags to the watch command.
• parse_time in frames.py converts timestamp strings (HH:MM:SS, MM:SS, or seconds) to floating-point seconds.
• Validation rules in watch.py ensure start ≥ 0, end > start, and start ≤ video duration.
• auto_fps_focus increases frame density specifically for the selected window.
• Transcript filtering via filter_range ensures text analysis matches the visual segment.
• All extraction functions respect the calculated effective_start and effective_end boundaries.

Frequently Asked Questions

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

Claude Video accepts three formats: plain seconds (e.g., 45), minutes and seconds (01:30), or hours, minutes, and seconds (01:30:00). The parse_time function in skills/watch/scripts/frames.py handles all three variations and converts them to floating-point seconds for internal processing.

How does focused mode affect frame extraction compared to normal mode?

When focused mode is active, the tool calls auto_fps_focus instead of the standard auto_fps function. This specialized routine allocates a higher frame-per-second budget to your selected time window, producing denser frame sampling within the segment while ignoring the rest of the video. According to the source code in frames.py (lines 41‑58), this ensures detailed capture of the specific interval you requested.

What happens if I provide an invalid time range?

The validation logic in skills/watch/scripts/watch.py (lines 43‑48) checks three conditions: start time must be non-negative, end time must be greater than start time, and start time must not exceed the video's total duration. If any check fails, the script exits immediately with a descriptive error message before attempting any frame extraction.

Does focused mode work with transcripts and captions?

Yes. When focused mode is active, the tool calls filter_range from transcribe.py to trim transcript segments to the same time window specified by your flags. This ensures that any text analysis, caption extraction, or content summaries match exactly the video segment being processed, as implemented in watch.py (lines 63‑66).

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