# How the `--no-whisper` Option Disables Transcription in Claude Video

> Learn how the --no-whisper option in Claude Video prevents Whisper API transcription. Discover how to force reliance on existing subtitles or get frames-only output.

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

---

**The `--no-whisper` flag prevents the `watch` skill from falling back to the Whisper API when no embedded captions are found, forcing it to rely solely on existing subtitles or return frames-only output.**

In the `bradautomates/claude-video` repository, the `watch` skill extracts visual frames from videos and optionally generates transcripts. The `--no-whisper` command-line option provides a way to disable the external transcription service entirely, which is useful when API keys are unavailable or when you want to avoid network calls.

## Where `--no-whisper` Is Defined

The flag is implemented in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 53-56. When present on the command line, the argument parser sets `args.no_whisper` to `True`.

This boolean value acts as a safety switch throughout the transcription pipeline, specifically guarding the fallback logic that invokes external AI services.

## How It Disables the Whisper Fallback

The `watch` skill processes transcription in two distinct stages:

1. **Caption extraction** – If the video has embedded subtitles, `yt-dlp` fetches them and `parse_vtt` parses the data.
2. **Whisper API fallback** – When no captions exist, the skill normally calls the Whisper API via Groq or OpenAI.

The `--no-whisper` option interrupts the second stage. After attempting to load captions, the code in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) evaluates the following condition:

```python
if not transcript_segments and not args.no_whisper and video_path and meta.get("has_audio"):
    backend, api_key = load_api_key(args.whisper)
    # ... API call logic ...

```

When `args.no_whisper` is `True`, the condition `not args.no_whisper` evaluates to `False`, short-circuiting the block. Consequently, the script skips the `load_api_key` and `transcribe_video` calls entirely, even if the video contains an audio track.

## User Feedback When Transcription Is Skipped

If captions are missing and `--no-whisper` is active, the script proceeds with a frames-only analysis. According to the source code around lines 77-84 in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py), the user receives a clear message indicating that transcription was omitted because Whisper was disabled or because no API key was configured.

## Practical Usage Examples

Run the `watch` skill normally to try captions first, then fall back to Whisper:

```bash
watch https://youtu.be/abcdEFGH

```

Disable the Whisper fallback to use only existing captions or receive frames-only output:

```bash
watch https://youtu.be/abcdEFGH --no-whisper

```

Force a specific Whisper backend when transcription is allowed (requires API key):

```bash
watch https://youtu.be/abcdEFGH --whisper openai

```

## Summary

- The `--no-whisper` flag is defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) (lines 53-56) and sets `args.no_whisper` to `True`.
- It short-circuits the Whisper API fallback by evaluating `not args.no_whisper` in the transcription guard condition.
- **Caption extraction** continues to work normally; only the external API call is blocked.
- When transcription is skipped, the script generates a frames-only report with an explanatory message (lines 77-84).
- The behavior is tested in [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py), which verifies the flag properly disables the Whisper invocation.

## Frequently Asked Questions

### Does `--no-whisper` disable caption extraction?

No. The flag only blocks the Whisper API fallback. If the video contains embedded subtitles, the skill still extracts and parses them using `parse_vtt` from [`transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/transcribe.py).

### What happens if I use `--no-whisper` but the video has no captions?

The script skips transcription entirely and generates a frames-only analysis. You will see a message explaining that transcription was omitted because Whisper was disabled or because no API key was configured.

### Where is the `--no-whisper` logic tested?

The behavior is verified in [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py), which invokes the script with the `--no-whisper` flag to ensure the Whisper fallback is properly bypassed.

### Can I still use a specific Whisper backend without the `--no-whisper` flag?

Yes. Use the `--whisper` option followed by the backend name (e.g., `--whisper openai` or `--whisper groq`). This requires a valid API key loaded via the `load_api_key` function in [`whisper.py`](https://github.com/bradautomates/claude-video/blob/main/whisper.py).