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

> Discover if Claude Video uses audio-only mode with captions. Learn how it bypasses audio downloads and generates transcripts from subtitle files for efficient video processing.

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

---

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

```python

# 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.

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

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

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