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

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, 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:

audio_only = detail == "transcript" and not cue_timestamps

(source: 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. Here, the format string changes based on the flag at lines 26–31:

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

(source: 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 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:

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, 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:

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:

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:

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 when users request transcripts without frame timestamps.
• Stream selection: 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 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, 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, 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 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.

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