How to Filter Transcript Segments to a Specific Time Range Using filterrange in Claude Video

The filterrange function in skills/watch/scripts/transcribe.py isolates transcript segments by checking if each segment's start time is greater than or equal to the requested start and its end time is less than or equal to the requested end, trimming partial matches to fit the exact window.

The bradautomates/claude-video repository powers the /watch skill for video analysis. When processing video transcripts, users often need to isolate dialogue from a specific time window rather than analyzing the entire file. The system handles this through a dedicated filtering utility that operates on Whisper-generated segment data.

Where filterrange Is Implemented

The core logic resides in skills/watch/scripts/transcribe.py. This module handles both the initial transcription via Whisper (or caption extraction) and the subsequent filtering of segments. The function signature accepts a list of segment dictionaries and boundary timestamps:

def filterrange(segments: List[dict], start: float, end: float) -> List[dict]:
    ...

Each segment dictionary in the input list contains three required keys: start (float, seconds), end (float, seconds), and text (string). The function returns a new list containing only the segments that fall within the specified range.

How the Time Range Filtering Works

The filtering process follows a four-step pipeline to ensure accurate extraction:

Normalization – The function first converts any timestamp strings (e.g., "00:01:30") into floating-point seconds. This standardization allows the utility to compare user input against Whisper's native second-based timestamps.

Selection – A list comprehension iterates through the transcript segments, keeping only those where segment["start"] >= requested_start and segment["end"] <= requested_end. This ensures strict containment within the boundaries.

Edge Handling – When a segment straddles the requested boundary (starting before the range or ending after it), the function trims the segment's text content and adjusts the start or end timestamps to match the exact window edges. This prevents partial dialogue from bleeding into the output.

Ordering Preservation – The returned list maintains the original chronological order of segments, making the output immediately ready for downstream rendering or LLM summarization without additional sorting.

Practical Code Examples

Direct Usage of filterrange

Import the function directly from the transcription module to filter existing transcript data:

from skills.watch.scripts.transcribe import filterrange

# Sample transcript segments from Whisper

full_transcript = [
    {"start": 5.2, "end": 7.8, "text": "Hello world"},
    {"start": 8.0, "end": 10.1, "text": "This is a test"},
    {"start": 12.5, "end": 15.0, "text": "Another segment"},
]

# Extract only the portion between 6.0 and 13.0 seconds

excerpt = filterrange(full_transcript, start=6.0, end=13.0)

print(excerpt)

# Output:

# [

#   {"start": 6.0, "end": 7.8, "text": "Hello world"},

#   {"start": 8.0, "end": 10.1, "text": "This is a test"},

#   {"start": 12.5, "end": 13.0, "text": "Another segment"},

# ]

Using the Watch Skill with Time Constraints

When interacting with the Claude Video agent, you can request specific time ranges using natural language. The skill internally invokes filterrange after transcription:

/watch https://youtu.be/abc123 "Show me the transcript from 1:30 to 2:45"

Behind the scenes, skills/watch/scripts/watch.py orchestrates the download, extracts frames, runs Whisper for the full transcript, then calls filterrange with the converted timestamps (90.0 seconds to 165.0 seconds) before returning the result.

Programmatic Integration in Python Scripts

For automated workflows, chain the download and filtering operations:

from skills.watch.scripts.watch import download_and_transcribe
from skills.watch.scripts.transcribe import filterrange

url = "https://youtu.be/abc123"
full_transcript = download_and_transcribe(url)

# Filter to specific range (1:30 - 2:45)

trimmed = filterrange(full_transcript, 90.0, 165.0)

for seg in trimmed:
    print(f"[{seg['start']:.2f}s – {seg['end']:.2f}s] {seg['text']}")

Integration with the Transcription Pipeline

The filtering utility integrates into the broader video processing architecture across several key files:

• skills/watch/scripts/transcribe.py – Contains the filterrange implementation and Whisper integration logic.
• skills/watch/scripts/watch.py – Orchestrates the end-to-end flow; calls filterrange when the user supplies time constraints.
• skills/watch/SKILL.md – Defines the /watch command contract, including how time range parameters are parsed and passed to the filtering layer.
• skills/watch/scripts/config.py – Stores default configuration values (such as the Whisper model size) used during the transcription phase before filtering occurs.

Summary

• The filterrange function lives in skills/watch/scripts/transcribe.py and operates on lists of segment dictionaries.
• It filters segments by verifying that start >= requested_start and end <= requested_end, with automatic trimming for boundary-crossing segments.
• Input timestamps are normalized to seconds to match Whisper's output format.
• The utility preserves chronological order and is invoked by skills/watch/scripts/watch.py when users specify time ranges via the /watch skill.

Frequently Asked Questions

How does filterrange handle partial segment matches?

When a segment starts before the requested range or ends after it, filterrange trims the segment's text and adjusts the start or end timestamps to fit exactly within the specified window. This ensures the output contains only the dialogue that occurred during the target time period.

Can I use filterrange with transcript formats other than Whisper?

Yes, provided the input follows the expected dictionary structure with start, end, and text keys. The function performs no Whisper-specific processing; it treats the segments as generic time-bounded text blocks, making it compatible with any transcription source that provides millisecond or second-level timestamps.

What happens if I provide timestamps in "HH:MM:SS" format?

The normalization step within the filtering pipeline converts timestamp strings into floating-point seconds before comparison. You can pass either numeric seconds (e.g., 90.0) or formatted strings (e.g., "00:01:30"), and the function handles the conversion internally.

Where are the tests for the filterrange function?

The test suite verifying correct filtering behavior, including edge cases for boundary timestamps and partial segments, resides in the repository's test directory. These tests ensure that filterrange correctly handles overlapping ranges and preserves text accuracy when trimming segments.

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