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

> Learn to filter transcripts by time range in Claude-Video using CLI flags or the filter_range function. Slice cue lists precisely for any specific window of your video.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-10

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point parses these arguments using the `parse_time` helper function, then passes the converted values (in seconds) to `filter_range`:

```bash
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:

```python
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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.