How Audio-Only Download Works in Claude-Video's Transcript Mode

In claude-video's transcript mode, the application downloads only the audio stream when no frame extraction is required, using yt-dlp's ba/bestaudio format to skip video tracks entirely while preserving subtitle retrieval capabilities.

The claude-video repository optimizes bandwidth usage by fetching only audio streams when processing video transcripts. When you invoke the /watch skill with the default transcript detail level, the system intelligently avoids downloading full video files unless cue timestamps are specified. This audio-only download function in claude-video's transcript mode reduces download times significantly while still delivering complete text transcripts through subtitle parsing or Whisper fallback.

Detection Logic in watch.py

The decision to trigger audio-only download begins in skills/watch/scripts/watch.py. The system evaluates whether the user requested transcript detail without providing specific --timestamps for frame extraction.

When both conditions are met—transcript detail is active and no cue timestamps are supplied—the code sets audio_only to True:

audio_only = detail == "transcript" and not cue_timestamps

This boolean flag determines whether the subsequent download operation retrieves only audio or the full video file. The flag is then passed to the download() function at lines 124-125 in watch.py.

Format Selection in download.py

yt-dlp Format String Construction

The download() function in skills/watch/scripts/download.py receives the audio_only parameter and constructs the appropriate yt-dlp format string. Inside the download_url function, the format selection logic appears at lines 126-127:

fmt = "ba/bestaudio" if audio_only else "bv*[height<=720]+ba/b[height<=720]/bv+ba/b"

When audio_only is True, the format string ba/bestaudio instructs yt-dlp to fetch only the best available audio stream. The ba selector targets the best audio bitrate, while bestaudio serves as a fallback for highest quality audio extraction.

Download Execution and Metadata Handling

The download proceeds with standard subtitle retrieval and info-json generation, but the resulting dictionary contains dl["video_path"] set to None while dl["downloaded"] remains True at lines 158-162. According to the claude-video source code, the get_metadata function falls back to yt-dlp's returned information for duration and codec details without requiring an actual video file, as implemented in watch.py lines 31-38.

Transcript Generation Workflow

Subtitle Parsing and Whisper Fallback

With only the audio stream available, the system processes existing subtitles through skills/watch/scripts/transcribe.py. If the video includes captions, the transcript generates directly from these VTT files without additional processing.

When captions are missing, the skill optionally invokes skills/watch/scripts/whisper.py for speech-to-text conversion using the downloaded audio file. This workflow operates entirely without video data unless you explicitly override the behavior with --no-whisper.

Practical Usage Examples

The following commands demonstrate how transcript mode handles audio-only downloads in different scenarios:

# Default transcript mode - downloads audio only if subtitles unavailable

watch https://youtu.be/abcdefg

# Transcript with timestamps - forces full video download for frame extraction

watch https://youtu.be/abcdefg --detail transcript --timestamps 00:30,01:15

# Balanced mode - explicitly requests video download despite transcript focus

watch https://youtu.be/abcdefg --detail balanced

Summary

• Transcript mode detection occurs in skills/watch/scripts/watch.py when detail == "transcript" and no cue timestamps are present.
• Audio-only flag triggers the ba/bestaudio format selection in skills/watch/scripts/download.py to skip video track retrieval.
• Metadata extraction functions without video files by utilizing yt-dlp's returned information.
• Subtitle availability determines whether the transcript generates from existing captions or requires Whisper audio processing.
• Bandwidth optimization saves significant download time by fetching only audio streams when frame extraction is unnecessary.

Frequently Asked Questions

When does claude-video download the full video instead of audio-only?

The system downloads the full video file when you specify cue timestamps using the --timestamps flag or select a detail mode other than transcript, such as balanced or visual. These conditions invalidate the audio_only boolean check in watch.py, forcing the format selector to use the video-inclusive download string.

Does audio-only mode still retrieve video subtitles?

Yes. The download process maintains subtitle retrieval regardless of the audio-only setting. According to the source code in download.py, subtitles download separately from the media content, and skills/watch/scripts/transcribe.py parses VTT files into transcripts without requiring the video stream.

What happens if a video has no subtitles in audio-only mode?

When captions are unavailable and audio_only is enabled, the skill falls back to Whisper processing using the downloaded audio file at skills/watch/scripts/whisper.py. This occurs unless you explicitly disable Whisper with --no-whisper, in which case the transcript generation would fail or return empty.

How does the yt-dlp format string change between audio and video downloads?

In download.py, the format string switches from ba/bestaudio for audio-only downloads to bv*[height<=720]+ba/b[height<=720]/bv+ba/b for video-inclusive downloads. The first format selects only the best audio stream, while the second constructs a video-audio merge with resolution constraints, ensuring you receive both visual and audio data when frame extraction is required.

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