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

> Discover what happens in claude-video when a video lacks captions and Whisper API key. Gracefully degraded processing skips transcription, warns, and reports frames with no transcript.

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

---

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

```bash

# 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

```

```bash

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

```

```bash

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