What Happens in claude-video When a Video Has No Captions and No Whisper API Key Configured

When claude-video processes a video without subtitles and no configured Whisper API key, it gracefully degrades by skipping transcription, emitting a configuration warning, and generating a report containing only extracted frames with a "none available" transcript notice.

The claude-video repository provides a watch skill for automated video analysis that handles missing data through a deliberate fallback chain. When source videos lack caption files and neither GROQ_API_KEY nor OPENAI_API_KEY environment variables are present, the tool continues execution without crashing, following a specific five-step degradation path defined in the source code.

The Five-Step Graceful Degradation Sequence

Step 1: Caption Lookup Failure in watch.py

After yt‑dlp fetches metadata in skills/watch/scripts/watch.py, the code attempts to parse any VTT subtitle files between lines 99-108. When no caption files exist, the variable transcript_segments remains empty, triggering the need for alternative transcription methods.

Step 2: Whisper Fallback Activation

Because transcript_segments is empty, execution reaches the Whisper conditional block at lines 39-44 in watch.py. This block evaluates if not transcript_segments and not args.no_whisper, attempting to invoke Whisper transcription as a fallback for the missing captions.

Step 3: API Key Detection Returns None

The load_api_key() function in skills/watch/scripts/whisper.py (lines 24-31) searches for API credentials in environment variables and ~/.config/watch/.env. When neither GROQ_API_KEY nor OPENAI_API_KEY exists, the function returns (None, None), causing the condition if backend and api_key: to evaluate false and skip the Whisper API call.

Step 4: User-Facing Configuration Hint

At lines 55-63 in watch.py, the script prints a specific warning: watch: no subtitles and no Whisper API key found — run python3 setup.py to enable the fallback. This directs users to the setup.py helper script for configuring API credentials to enable future transcription capabilities.

Step 5: Report Generation Without Transcript

Lines 73-84 in watch.py generate the final markdown report, inserting "Transcript: none available" where textual content would normally appear. Frame extraction continues if the selected detail mode requires visual analysis, but no transcript accompanies the output.

Code Examples: Handling Videos Without Captions or API Keys

The following examples demonstrate the graceful degradation behavior when processing videos lacking both captions and Whisper configuration:

# Example 1 – Video without captions, no API key configured

watch https://example.com/video-without-captions.mp4

# → Output ends with:

# - **Transcript:** none available

# watch: no subtitles and no Whisper API key found — run `python3 setup.py` to enable the fallback

# Example 2 – Same video, but explicitly disabling Whisper

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

# → Same “none available” transcript line, but without the hint about configuring an API key.

# Example 3 – Adding frames‑only detail (e.g., efficient) when no transcript is possible

watch https://example.com/video-without-captions.mp4 --detail efficient

# → Frames are still extracted; transcript remains absent.

Key Implementation Files

Four primary files control this fallback behavior in the claude-video repository:

• skills/watch/scripts/watch.py: The main entry point that orchestrates caption parsing, Whisper fallback logic, and report generation. Contains the degradation sequence at lines 39-44, 55-63, 73-84, and 99-108.

• skills/watch/scripts/whisper.py: Implements audio extraction and API integration. The load_api_key() function at lines 24-31 detects missing credentials by returning (None, None) when keys are absent from the environment.

• skills/watch/scripts/download.py: Handles video acquisition and caption fetching, returning subtitle_path = None when no subtitle files exist for the requested video.

• skills/watch/scripts/setup.py: Referenced in warning messages, this helper script creates ~/.config/watch/.env with placeholder API keys to guide users through configuration.

Summary

• No crashes occur: The tool degrades gracefully rather than throwing exceptions when both captions and API keys are missing.
• Clear user guidance: The specific warning message references python3 setup.py to configure GROQ_API_KEY or OPENAI_API_KEY.
• Partial output generation: Frame extraction continues based on detail mode settings, but the transcript section displays "none available".
• Conditional logic: The check if backend and api_key: in whisper.py prevents unauthorized API calls when credentials are absent.

Frequently Asked Questions

Does claude-video crash if a video has no captions and no Whisper API key is configured?

No, claude-video does not crash. According to the source code in skills/watch/scripts/watch.py, the tool implements a graceful degradation path that skips transcription and continues generating a report with available visual data, printing a warning message instead of terminating with an error.

How do I enable Whisper transcription after seeing the warning message?

Run python3 setup.py as suggested in the warning emitted at lines 55-63 of watch.py. This helper script creates the necessary ~/.config/watch/.env file and guides you through configuring either GROQ_API_KEY or OPENAI_API_KEY to enable the Whisper fallback for videos without embedded captions.

Will claude-video still extract video frames if no transcript is available?

Yes, frame extraction proceeds independently of transcription status based on the selected detail mode. In watch.py lines 73-84, the report generation logic separates frame extraction from transcript processing, ensuring visual analysis continues even when transcript_segments remains empty due to missing captions and API keys.

Where does claude-video look for the Whisper API key?

The load_api_key() function in skills/watch/scripts/whisper.py (lines 24-31) searches for GROQ_API_KEY and OPENAI_API_KEY in the current environment variables and in the ~/.config/watch/.env configuration file. If neither location contains valid credentials, the function returns (None, None), disabling Whisper transcription.

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