Does Claude Video Use Audio-Only Mode When Captions Are Available?

Claude Video does not use audio-only mode when captions are available; instead, it bypasses audio downloads entirely and generates transcripts directly from existing subtitle files.

The bradautomates/claude-video repository processes video content with an intelligent pipeline that prioritizes available captions over audio extraction. When processing YouTube URLs or local files for transcription, the application evaluates whether to download audio streams or rely on native subtitles. This decision logic ensures optimal performance by avoiding unnecessary downloads when caption data already exists.

How the Audio-Only Decision Logic Works

The Conditional Flag in watch.py

In skills/watch/scripts/watch.py, the script determines whether to activate audio-only mode using a specific boolean evaluation. The code checks if the user requested transcript detail without providing explicit cue timestamps.

# skills/watch/scripts/watch.py (lines 111-113)

audio_only = detail == "transcript" and not cue_timestamps

This flag controls whether the pipeline will later attempt to download only the audio track or process available caption files.

Caption Handling Bypasses Audio Downloads

When subtitles are present in the source, the script prioritizes them immediately. The logic checks for a subtitle_path in the download results dictionary and parses the VTT file directly.

if dl.get("subtitle_path"):
    transcript_segments = parse_vtt(dl["subtitle_path"])
    transcript_text = format_transcript(transcript_segments)
    transcript_source = "captions"

If captions are found, the script sets video_path = None (lines 119-124), effectively skipping the audio download phase entirely. This optimization ensures that when captions are already available, Claude Video does not engage the audio-only mode or download any media streams.

When Audio-Only Mode Actually Activates

The audio-only path serves as a fallback mechanism when native captions cannot be obtained. If the source URL yields no subtitle files, or when processing local video files without embedded captions, the script downloads only the audio track using specific ffmpeg parameters (-vn -ac 1 -ar 16000).

According to skills/watch/SKILL.md (lines 201-202):

"At transcript detail, captions are enough to return a report without downloading video. If captions are missing, the script downloads audio only and tries Whisper."

This behavior confirms that audio-only mode is strictly a fallback and is bypassed entirely when captions are available.

Practical Code Examples

Processing a video with available captions (no audio download):

When executing against a YouTube URL that has built-in subtitles, the command completes without downloading audio or video streams:

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/example" \
  --detail transcript

The script retrieves subtitles via yt-dlp, constructs the transcript from the VTT file in parse_vtt(), and terminates successfully.

Forcing audio-only processing (when captions are missing):

If the source lacks subtitles, the script automatically switches to audio extraction as implemented in skills/watch/scripts/download.py (line 118):

python3 "${SKILL_DIR}/scripts/watch.py" "https://youtu.be/example" \
  --detail transcript --no-whisper

In this scenario, audio_only evaluates to True, triggering the download of only the audio track for processing through the Whisper pipeline in skills/watch/scripts/whisper.py (lines 115-146).

Summary

• Claude Video only activates audio-only mode when captions are unavailable and the user requests transcript detail without providing cue timestamps.
• The audio_only flag is calculated in skills/watch/scripts/watch.py using the condition detail == "transcript" and not cue_timestamps (lines 111-113).
• When subtitle_path is present, the script sets video_path = None and skips all media downloads, processing captions directly instead.
• Audio extraction only occurs as a fallback to feed Whisper transcription when no subtitle files exist, utilizing ffmpeg -vn -ac 1 -ar 16000 parameters.

Frequently Asked Questions

What triggers audio-only mode in Claude Video?

Audio-only mode activates when the user requests transcript detail without providing cue timestamps, and the source contains no available captions. In skills/watch/scripts/watch.py, this evaluates to audio_only = detail == "transcript" and not cue_timestamps. When this condition is true and no subtitles are found, the script downloads only the audio track for processing.

Does Claude Video download audio if YouTube captions exist?

No. When YouTube captions are available, the script retrieves the subtitle file via yt-dlp and sets video_path = None, completely bypassing the audio download step. The transcript is generated directly from the caption file using parse_vtt(), and the audio-only path is never executed.

Where is the audio-only download implemented?

The actual audio extraction logic resides in skills/watch/scripts/download.py (line 118), where the audio_only parameter is passed to the yt-dlp configuration. Additionally, skills/watch/scripts/whisper.py (lines 115-146) handles the audio processing and transcription logic when the fallback mechanism is triggered.

Can I force audio download even when captions are available?

No, the current implementation in skills/watch/scripts/watch.py prevents this. When dl.get("subtitle_path") returns a valid path, the script immediately processes captions and skips the download phase regardless of other configuration flags. To process audio instead of using available captions, you would need to modify the source to disable subtitle detection or remove the video_path = None assignment.

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