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

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 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 at lines 53-56, the argument is defined:

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:

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

# 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 – Main entry point that parses --no-whisper and controls the conditional transcription flow.
• 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 – Parses VTT captions and formats transcripts; used for both downloaded subtitles and Whisper output.
• 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 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 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.

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