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

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

The parse_time utility (lines 55-72 in 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 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:

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). 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 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) trims the text to match the selected time window (lines 63-66 in 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:

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

Use absolute seconds for the same range:

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

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

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:

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.
• Automatic optimization: The system switches to auto_fps_focus in 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: 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 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). 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 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) before being included in the final Markdown report.

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