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

> Discover how Claude-Video's transcript mode enables audio-only download. Learn how yt-dlp's ba/bestaudio format efficiently skips video for faster processing.

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

---

**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`](https://github.com/bradautomates/claude-video/blob/main/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`:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/watch.py).

## Format Selection in download.py

### yt-dlp Format String Construction

The `download()` function in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/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:

```python
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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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:

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/download.py), subtitles download separately from the media content, and [`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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.