# How to Disable Whisper Transcription with `--no-whisper` in Claude-Video for Frames-Only Analysis

> Learn how to disable Whisper transcription in claude-video using the --no-whisper flag for efficient frames-only analysis. Save time and resources by bypassing audio processing.

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

---

**Use the `--no-whisper` flag when running the `watch` command to bypass all Whisper API calls and force a frames-only analysis, even for videos with audio.**

The `claude-video` repository provides a video analysis toolkit that optionally transcribes audio using OpenAI's Whisper API. When you need to analyze only visual content or avoid external API dependencies, the `--no-whisper` argument in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) disables transcription entirely while preserving frame extraction capabilities.

## How `--no-whisper` Works in the Source Code

The flag is implemented as a **store-true boolean** that defaults to `False`. When present, it short-circuits the transcription pipeline before any network requests occur.

### Command-Line Parsing in watch.py

In [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at lines 53-56, the argument is defined:

```python
parser.add_argument(
    "--no-whisper",
    action="store_true",
    help="Disable Whisper transcription even if audio is present"
)

```

This creates the `args.no_whisper` attribute that downstream logic checks before invoking the transcription backend.

### Conditional Transcription Logic

The critical bypass occurs around lines 39-47, where the script evaluates whether to call Whisper:

```python
if not transcript_segments and not args.no_whisper and video_path and meta.get("has_audio"):
    # load API key, invoke Whisper, build transcript

    ...

```

When `args.no_whisper` is **True**, this block is skipped entirely. The script proceeds directly to report generation without loading API keys or making external calls. At lines 77-83, the code emits a user-facing notice confirming that Whisper was disabled and only frames will be shown in the final output.

## The Frames-Only Workflow

Activating `--no-whisper` triggers a streamlined, visual-only pipeline:

1. **Caption fetch** – The script still attempts to download embedded subtitles via `yt-dlp`. If subtitles exist, they are used; otherwise it proceeds without transcription.
2. **Whisper skip** – The Whisper fallback in [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) is entirely omitted, eliminating external API calls and reducing latency.
3. **Report generation** – The resulting markdown contains only the frame list and a notice that no transcript is available, directing downstream agents to focus exclusively on visual content.

## When to Use `--no-whisper`

This flag is particularly valuable in these scenarios:

- **API key constraints** – You lack Whisper API credentials or want to avoid rate limits and costs.
- **Visual-only analysis** – You need scene detection, object recognition, or frame-based workflows without audio context.
- **Performance optimization** – You want to reduce network latency and token usage for downstream LLM prompts by excluding lengthy transcripts.

## Command Examples

Run frames-only analysis by appending the flag to any `watch` command:

```bash

# Basic frames-only run (no Whisper)

watch https://example.com/video.mp4 --detail balanced --no-whisper

# Combine with resolution and timestamp constraints

watch path/to/video.mov \
    --detail efficient \
    --resolution 720 \
    --timestamps 00:01:15,00:02:30 \
    --no-whisper

# Process local file without any transcription

watch ./local_video.mp4 --no-whisper

```

In each case, adding `--no-whisper` guarantees the script will **not** attempt to call the Whisper backend, even if a valid API key is present in your environment.

## Key Files in the Transcription Pipeline

Understanding the codebase structure helps when modifying or debugging the frames-only behavior:

- **[`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py)** – Main entry point that parses `--no-whisper` and controls the conditional transcription flow.
- **[`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py)** – Loads Whisper API keys and defines the `transcribe_video` helper (only invoked when `--no-whisper` is not set).
- **[`skills/watch/scripts/transcribe.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/transcribe.py)** – Parses VTT captions and formats transcripts; used for both downloaded subtitles and Whisper output.
- **[`skills/watch/scripts/config.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/config.py)** – Holds default configuration values that interact with the `--no-whisper` execution path.

## Summary

- **`--no-whisper`** is a boolean flag defined in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) that defaults to `False`.
- When enabled, it bypasses the Whisper API call at lines 39-47, forcing a frames-only workflow.
- The script still attempts to fetch embedded captions via `yt-dlp` but skips external transcription entirely.
- Use this flag to reduce costs, avoid API dependencies, or focus analysis purely on visual content.

## Frequently Asked Questions

### Does `--no-whisper` prevent downloading embedded YouTube captions?

No. The flag only disables the Whisper API fallback. The script still attempts to extract existing subtitle tracks via `yt-dlp` before checking the `--no-whisper` condition. If embedded captions exist, they will be included in the analysis.

### Can I use `--no-whisper` with the `--detail transcript` option?

While technically possible, this combination is counterproductive. The `--detail transcript` setting optimizes output for text-heavy analysis, but `--no-whisper` ensures no transcript text is generated unless embedded captions exist. For pure frames-only analysis, use `--detail efficient` or `--detail balanced` instead.

### Will the script throw an error if I have no Whisper API key and forget to use `--no-whisper`?

Yes. Without `--no-whisper`, the script attempts to load the API key from [`skills/watch/scripts/whisper.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/whisper.py) when audio is detected. If the key is missing, this will raise an authentication error. Always include `--no-whisper` when API credentials are unavailable.

### Does disabling Whisper affect frame extraction quality or resolution?

No. Frame extraction occurs independently in the preprocessing pipeline. The `--resolution` and frame sampling logic operates regardless of transcription settings, ensuring you receive the same visual quality with or without `--no-whisper`.