# How to Disable the Transcription Fallback Using the `--no-whisper` Flag in Claude-Video

> Learn how to disable the transcription fallback in Claude-Video using the --no-whisper flag. Force frames-only output and skip Whisper API when no captions exist.

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

---

**Add the `--no-whisper` flag when running the `watch` script to skip the Whisper API fallback and force frames-only output when no embedded captions are available.**

Claude-Video is an open-source tool that extracts subtitles from videos using a two-stage pipeline. When you disable the transcription fallback using the `--no-whisper` flag, the tool processes only native embedded captions and bypasses the Whisper API entirely. This guide explains the implementation details in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) and shows exactly how to use this option.

## How the Transcription Fallback Works

Claude-Video attempts to obtain subtitles through two distinct sources:

1. **Primary source**: yt-dlp downloads embedded captions directly from the video.
2. **Fallback source**: If no captions exist, the script invokes the Whisper API (or a local Whisper model) to generate a transcription.

The fallback is optional. When disabled, the workflow short-circuits at the decision point in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) line 239, producing frames-only output when native captions are unavailable.

## Using the `--no-whisper` Flag

### Command Line Usage

Pass `--no-whisper` as a boolean argument to the `watch` entry point:

```bash

# Process a YouTube URL without Whisper fallback

python -m skills.watch.scripts.watch "https://youtu.be/abc123" --no-whisper

# Process a local video file

python -m skills.watch.scripts.watch "/path/to/video.mp4" --no-whisper

```

### What Happens When You Disable Whisper

When `--no-whisper` is present, the script behavior changes at three specific points in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py):

- **Line 239**: The condition `if not transcript_segments and not args.no_whisper` evaluates to `False`, bypassing the Whisper invocation block entirely.
- **Line 262**: The script prints a hint that Whisper is unavailable and suggests re-running with a proper API key if you want transcription.
- **Line 380**: Final messaging reports that "Captions were missing and the Whisper fallback was unavailable," confirming the bypass occurred.

## Implementation Details

### Argument Parsing

The flag is defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at line 55 as a boolean argument:

```python

# From skills/watch/scripts/watch.py

parser.add_argument(
    '--no-whisper',
    action='store_true',
    help="Disable Whisper fallback. Report frames-only if no captions available."
)

```

According to the repository source code, this argument is stored in the `args` namespace as `no_whisper` (boolean).

### The Bypass Logic

The critical guard clause appears in the transcript acquisition flow:

```python

# Conceptual flow from watch.py line 239

if not transcript_segments and not args.no_whisper:
    # Invoke Whisper API or local model

    transcript_segments = generate_whisper_transcription(video_path)

```

When `args.no_whisper` is `True`, the script skips the Whisper block and proceeds with an empty `transcript_segments` list, resulting in frames-only analysis.

## Testing and Validation

The test suite validates this behavior in [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py) at line 18. Run the specific test case to verify the flag functionality:

```bash
python -m pytest tests/test_watch.py -k no_whisper

```

### Programmatic Invocation

You can also invoke the functionality programmatically using the same argparse namespace:

```python
from pathlib import Path
from skills.watch.scripts.watch import main, parse_args

args = parse_args([
    str(Path("sample_clip.mp4")),
    "--no-whisper"
])
exit_code = main(args)  # Returns 0 on success, skips Whisper entirely

```

## 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) at line 55 as a boolean argument that disables the Whisper transcription fallback.
- When enabled, the guard clause at line 239 prevents Whisper API invocation, resulting in frames-only output when no embedded captions exist.
- User feedback appears at lines 262 and 380, informing you that captions were missing and the fallback was intentionally skipped.
- The test harness in [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py) demonstrates proper invocation patterns for validating this behavior.

## Frequently Asked Questions

### What happens if I use `--no-whisper` and no captions exist?

The script outputs frames-only analysis without transcription. According to the implementation in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at line 380, you will see the message "Captions were missing and the Whisper fallback was unavailable," and the tool will proceed with visual frame extraction only.

### Can I use `--no-whisper` with local Whisper models?

Yes. The flag bypasses all Whisper invocations regardless of whether you are using the OpenAI API or a local model. As implemented in [`watch.py`](https://github.com/bradautomates/claude-video/blob/main/watch.py) line 239, the check `if not args.no_whisper` prevents any Whisper code path from executing, whether cloud-based or local.

### Where is the `--no-whisper` argument defined in the source code?

The argument is defined in [`skills/watch/scripts/watch.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/watch.py) at line 55 with the help text "Disable Whisper fallback. Report frames-only if no captions available." The setup documentation in [`skills/watch/scripts/setup.py`](https://github.com/bradautomates/claude-video/blob/main/skills/watch/scripts/setup.py) lines 40-44 also notes that the Whisper fallback is optional and describes the OpenAI key configuration.

### How do I test that the `--no-whisper` flag works correctly?

Run the specific test filter in the pytest suite: `python -m pytest tests/test_watch.py -k no_whisper`. The test harness at line 18 of [`tests/test_watch.py`](https://github.com/bradautomates/claude-video/blob/main/tests/test_watch.py) demonstrates how the flag is passed to the script and validates that Whisper is not invoked when the flag is present.