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

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, 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.

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) 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.

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 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.

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 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 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 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, 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). 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. 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.

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