# How Video Transcript Data Is Formatted for Claude: A Technical Deep Dive

> Learn how video transcript data is formatted for Claude. Discover the plain-text conversion with [MM:SS] timestamps and markdown code blocks used by bradautomates/claude-video.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: deep-dive
- Published: 2026-08-09

---

**The watch skill in bradautomates/claude-video converts WebVTT subtitles into a plain-text format using `[MM:SS]` timestamps, with each line containing cleaned subtitle text that Claude receives inside a fenced markdown code block.**

The `claude-video` repository provides a watch skill that extracts and prepares video transcripts for Claude's analysis. Understanding exactly how this transcript data is structured helps developers integrate video processing capabilities and debug subtitle formatting issues. The transformation happens in two distinct stages within the Python scripts, ultimately delivering a human-readable timestamped format that Claude can reference when analyzing video content.

## Parsing WebVTT into Segment Dictionaries

The transcript formatting pipeline begins in [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py), where the `parse_vtt()` function handles the initial extraction. This function reads standard `.vtt` files and converts them into structured data that the system can manipulate before presenting to Claude.

According to the source code at lines 24-52, `parse_vtt()` returns a list of segment dictionaries, where each dictionary contains three specific keys:

- **`start`**: Float representing start time in seconds (rounded to two decimals)
- **`end`**: Float representing end time in seconds (rounded to two decimals)  
- **`text`**: String containing the cleaned subtitle text with HTML tags removed

During parsing, the function automatically collapses duplicate cues and removes formatting markup, ensuring Claude receives deduplicated, clean text without presentation-layer HTML.

```python
from transcribe import parse_vtt

segments = parse_vtt("example.vtt")
print(segments[:2])

# [{'start': 0.0, 'end': 2.58, 'text': 'Welcome to the video'},

#  {'start': 2.58, 'end': 5.12, 'text': 'We will explore...'}]

```

## Converting Segments to Claude-Ready Text

Once the VTT data exists as Python dictionaries, the `format_transcript()` function (lines 83-89 of [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py)) transforms these segments into the final format Claude actually reads. This function iterates through the segment list and emits one line per subtitle entry.

The formatting follows a strict pattern:

```

[MM:SS] segment text

```

The timestamp uses only the **start time** (derived from the integer portion of the `start` float), displaying minutes and seconds in `MM:SS` format. Notably, the end time and milliseconds are discarded in the final output, creating a cleaner reference format that Claude can use to correlate text with specific video frames without visual clutter.

```python
from transcribe import format_transcript

transcript = format_transcript(segments)
print(transcript)

# [00:00] Welcome to the video

# [00:02] We will explore...

```

## Embedding Transcripts in the Final Report

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) entry point orchestrates the complete workflow and inserts the formatted transcript into Claude's context window. Located at lines 55-66 and 103-108, this script calls `format_transcript()` on the processed segments (which may be filtered based on user criteria) and embeds the resulting string inside a fenced code block within a generated markdown report.

When Claude receives this report, it sees the transcript as a structured code block containing timestamp-prefixed lines, allowing the model to reference specific timestamps when discussing video content or correlating transcript segments with extracted frames.

```python
from watch import main  # CLI entry point

# Running `watch https://youtu.be/xyz` prints a markdown report where the

# transcript appears inside a fenced code block, already formatted as above.

```

## Summary

- **Source parsing**: The `parse_vtt()` function in [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py) converts WebVTT files into dictionaries with `start`, `end`, and `text` keys, removing HTML tags and deduplicating cues.
- **Text formatting**: The `format_transcript()` function transforms these dictionaries into lines prefixed with `[MM:SS]` timestamps, omitting end times and milliseconds for readability.
- **Final delivery**: The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script embeds this plain-text transcript inside a fenced code block within a markdown report, which Claude reads as structured timestamped data.
- **Repository location**: All formatting logic resides in the `bradautomates/claude-video` repository under the `skills/watch/scripts/` directory.

## Frequently Asked Questions

### What format does Claude receive for video transcripts?

Claude receives a plain-text transcript where each line follows the pattern `[MM:SS] subtitle text`. This format is generated by the `format_transcript()` function in [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py) and embedded inside a fenced code block within a markdown report. The timestamps use minutes and seconds from the start time only, with HTML tags and duplicate cues already removed during the parsing stage.

### Why does the transcript use [MM:SS] instead of full timestamps?

The `[MM:SS]` format provides sufficient precision for video reference while maintaining readability. According to the implementation in lines 83-89 of [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py), the code intentionally derives the timestamp from only the integer portion of the start time (converting seconds to minutes and seconds), omitting end times and milliseconds. This reduces token count and visual noise while still allowing Claude to correlate text with specific video frames.

### How are duplicate subtitle cues handled?

The `parse_vtt()` function automatically detects and collapses duplicate cues during the initial parsing phase (lines 24-52 of [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py)). This deduplication happens before the text reaches `format_transcript()`, ensuring Claude does not receive repeated lines when the source VTT contains overlapping or redundant subtitle entries. The function also strips HTML tags during this cleaning phase.

### Can I customize the transcript format for Claude?

Currently, the transcript format is hardcoded in the `format_transcript()` function at lines 83-89 of [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py). To modify the timestamp format or include end times, you would need to edit this function to change how the `start` time is converted to the `[MM:SS]` string, or modify the line template to include additional fields from the segment dictionaries.