# How the Audio-Only Download Feature Works for Whisper Transcription in claude-video

> Discover how claude-video's audio-only download feature efficiently prepares audio for Whisper transcription, staying under API limits and saving bandwidth for fast transcripts.

- Repository: [bradautomates/claude-video](https://github.com/bradautomates/claude-video)
- Tags: how-to-guide
- Published: 2026-07-25

---

**The audio-only download feature in claude-video downloads just the audio track when users request transcripts without video frames, converts the audio to a 16 kHz mono MP3 at 64 kbps, and sends it to Whisper—keeping payloads under the 25 MB API limit while eliminating unnecessary video bandwidth.**

When the `watch` skill in the bradautomates/claude-video repository generates transcripts without native captions, it employs an **audio-only download** strategy to optimize network usage and satisfy API constraints. Instead of retrieving full video streams, the tool extracts only the audio track via yt-dlp, compresses it into a Whisper-compatible format using FFmpeg, and submits it for transcription.

## When claude-video Switches to Audio-Only Downloads

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), the decision logic evaluates the requested detail level and timestamp requirements to determine whether video data is necessary. The code at lines 111–115 checks if the user selected `transcript` detail and did not request any cue timestamps:

```python
audio_only = detail == "transcript" and not cue_timestamps

```

(source: [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py), lines 111–115)

When `audio_only` evaluates to `True`, the system skips video stream downloads entirely. This occurs specifically when invoking the `watch` command with `--detail transcript` without frame extraction flags, ensuring the pipeline minimizes bandwidth by fetching only the audio data required for Whisper processing.

## Downloading the Audio Stream with yt-dlp

The `download.download()` function forwards the `audio_only` flag to `download_url()` in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py). Here, the format string changes based on the flag at lines 26–31:

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

```

(source: [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py), lines 26–31)

When `audio_only` is enabled, yt-dlp receives the `ba/bestaudio` format selector, which retrieves only the best available audio stream (typically `.m4a` or `.mp3`). This approach eliminates video codec overhead and reduces download sizes significantly compared to full video plus audio streams.

## Converting Audio for Whisper Compatibility

Once the audio file resides on disk, `transcribe_video()` in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) invokes `extract_audio()` to prepare the file for the Whisper API. The function uses FFmpeg to generate a low-bitrate mono MP3, as shown in lines 15–33:

```python
cmd = [
    "ffmpeg", "-hide_banner", "-loglevel", "error", "-y",
    "-i", str(Path(video_path).resolve()), "-vn",
    "-acodec", "libmp3lame", "-ar", "16000", "-ac", "1",
    "-b:a", "64k", str(out_path.resolve()),
]

```

(source: [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), lines 15–33)

This conversion produces a **16 kHz, mono, 64 kbps MP3** that consumes approximately 480 KB per minute of audio. The compressed file always remains below Whisper's 25 MB upload ceiling, enabling direct multipart POST requests to Groq or OpenAI endpoints without requiring complex chunking strategies.

## Usage Examples

The audio-only download operates transparently during standard transcription workflows. Here are practical command-line scenarios:

Request a pure transcript without video frames:

```bash
watch https://www.youtube.com/watch?v=abc123 --detail transcript

```

This triggers the `ba/bestaudio` download, extracts the MP3, and sends it to Whisper without fetching any video frames.

Request a transcript with specific frame timestamps:

```bash
watch https://www.youtube.com/watch?v=abc123 \
     --detail transcript --timestamps 00:30,01:15

```

The audio-only download still occurs for transcription, while frames are extracted only at the specified timestamps.

Force a specific Whisper backend while maintaining audio-only optimization:

```bash
watch https://www.youtube.com/watch?v=abc123 \
     --detail transcript --whisper groq

```

The audio-only download proceeds to Groq's Whisper endpoint with the compressed MP3 payload.

## Summary

- **Conditional activation**: The `audio_only` flag activates in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) when users request transcripts without frame timestamps.
- **Stream selection**: [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py) uses yt-dlp's `ba/bestaudio` format to download only audio tracks, avoiding video data.
- **Compression pipeline**: [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) converts source audio to 16 kHz mono 64 kbps MP3 using FFmpeg, ensuring files stay under Whisper's 25 MB limit.
- **Bandwidth efficiency**: Audio-only downloads reduce network usage while maintaining transcription quality through optimized MP3 encoding.

## Frequently Asked Questions

### Why does claude-video download only audio for Whisper transcription?

Downloading only the audio track minimizes bandwidth usage and ensures the file size remains below the 25 MB upload limit imposed by Whisper API providers like OpenAI and Groq. As implemented in [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py), the `ba/bestaudio` format selector retrieves the best available audio stream without video data.

### What audio format does claude-video send to Whisper?

The tool converts downloaded audio to a **16 kHz, mono MP3 encoded at 64 kbps** using FFmpeg. This specific format, configured in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py), produces approximately 480 KB per minute of audio—small enough to fit within API constraints while preserving speech clarity.

### How does claude-video decide between audio-only and full video downloads?

The decision logic in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) evaluates two conditions: whether the user requested `transcript` detail and whether cue timestamps were specified. If `detail == "transcript"` and no timestamps are requested, the `audio_only` flag becomes `True`, triggering the audio-only download path.

### Can I use the audio-only feature with specific Whisper backends?

Yes. The audio-only download works transparently with both Groq and OpenAI Whisper endpoints. When specifying `--whisper groq` or the default OpenAI provider, the `watch` skill still downloads only the audio track and compresses it to the 16 kHz mono MP3 format before uploading.