How --start/--end Focus Mode Filters Transcript Timestamps in Claude-Video

When you specify --start or --end arguments, claude-video activates focus mode and filters transcript segments using an overlap-based algorithm that keeps any cue intersecting your specified time window.

Claude-video is an open-source tool for extracting and analyzing video transcripts. When you need to examine only a specific portion of a video, the --start and --end flags activate focus mode to filter transcript timestamps before processing. This filtering happens through the filter_range function in skills/watch/scripts/transcribe.py, which preserves any segment overlapping your requested interval while discarding cues that fall completely outside the window.

How Focus Mode Activates

Focus mode triggers automatically in skills/watch/scripts/watch.py when either --start or --end arguments are provided. The entry point sets a boolean variable focused to True and converts your time strings (like "2:15" or "00:01:30") into numeric seconds.

After obtaining the transcript—whether from YouTube captions or via Whisper transcription—the script conditionally invokes the filter:

# watch.py – focus mode handling

if transcript_segments and focused:
    transcript_segments = filter_range(transcript_segments, start_sec, end_sec)

This same logic applies universally across all transcript sources, ensuring consistent timestamp filtering regardless of whether the video provides native captions or requires audio transcription.

The filter_range Algorithm

The core filtering logic resides in the filter_range function within skills/watch/scripts/transcribe.py. This function implements an overlap-based inclusion strategy rather than strict truncation.

Building the Time Window

The function first constructs a numeric window [lo, hi] from your input parameters:

def filter_range(segments, start_seconds, end_seconds):
    """Return segments whose time range overlaps [start, end]."""
    if start_seconds is None and end_seconds is None:
        return segments
    lo = start_seconds if start_seconds is not None else float("-inf")
    hi = end_seconds   if end_seconds   is not None else float("inf")
    return [seg for seg in segments if seg["end"] >= lo and seg["start"] <= hi]

Missing --start values default to negative infinity (including all content from the beginning), while missing --end values default to positive infinity (including all content to the end).

Overlap-Based Filtering Logic

A transcript segment is preserved if and only if its time range intersects with your specified window. Specifically, the function checks two conditions:

1. The segment's end time must be greater than or equal to the window's lower bound (seg["end"] >= lo)
2. The segment's start time must be less than or equal to the window's upper bound (seg["start"] <= hi)

This means partially overlapping segments remain intact. If a cue starts at 02:10 and ends at 02:20, and you request --start 02:15, that segment stays in the results because it intersects your window, even though it begins before your start time. The function does not trim or truncate the actual text content—it merely excludes non-overlapping cues.

When no transcript lines fall within your specified range, the final report displays a message such as: _No transcript lines fell inside 02:15 → 02:45._

Implementation Details in watch.py

According to the claude-video source code, the filtering happens immediately after transcript acquisition and before formatting. The filter_range call occurs in skills/watch/scripts/watch.py around line 160-170, where the transcript segments list is reassigned to the filtered result.

After filtering, the remaining segments pass to format_transcript for timestamp formatting and display. The absolute source timestamps are preserved in the output, so filtered results still display the original video times rather than relative offsets from your --start value.

Usage Examples

You can activate focus mode from the command line using several time formats:

# Focus on a 30-second segment of a YouTube video

python skills/watch/scripts/watch.py "https://youtu.be/abc123" --start 2:15 --end 2:45

# Start at 1 minute, continue to video end

python skills/watch/scripts/watch.py video.mp4 --start 00:01:00

# Process from beginning up to 30 seconds

python skills/watch/scripts/watch.py video.mp4 --end 00:00:30

Each command returns only the transcript cues that overlap with your specified window, maintaining original timestamps for context.

Summary

• Focus mode activates automatically when you supply --start or --end arguments in watch.py, setting the focused variable to True.
• filter_range in transcribe.py implements overlap-based filtering using infinity bounds for unspecified limits.
• Segments are kept if they intersect the requested window, not just if they fall completely inside it, preserving contextual cues that partially overlap your range.
• No truncation occurs—the algorithm filters out entire segments rather than trimming text content or adjusting timestamps to relative values.
• Empty results generate explicit feedback when no transcript lines overlap the specified interval.

Frequently Asked Questions

Does claude-video trim or truncate transcript text to fit the --start/--end window exactly?

No, claude-video does not truncate text content. The filter_range function keeps or discards entire cue segments based on overlap, meaning a segment starting at 02:10 and ending at 02:20 remains complete even if you specify --start 02:15. The segment stays because it overlaps the window, but the full text and original timestamps remain intact.

What happens if I specify only --start or only --end without the other parameter?

When you specify only --start, the end time defaults to positive infinity (float("inf")), including all remaining transcript content from your start time to the video end. When you specify only --end, the start time defaults to negative infinity (float("-inf")), including all content from the video beginning up to your end time.

Where in the source code is the focus mode filtering logic implemented?

The filtering logic resides in skills/watch/scripts/transcribe.py within the filter_range function (lines 70-80 according to the repository structure). The conditional invocation occurs in skills/watch/scripts/watch.py (around lines 160-170) where the script checks if transcript_segments and focused: before calling the filter.

Does focus mode work with both YouTube captions and Whisper-generated transcripts?

Yes, the filtering applies universally. In watch.py, the filter_range function is called after transcript acquisition regardless of the source. Whether the transcript comes from existing video captions or Whisper speech-to-text generation, the same overlap-based timestamp filtering occurs before the final report generation.

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