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

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 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 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:

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

• 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 at line 55 as a boolean argument:

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

# 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 at line 18. Run the specific test case to verify the flag functionality:

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

Programmatic Invocation

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

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 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 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 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 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 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 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 demonstrates how the flag is passed to the script and validates that Whisper is not invoked when the flag is present.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}