How to Process a Specific Video Section Using `--start` and `--end` in Claude Video

Use the --start and --end CLI flags to limit processing to a specific time range, which triggers focused mode—automatically adjusting frame density and filtering transcripts to match only the selected segment.

The bradautomates/claude-video repository provides a powerful Python-based toolkit for video analysis, and its watch command supports precise temporal targeting through command-line arguments. When you need to analyze only a portion of a video rather than the entire duration, these flags integrate with the underlying ffmpeg pipeline and transcript filtering logic to optimize both performance and output relevance.

Understanding the --start and --end Arguments

The core entry point for this functionality is located in skills/watch/scripts/watch.py, which implements the main watch CLI script. When invoked, the script builds an argparse parser that accepts --start and --end as optional string arguments. These parameters accept timestamps in SS, MM:SS, or HH:MM:SS format, allowing you to specify exact boundaries for video processing.

Supplying either flag activates focused mode (focused = True), which fundamentally alters how the system allocates resources. Instead of distributing the frame budget across the entire video duration, the logic switches to auto_fps_focus in frames.py, yielding a denser sampling rate specifically for your selected interval.

Timestamp Formats and Validation

Before processing begins, the parse_time function in skills/watch/scripts/frames.py converts your input strings into float values representing seconds. This function handles all three supported formats and validates that the values are logically consistent.

The validation logic in watch.py enforces three critical constraints:

• Non-negative start: The --start value must be greater than or equal to zero
• Sequential ordering: The --end timestamp must exceed the --start timestamp
• Duration bounds: The start time cannot exceed the video's total duration

If any check fails, the script aborts with a descriptive error message before invoking expensive video processing operations.

How Range Processing Works

When valid timestamps are provided, the system calculates effective_start (defaulting to 0 if unspecified) and effective_end (defaulting to the full duration if unspecified). These boundaries propagate through the entire processing pipeline.

Argument Parsing and Validation

In watch.py, the argument parser captures raw string inputs into args.start and args.end. The script then invokes validation logic to ensure the temporal range is valid relative to the video's metadata retrieved during the initial probe phase.

Timestamp Conversion in frames.py

The parse_time utility converts formatted strings into seconds for internal calculations. Conversely, format_time prepares human-readable representations for the final report output. These conversions ensure that user-facing displays remain readable while internal ffmpeg commands receive precise numeric values.

Frame Extraction with ffmpeg

The extract function in skills/watch/scripts/frames.py receives start_seconds and end_seconds as parameters. It constructs an ffmpeg command incorporating -ss (seek to start) and -to (terminate at end) flags, causing ffmpeg to seek directly to the start timestamp and cease processing at the end boundary. Only frames within the specified window are written to the output directory, significantly reducing I/O overhead for long videos.

Transcript Filtering

After potential caption download or Whisper transcription, the filter_range function in skills/watch/scripts/transcribe.py trims the transcript to match the selected window. This function discards any subtitle segments falling outside the specified time boundaries, ensuring that the reported transcript content synchronizes perfectly with the extracted visual frames.

Focused Mode and Frame Budgeting

When processing a specific range, the system automatically switches from standard auto-fps logic to auto_fps_focus (as implemented in frames.py). This optimization concentrates the available frame budget onto the narrower time window, providing richer visual coverage for critical sections without exceeding overall processing limits.

The final markdown report includes a "Focus range" line when boundaries are applied, displaying the formatted start and end times. Both the frames list and transcript sections reflect only the chosen segment, creating a cohesive analysis package isolated to your region of interest.

Practical Code Examples

Extract frames from 1 minute 30 seconds to 2 minutes 15 seconds, limiting resolution to 720px:

python -m skills.watch.scripts.watch \
    "https://www.youtube.com/watch?v=example" \
    --start 01:30 \
    --end 02:15 \
    --resolution 720

Process a local video from 45 seconds to 1 minute 10 seconds with transcript generation:

python -m skills.watch.scripts.watch \
    ./local_video.mp4 \
    --start 00:45 \
    --end 01:10 \
    --detail transcript

Combine a custom frame cap with a precise 10-second range:

python -m skills.watch.scripts.watch \
    "https://vimeo.com/123456" \
    --start 00:00:10 \
    --end 00:00:20 \
    --max-frames 30

In each case, the output includes only frames and transcript lines falling inside the specified interval, and internal logs prefixed with [watch] display the calculated effective boundaries and adjusted fps values.

Summary

• Processing specific video sections uses --start and --end flags in skills/watch/scripts/watch.py to define temporal boundaries
• Valid formats include SS, MM:SS, and HH:MM:SS, converted to seconds via parse_time in frames.py
• Range validation ensures logical constraints before processing begins
• The extract function passes -ss and -to flags to ffmpeg for efficient segment extraction
• Transcript content is filtered via filter_range in transcribe.py to match the selected window
• Focused mode automatically activates auto_fps_focus, concentrating frame budgets on the selected segment

Frequently Asked Questions

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

Claude Video accepts three timestamp formats: raw seconds (SS), minutes and seconds (MM:SS), and hours with minutes and seconds (HH:MM:SS). The parse_time function in frames.py handles conversion of all three formats to float values representing seconds, which are then passed to ffmpeg and the transcript filtering logic.

Does using --start and --end download the entire video or just the selected section?

The system downloads the complete video file but processes only the specified section. The ffmpeg -ss and -to flags seek to the start position and terminate at the end timestamp during frame extraction, while filter_range in transcribe.py discards transcript segments outside the range. This approach ensures accurate keyframe extraction while minimizing actual processing overhead.

What happens if I specify an end time beyond the video's actual duration?

The validation logic in watch.py prevents processing when the start time exceeds the video duration, but if the end time extends beyond the actual duration, ffmpeg typically processes until the end of the available media. The effective_end value defaults to the full duration when unspecified or when validation determines the provided end exceeds available content.

How does focused mode affect the number of frames extracted?

When --start or --end is specified, focused mode activates auto_fps_focus instead of the standard auto-fps calculator. This function concentrates the frame budget onto the narrower time window, effectively increasing the frame density for the selected segment while maintaining the overall --max-frames limit, ensuring richer visual coverage of the specific section you want to analyze.

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