# How to Fix Missing Captions in Claude Video Downloads

> Fix missing captions in Claude Video downloads. Learn how the tool uses Whisper transcription or frame output as fallbacks and how to reenable audio extraction.

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

---

**When captions are missing from a Claude Video download, the tool automatically falls back to Whisper transcription if an API key is configured, or delivers frames-only output if audio extraction is disabled or unavailable.**

The `claude-video` repository by bradautomates provides a `/watch` skill that processes video content through `yt-dlp`. When **Claude Video missing captions** occur—either because the source lacks subtitles or extraction fails—the codebase implements a robust fallback chain defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) that attempts transcription before defaulting to visual frame analysis.

## How Caption Retrieval Works Initially

When you execute the `/watch` command, the system first attempts to retrieve subtitle tracks using **yt-dlp**. In [`skills/watch/scripts/download.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/download.py), the `fetch_captions` function (lines 65-95) handles this retrieval and returns a `subtitle_path` only if VTT caption files were successfully discovered and downloaded.

If `fetch_captions` returns no subtitle file, the workflow proceeds to [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), where the `parse_vtt` function (lines 98-106) attempts to process the file. A failure here simply leaves `transcript_segments` empty, triggering the fallback mechanisms.

## The Three-Tier Fallback System for Missing Captions

The `claude-video` source code implements a conditional fallback chain when **Claude Video missing captions** are detected.

### Stage 1: VTT Parsing Verification

The [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) script first calls `parse_vtt` on any retrieved subtitle file. If this parsing fails or returns no segments, `transcript_segments` remains empty, and the system evaluates whether to proceed with audio transcription.

### Stage 2: Whisper Transcription

When transcript segments are empty, the script checks three specific conditions (lines 39-54 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)):

- The `--no-whisper` flag is **not** set
- A video file was successfully downloaded (`video_path` is available)
- The video contains an audio stream (`meta.get("has_audio")`)

If all conditions are true, the system loads a Whisper API key via `load_api_key` and executes `transcribe_video` to generate subtitles using either **Groq** or **OpenAI** APIs.

### Stage 3: Frames-Only Output

If Whisper is disabled via `--no-whisper` or no API key is configured, the skill falls back to delivering frames only. In [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 77-84), the code prints a helpful message directing you to the setup wizard and processes the video without audio transcription.

## Configuring Whisper API Keys

To enable the Whisper fallback for **Claude Video missing captions**, you must store a valid API key in `~/.config/watch/.env`. The [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) script (lines 28-55) scaffolds this configuration file if missing and explains where to place your keys.

After adding your credentials, running `python3 setup.py` marks the installation as complete and enables transcription capabilities.

```bash

# Scaffold the configuration file

python3 skills/watch/scripts/setup.py

# Edit ~/.config/watch/.env and add one of:

# GROQ_API_KEY=your_groq_key_here

# OR

# OPENAI_API_KEY=your_openai_key_here

# Re-run setup to confirm configuration

python3 skills/watch/scripts/setup.py

```

## Command-Line Options for Caption Handling

The `watch` command provides flags to control behavior when **Claude Video missing captions** occur:

```bash

# Default behavior: tries captions first, then Whisper fallback

watch https://example.com/video.mp4

# Force frames-only mode, skip Whisper entirely

watch https://example.com/video.mp4 --no-whisper

# Provide local subtitles manually to bypass extraction

watch /path/to/video.mp4 --subtitle /path/to/subtitles.vtt

```

## Summary

- **Primary retrieval**: The `fetch_captions` function in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) attempts VTT extraction via yt-dlp (lines 65-95).
- **Whisper fallback**: Automatically activates when captions are missing, an API key exists, and audio is present (lines 39-54 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py)).
- **Configuration**: Store `GROQ_API_KEY` or `OPENAI_API_KEY` in `~/.config/watch/.env` via the [`setup.py`](https://github.com/bradautomates/claude-video/blob/main/setup.py) wizard (lines 28-55).
- **Manual override**: Use `--subtitle` to provide local VTT files or `--no-whisper` to force frames-only processing.

## Frequently Asked Questions

### Why does Claude Video sometimes download videos without captions?

Captions are only available if the source platform provides subtitle tracks that yt-dlp can extract. According to the logic in [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) (lines 65-95), the `fetch_captions` function returns a path only when VTT files are successfully retrieved. If the host site lacks subtitles or blocks extraction, the file remains unavailable, triggering the Whisper fallback or frames-only output.

### How do I enable automatic transcription when captions are missing?

Configure a Whisper API provider by running `python3 skills/watch/scripts/setup.py` to create `~/.config/watch/.env`, then add either `GROQ_API_KEY` or `OPENAI_API_KEY`. As implemented in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 39-54), the system automatically calls `transcribe_video` when the three conditions are met: no `--no-whisper` flag, valid `video_path`, and `meta.get("has_audio")` returning true.

### Can I use Claude Video without any API keys for transcription?

Yes. If no API key is configured and captions are missing, the tool defaults to frames-only processing. According to [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) (lines 77-84), the script prints a warning and continues with visual analysis only. Alternatively, use the `--no-whisper` flag to explicitly disable transcription attempts and force this behavior.

### What happens if I provide my own subtitle file manually?

You can bypass the automatic caption retrieval and transcription entirely by using the `--subtitle` flag followed by the path to a local VTT file. This prevents the `fetch_captions` fallback chain from executing and uses your provided subtitles directly for the processing workflow.