How Claude-Video's Transcript-Only Mode Works Without Downloading Video Files

Claude-Video's transcript-only mode bypasses video downloads by either extracting existing captions via yt-dlp or downloading only audio streams for Whisper transcription, ensuring zero video frames are ever written to disk.

The bradautomates/claude-video repository provides an efficient workflow for generating clean, timestamped transcripts while completely avoiding the storage overhead and bandwidth costs of video files. When you invoke claude-video's transcript-only mode using the --detail transcript flag, the tool intelligently routes through caption metadata or audio-only extraction rather than pulling the full video payload. This approach leverages yt-dlp's selective download capabilities and conditional logic in the main orchestration script to eliminate unnecessary data transfer.

The Three-Stage Transcript-Only Workflow

The implementation follows a strict hierarchy that prioritizes metadata extraction over media downloads, ensuring that video data is treated as optional rather than required.

Stage 1: Metadata and Caption Retrieval

In skills/watch/scripts/watch.py (lines 99-104), the entry point immediately attempts to fetch embedded or external subtitles through the fetch_captions function. This call uses yt-dlp to probe for .vtt subtitle files without downloading the video container.

If captions exist, skills/watch/scripts/transcribe.py handles the parsing via parse_vtt and formatting through format_transcript. These functions convert the WebVTT data into a readable markdown transcript before any video data reaches the local disk.

Stage 2: Short-Circuiting Video Downloads

When the user specifies --detail transcript and captions are available, the script executes a critical conditional at lines 112-114 in watch.py. Here, the code sets audio_only = True and explicitly forces video_path = None.

This assignment short-circuits all downstream frame extraction logic, guaranteeing that no video decoder is instantiated and no frames are written to temporary storage.

Stage 3: Audio-Only Fallback with Whisper

If caption metadata is absent, the system falls back to transcription via Whisper or the OpenAI/Groq endpoint. Controlled by the block at watch.py lines 239-251, this path still respects the transcript-only constraint by passing audio_only=True to the download request.

The download.py wrapper then instructs yt-dlp to retrieve only the audio stream, which Whisper subsequently processes into a formatted transcript without ever accessing video frames.

Practical Usage Examples

Here are the specific commands to trigger this efficient workflow:

# Generate transcript without downloading video frames

watch --detail transcript "https://youtu.be/abcd1234"

# Force transcript-only mode even with timestamp cues

watch --detail transcript --timestamps "30,60" "https://youtu.be/abcd1234"

Both commands skip frame extraction entirely. If the source contains VTT captions, the tool parses them directly; otherwise, it performs an audio-only download for Whisper processing.

Key Source Files and Functions

The transcript-only mode relies on specific modules within the skills/watch/scripts/ directory:

• watch.py: The main orchestration script that selects the transcript-only path, prevents video downloads by setting video_path = None, and triggers the Whisper fallback when needed.
• transcribe.py: Implements parse_vtt and format_transcript for converting subtitle files into clean markdown output.
• download.py: The yt-dlp wrapper supporting audio_only parameters for selective stream downloads.
• whisper.py: Handles audio transcription when captions are unavailable.
• config.py: Defines the DETAILS configuration set, including the "transcript" option that enables this mode.

Summary

• Caption-first approach: The system always attempts to extract existing subtitles via fetch_captions before considering any download.
• Explicit video bypass: Setting video_path = None in watch.py (lines 112-114) physically prevents frame extraction.
• Audio-only safety net: When captions are missing, the Whisper fallback downloads only audio streams using audio_only=True.
• Zero video footprint: Throughout the entire pipeline, the transcript-only mode guarantees that no video files are written to disk.

Frequently Asked Questions

Does transcript-only mode ever download video frames?

No. According to the source code in watch.py, the transcript-only path explicitly sets video_path = None and audio_only = True, which prevents any video frame extraction. The only data that may be downloaded is audio (for Whisper) or text (for captions).

What happens if a YouTube video has no embedded captions?

When fetch_captions returns empty, the code block at watch.py lines 239-251 triggers the Whisper fallback. This path downloads only the audio stream using yt-dlp's audio-only formats, then transcribes it via Whisper or the OpenAI/Groq API, maintaining the zero-video guarantee.

Where is the transcript formatting logic located?

The formatting logic resides in skills/watch/scripts/transcribe.py. This module contains the parse_vtt function for parsing WebVTT subtitle files and format_transcript for converting parsed data into readable markdown output.

Can I use transcript-only mode with timestamp filtering?

Yes. Even when using --timestamps to specify cue points, the --detail transcript flag maintains the video-free workflow. The system filters the transcript data after processing without ever downloading the visual content.

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