How to Force a Specific Whisper Backend Using the `--whisper` Flag in Claude-Video

You can force Claude-Video to use a specific Whisper transcription backend by appending --whisper groq or --whisper openai to your watch command, overriding the default automatic selection logic.

When working with the bradautomates/claude-video repository, the video-watch skill automatically falls back to Whisper transcription when native captions are unavailable. While the tool defaults to Groq when both API keys are present, you can force a specific Whisper backend using the --whisper flag to control costs, latency, or availability preferences.

Supported Whisper Backends

The --whisper flag accepts two distinct backend options, each utilizing different API endpoints and model variants according to the source code in skills/watch/scripts/whisper.py (lines 65-71):

Groq Whisper (groq): Uses the whisper-large-v3 model via the Groq API endpoint at https://api.groq.com/openai/v1/audio/transcriptions. This backend is typically faster and more cost-effective for transcription tasks.

OpenAI Whisper (openai): Uses the whisper-1 model via the OpenAI API endpoint at https://api.openai.com/v1/audio/transcriptions. This serves as the fallback option when Groq credentials are unavailable or when you specifically require OpenAI's implementation.

Command-Line Usage Examples

To force a specific backend, append the --whisper flag followed by your preferred provider name when running the watch command. The flag is parsed in skills/watch/scripts/watch.py (lines 58-62) and passed to the load_api_key() function.

Force Groq backend (preferred for speed and cost):

watch "https://www.youtube.com/watch?v=abc123" --whisper groq

Force OpenAI backend:

watch "/path/to/local/video.mp4" --whisper openai

Disable Whisper entirely to process frames only:

watch "https://vimeo.com/123456" --no-whisper

Internal Backend Selection Logic

According to the implementation in skills/watch/scripts/whisper.py, the load_api_key() function handles backend selection based on the flag value (lines 65-71). When you specify --whisper groq or --whisper openai, the function validates the corresponding API key environment variable and configures the appropriate endpoint.

The CLI argument is defined in skills/watch/scripts/watch.py (lines 58-62), where the --whisper option is captured via argparse and forwarded to load_api_key(). If the requested backend's API key is missing, the script aborts with a descriptive error message.

Default behavior (when the flag is omitted) prioritizes Groq if both GROQ_API_KEY and OPENAI_API_KEY are present, falling back to OpenAI only when only the OpenAI key is available, as documented in skills/watch/SKILL.md (lines 150-152) and README.md (lines 198-200).

Summary

• Use --whisper groq to force transcription via Groq's whisper-large-v3 endpoint.
• Use --whisper openai to force OpenAI's whisper-1 endpoint.
• The default logic prefers Groq when both API keys are configured.
• The load_api_key() function in skills/watch/scripts/whisper.py implements the selection logic, while skills/watch/scripts/watch.py handles CLI parsing.
• For frames-only analysis without audio transcription, use --no-whisper.

Frequently Asked Questions

What happens if I omit the --whisper flag?

If you omit the flag, the system automatically selects the backend based on available API keys. As implemented in skills/watch/scripts/whisper.py (lines 65-71), it first checks for Groq availability, defaulting to OpenAI only if Groq credentials are absent. This ensures optimal performance without manual intervention.

Can I use the --whisper flag without configuring API keys?

No. The load_api_key() function validates that the specified backend's API key exists in your environment or .env file. If you force a backend without the corresponding key (e.g., --whisper groq without GROQ_API_KEY), the script terminates with an error message indicating the missing credential.

How do I completely disable Whisper transcription?

To skip audio transcription and analyze only video frames, use the --no-whisper flag instead. This bypasses the load_api_key() function entirely and processes visual content only, which is useful when audio analysis is unnecessary or when you want to avoid API costs.

Which backend offers better performance?

Groq generally provides faster inference and lower costs for whisper-large-v3 compared to OpenAI's whisper-1. However, availability and rate limits may vary. If you experience latency issues with one provider, forcing the alternative backend via --whisper allows you to optimize for your specific infrastructure constraints.

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