What Does `--no-whisper` Do to Transcripts in Claude Video?

The --no-whisper flag disables the Whisper speech-to-text fallback, so transcripts appear only when embedded captions exist; otherwise the report shows "none available."

Claude Video is an open-source tool that analyzes video content and generates structured markdown reports. Transcripts are a core component of these reports, but their availability depends on your configuration. This guide explains exactly how the --no-whisper flag controls transcript generation based on the source code in bradautomates/claude-video.

How Transcript Generation Works by Default

The watch command in skills/watch/scripts/watch.py attempts to build transcripts through a two-stage pipeline:

1. Captions first — Parses embedded VTT/SRT subtitles using parse_vtt() from transcribe.py
2. Whisper fallback — Calls the remote speech-to-text service if no captions exist

The default behavior ensures maximum transcript coverage: local captions when available, AI transcription when needed.

What --no-whisper Changes

Adding --no-whisper removes stage 2 entirely. The relevant conditional in watch.py is:

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)
    ...

When args.no_whisper is True, this condition fails immediately. The script never:

• Loads API keys via load_api_key()
• Invokes the Whisper backend
• Fetches remote transcripts

Fallback Behavior When Both Sources Fail

If neither captions nor Whisper produces a transcript, the user sees a clear diagnostic message:

else:
    setup_py = SCRIPT_DIR / "setup.py"
    print(
        "_No transcript available — proceed with frames only. "
        "Captions were missing and the Whisper fallback was unavailable "
        "(no API key set, or `--no-whisper` was used). "
        f"Run `python3 {setup_py}` to enable Whisper, then re-run._",
        file=sys.stderr,
    )

The report still generates, but the transcript section reads:

- **Transcript:** none available

Use Cases for --no-whisper

Scenario	Why Use --no-whisper
Privacy-sensitive content	Avoid sending audio to remote services
Cost control	Skip API calls when transcripts aren't critical
Caption-only workflow	Rely strictly on embedded subtitles
Offline/air-gapped environments	No external network calls required
Faster processing	Eliminate network latency from transcription

Practical Examples

Run Without Whisper (Frames Only)

python -m skills.watch.scripts.watch https://example.com/video.mp4 --no-whisper

Result: Video frames analyzed, transcript omitted unless captions present.

Run With Whisper Enabled (Default)

python -m skills.watch.scripts.watch https://example.com/video.mp4

Result: If no captions exist, Whisper transcribes audio. Report shows:

- **Transcript:** 27 segments (via whisper (groq))

Key Source Files

Understanding these modules clarifies how --no-whisper propagates through the system:

• skills/watch/scripts/watch.py — Main orchestrator that parses --no-whisper and routes transcript decisions
• skills/watch/scripts/transcribe.py — VTT/SRT caption parsing utilities
• skills/watch/scripts/whisper.py — API key loading and Whisper backend interface
• skills/watch/scripts/setup.py — Creates local .env with Whisper credentials

Summary

• --no-whisper disables the Whisper speech-to-text fallback in Claude Video's watch command
• Transcripts appear only from embedded captions when this flag is active
• The report generates successfully regardless, with a clear "none available" notice if needed
• Use this flag for privacy, cost, speed, or offline constraints where AI transcription is undesirable

Frequently Asked Questions

What happens if a video has captions and I use --no-whisper?

Captions are parsed normally. The flag only affects the Whisper fallback, not embedded subtitle extraction. You'll receive a complete transcript from the VTT/SRT source.

Can I re-enable Whisper after using --no-whisper?

Yes. Remove the flag from your command, or run python3 skills/watch/scripts/setup.py to configure API credentials if you haven't already. No permanent configuration is changed by using --no-whisper.

Does --no-whisper affect frame extraction or other report sections?

No. Frame analysis, metadata extraction, and markdown generation proceed unchanged. Only the transcript source pipeline is modified—specifically the conditional block in watch.py that calls load_api_key() and the Whisper backend.

Why would captions exist but Whisper still run without --no-whisper?

This shouldn't occur in normal operation. The logic checks if not transcript_segments before attempting Whisper, so existing caption-derived segments satisfy the condition and skip the fallback. If both run, inspect whether parse_vtt returned empty segments due to malformed caption files.

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