How to Filter Transcripts by Time Range in Claude-Video: A Complete Guide

Filter transcripts by time range in Claude-Video using the --start and --end CLI flags or by calling the filter_range function directly in skills/watch/scripts/transcribe.py to slice cue lists to any specific window.

The bradautomates/claude-video repository provides a Python-based toolkit for processing video transcripts from both YouTube captions and Whisper-generated audio transcriptions. Whether you need to isolate a specific section of a lecture or analyze a particular interview segment, the built-in time-range filtering capability allows you to extract only the relevant dialogue without manual editing.

Understanding the Transcript Data Structure

Before filtering, Claude-Video normalizes all transcript sources into a consistent dictionary format. Each cue or segment is stored as a dictionary with three keys: {"start": float, "end": float, "text": str}.

The start and end values represent timestamps in seconds, while text contains the spoken dialogue. This unified structure applies regardless of whether the transcript originates from YouTube's auto-generated WebVTT files or OpenAI's Whisper API, ensuring that downstream filtering logic works identically across all input sources.

The Core Filtering Logic

The heart of the time-range feature is the filter_range function defined in skills/watch/scripts/transcribe.py (lines 70-80). This utility accepts a list of transcript segments and two boundary values, returning only those cues that overlap with the specified window.

The function implements an overlap-based inclusion strategy: it keeps any segment where the interval [start, end] intersects with the requested time window. If you do not provide either boundary, the function returns the entire transcript list unchanged. This design ensures that partial cues at the window edges are preserved, preventing truncation of sentences that begin slightly before your start time or end slightly after your end time.

Command-Line Usage

When using the watch CLI tool, time ranges are specified via the --start and --end flags. These flags accept human-readable formats including raw seconds (SS), minutes and seconds (MM:SS), or full hours (HH:MM:SS).

The watch.py entry point parses these arguments using the parse_time helper function, then passes the converted values (in seconds) to filter_range:

watch https://youtu.be/xyz123 \
      --detail transcript \
      --start 01:23 \
      --end 02:45

In this example, the tool downloads the video, extracts or generates the transcript, and then filters the results to include only the dialogue occurring between 1 minute 23 seconds and 2 minutes 45 seconds. The final Markdown report displays only the filtered content under the "## Transcript" section.

Programmatic Usage

You can also leverage the filtering logic directly in Python scripts without invoking the CLI. This is useful when processing local VTT files or integrating transcript filtering into larger data pipelines.

Filtering Existing VTT Files

To parse a WebVTT file and extract a specific time window:

from skills.watch.scripts.transcribe import parse_vtt, filter_range, format_transcript

# Load a VTT file (typically obtained from a previous download)

segments = parse_vtt("my_video.vtt")

# Keep only cues between 90 seconds and 150 seconds

windowed = filter_range(segments, start_seconds=90, end_seconds=150)

# Generate a formatted Markdown string

print(format_transcript(windowed))

Integrating with Whisper Fallback

When working with Whisper-generated transcripts, the same filtering approach applies immediately after transcription:

from skills.watch.scripts.whisper import transcribe_video, load_api_key
from skills.watch.scripts.transcribe import filter_range, format_transcript

# Load API credentials and define video/audio paths

backend, key = load_api_key()
all_segments, _ = transcribe_video(video_path, audio_path, backend, key)

# Apply the time-range filter

filtered = filter_range(all_segments, start_seconds=30, end_seconds=120)
print(format_transcript(filtered))

This pattern works identically for both caption-derived and Whisper-generated transcripts, as both sources ultimately produce the same segment dictionary structure consumed by filter_range.

How the Filtering Pipeline Works

The complete transcription workflow in Claude-Video processes time-range filtering at a specific stage in the pipeline:

1. Parse VTT – The parse_vtt function in transcribe.py (lines 24-49) reads WebVTT files and creates the standardized segment dictionaries.

2. Deduplicate – The _dedupe function (lines 55-66) merges consecutive identical cues, which commonly occur in YouTube auto-generated subtitles.

3. Slice to Window – The filter_range function (lines 70-80) drops segments that lie completely outside the [start, end] interval while preserving overlapping cues.

4. Render Output – The format_transcript function (lines 83-89) converts the filtered list into a timestamped Markdown text block suitable for the final report.

5. CLI Integration – In watch.py (lines 63-66), the --start and --end arguments are parsed and forwarded to filter_range only when the transcript detail level is requested.

Summary

• Primary function: Use filter_range in skills/watch/scripts/transcribe.py to slice transcript lists by time range.
• CLI flags: Pass --start and --end to the watch command using MM:SS or HH:MM:SS formats.
• Data format: All transcripts are normalized to dictionaries with start, end, and text keys before filtering.
• Overlap logic: The filter preserves any segment that overlaps with the specified window, preventing mid-sentence truncation.
• Universal application: The same filtering works for both YouTube caption sources and Whisper-generated transcripts.

Frequently Asked Questions

What time formats does Claude-Video accept for the --start and --end flags?

Claude-Video accepts raw seconds (SS), minutes and seconds (MM:SS), or hours with minutes and seconds (HH:MM:SS). The parse_time function in transcribe.py automatically converts these human-readable formats into float values representing seconds before passing them to filter_range.

Does the filter include segments that partially overlap the time range?

Yes, the filter_range function uses inclusive overlap logic. It retains any segment where the cue's time interval intersects with your specified window, even if the segment starts before your start time or ends after your end time. This ensures you don't lose context from sentences that cross your boundary thresholds.

Can I filter transcripts from Whisper-generated audio transcriptions?

Absolutely. The filter_range function operates on the standard segment dictionary format used throughout the codebase. Whether the transcript originates from YouTube's WebVTT captions via parse_vtt or from Whisper API output via transcribe_video, you can apply the same filtering logic using identical function calls.

Where is the filter_range function implemented in the source code?

The filter_range function is implemented in skills/watch/scripts/transcribe.py at lines 70-80. This file also contains related utilities including parse_vtt for reading WebVTT files, _dedupe for merging duplicate consecutive cues, and format_transcript for rendering the final output.

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