Handling Videos with No Captions and No Whisper API Key in claude-video

TLDR: When the watch skill encounters a video without subtitles and detects no Whisper API key in the environment, it gracefully degrades by skipping transcription, printing a configuration hint, and generating a markdown report containing only extracted frames.

The claude-video repository provides a watch skill for processing video content through Claude's API. Understanding how the system handles missing transcripts and unavailable speech-to-text fallback is essential for users operating without API credentials. When both caption files and Whisper API keys are absent, the tool follows a specific five-step degradation path that preserves functionality while alerting the user to the configuration gap.

The Graceful Degradation Sequence

When transcript_segments remains empty after the initial caption parsing and load_api_key() returns no credentials, the following sequence occurs:

Step 1: Caption Lookup Fails

After yt-dlp fetches video metadata, watch.py attempts to parse any available VTT subtitle files via the download module. When download.py returns subtitle_path = None, transcript_segments stays empty, triggering the fallback logic.

Source: [watch.py lines 99-108](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L99-L108)

Step 2: Whisper Fallback Activation

Because transcript_segments is empty and the --no-whisper flag was not specified, the code reaches the Whisper block (if not transcript_segments and not args.no_whisper …). It calls load_api_key() to detect GROQ_API_KEY or OPENAI_API_KEY in the environment.

Source: [watch.py lines 39-44](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L39-L44)

Step 3: API Key Detection Returns None

The load_api_key() function in whisper.py searches environment variables and ~/.config/watch/.env for valid credentials. When neither GROQ_API_KEY nor OPENAI_API_KEY exists, it returns (None, None), causing the condition if backend and api_key: to evaluate as false and skip the transcription step.

Source: [whisper.py lines 24-31](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py#L24-L31)

Step 4: User-Facing Configuration Hint

The script prints a helpful warning explaining that Whisper cannot run without an API key and directs the user to the setup helper for configuration.

Source: [watch.py lines 55-63](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L55-L63)

Step 5: Report Generation Without Text

The final markdown report displays "Transcript: none available" while frame extraction continues if the selected detail mode requires visual analysis. The tool does not crash or halt execution.

Source: [watch.py lines 73-84](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py#L73-L84)

Practical Command Examples

Demonstrating the behavior with different command-line scenarios:

# Video without captions, no API key configured

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

# Output includes:

# - **Transcript:** none available

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

# Explicitly disabling Whisper produces the same transcript result but suppresses the API key hint

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

# Transcript shows "none available" without the configuration message

# Frame extraction continues independently of transcript availability

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

# Frames are extracted and included in the report; transcript section remains absent

Source Files Involved

The degradation behavior spans three core files in the skills/watch/scripts/ directory:

• watch.py: Main entry point orchestrating caption parsing, Whisper fallback logic, and report generation.
• whisper.py: Implements load_api_key() for credential detection and handles audio extraction when keys are present.
• download.py: Returns subtitle_path = None when yt-dlp finds no caption files, triggering the initial fallback condition.

Summary

• No crash occurs: The tool continues processing and generates a valid markdown report even when transcripts are unavailable.
• Clear user feedback: A specific warning message directs users to run python3 setup.py to configure GROQ_API_KEY or OPENAI_API_KEY.
• Visual content preserved: Frame extraction proceeds based on the selected detail level (efficient, medium, or high).
• Environment-aware detection: The system checks both shell environment variables and the ~/.config/watch/.env configuration file for credentials.

Frequently Asked Questions

What happens if a video has captions but no Whisper API key is configured?

If the video contains downloadable VTT subtitles, download.py successfully retrieves them and watch.py populates transcript_segments with the parsed text. The Whisper fallback block is skipped entirely, and the final report includes the full caption content without requiring any API credentials.

Can I suppress the API key warning while processing videos without captions?

Yes. Passing the --no-whisper flag bypasses the Whisper block entirely, which prevents the "no API key found" warning from appearing. The transcript will still show as "none available," but the configuration hint will not be printed to the console.

Where does claude-video look for Whisper API keys?

According to the source code in whisper.py, the load_api_key() function first checks for GROQ_API_KEY or OPENAI_API_KEY environment variables, then fallbacks to the ~/.config/watch/.env file created by setup.py. If neither location contains valid credentials, the transcription service remains disabled and the graceful degradation path executes.

Does frame extraction still work when no transcript is available?

Yes. Frame extraction operates independently of the transcription pipeline and depends solely on the --detail parameter setting. The tool will still extract and reference frames in the final markdown report sent to Claude, even when the transcript section displays "none available."

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