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

> Learn how claude-video handles videos without captions or a Whisper API key. Discover graceful degradation, skipping transcription, and error hints for a smoother workflow.

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

---

**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`](https://github.com/bradautomates/claude-video/blob/main/watch.py) attempts to parse any available VTT subtitle files via the download module. When [`download.py`](https://github.com/bradautomates/claude-video/blob/main/download.py) returns `subtitle_path = None`, `transcript_segments` stays empty, triggering the fallback logic.

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

```bash

# 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

```

```bash

# 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

```

```bash

# 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`](https://github.com/bradautomates/claude-video/blob/main/watch.py)**: Main entry point orchestrating caption parsing, Whisper fallback logic, and report generation.
- **[`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py)**: Implements `load_api_key()` for credential detection and handles audio extraction when keys are present.
- **[`download.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/download.py) successfully retrieves them and [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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`](https://github.com/bradautomates/claude-video/blob/main/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."