How to Fix Missing Captions in Claude Video Downloads

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

• 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 (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 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.

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

# 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 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).
• Configuration: Store GROQ_API_KEY or OPENAI_API_KEY in ~/.config/watch/.env via the 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 (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 (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 (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.

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