# How Claude-Video's Transcript-Only Mode Works Without Downloading Video Files > Discover how Claude-Video's transcript-only mode works without downloading video files. It extracts captions or audio for transcription, saving disk space and time. - Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video) - Tags: how-to-guide - Published: 2026-07-25 --- **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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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: ```bash # 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py)**: Implements `parse_vtt` and `format_transcript` for converting subtitle files into clean markdown output. - **[`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py)**: The yt-dlp wrapper supporting `audio_only` parameters for selective stream downloads. - **[`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py)**: Handles audio transcription when captions are unavailable. - **[`config.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.