How to Force Claude-Video to Use a Specific Whisper Backend (e.g., Groq)

You can force Claude-Video to use a specific Whisper backend by passing the --whisper flag with either groq or openai to the watch command, ensuring the corresponding API key is configured in your environment.

Claude-Video is an open-source video transcription tool that leverages cloud-based Whisper APIs for speech-to-text conversion. While the application defaults to the Groq backend for faster processing, you can explicitly force Claude-Video to use a specific Whisper backend according to your preference or API availability. The backend selection logic is implemented in the Python source files within the skills/watch/scripts/ directory.

How Backend Selection Works in Claude-Video

Default Preference and Fallback Logic

According to the source code in skills/watch/scripts/whisper.py (lines 65-73), Claude-Video prefers the Groq backend by default. If a Groq API key is not found in the environment or configuration files, the system falls back to OpenAI. This automatic selection ensures optimal performance when Groq is available while maintaining functionality through OpenAI as a secondary option.

Command-Line Argument Parsing

The main entry point in skills/watch/scripts/watch.py defines the --whisper argument between lines 58-62. When you invoke the watch command, the value supplied to this flag is passed directly to the load_api_key function (lines 40-44):

backend, api_key = load_api_key(args.whisper)

The load_api_key function restricts candidate backends to your specific request, validating that the corresponding API key exists before proceeding with transcription.

Forcing a Specific Backend via the CLI

To override the default behavior and force Claude-Video to use a specific Whisper backend, append the --whisper flag followed by your preferred provider name.

Force Groq backend:

watch https://www.youtube.com/watch?v=example \
  --whisper groq

Force OpenAI backend:

watch https://www.youtube.com/watch?v=example \
  --whisper openai

If the requested backend's API key is missing, Claude-Video prints a helpful error message and aborts the Whisper step (see error handling in watch.py, lines 55-60).

Configuring API Keys for Your Chosen Backend

Before forcing a specific backend, you must ensure the corresponding API key is available. Claude-Video searches for credentials in environment variables or in the user-specific configuration file at ~/.config/watch/.env.

Configure your Groq API key:

echo "GROQ_API_KEY=your_groq_key" >> ~/.config/watch/.env

Configure your OpenAI API key:

echo "OPENAI_API_KEY=your_openai_key" >> ~/.config/watch/.env

The skills/watch/scripts/setup.py file provides helper utilities for generating this configuration file during initial installation.

Direct Script Execution for Testing

For debugging or development purposes, you can invoke the Whisper module directly using the --backend parameter. This bypasses the main watch.py entry point while achieving the same backend restriction:

python -m skills.watch.scripts.whisper \
  path/to/video.mp4 \
  --backend groq

This approach is useful when testing transcription functionality without processing the full video pipeline.

Summary

• Claude-Video defaults to Groq for Whisper transcription but automatically falls back to OpenAI if Groq credentials are unavailable.
• Use the --whisper flag with the watch command to force a specific backend (either groq or openai).
• The backend selection logic resides in skills/watch/scripts/whisper.py, while argument parsing occurs in skills/watch/scripts/watch.py.
• Ensure your chosen backend's API key is configured in ~/.config/watch/.env or as an environment variable before specifying the backend.
• For advanced testing, run whisper.py directly with the --backend flag to isolate transcription behavior.

Frequently Asked Questions

What happens if I specify a backend but don't have the API key configured?

Claude-Video validates API key availability immediately after you specify a backend via the --whisper flag. If the corresponding key is missing from your environment or ~/.config/watch/.env file, the application prints a helpful hint indicating which key is required and aborts the transcription process (as implemented in watch.py lines 55-60).

Can I switch backends without editing configuration files?

Yes. You can switch between Groq and OpenAI on a per-command basis by simply changing the value passed to the --whisper flag. Since the backend selection is determined at runtime through command-line arguments, no configuration file modifications are necessary once both API keys are stored in your environment.

Why does Claude-Video default to Groq instead of OpenAI?

The source code in skills/watch/scripts/whisper.py (lines 65-73) implements a preference for Groq due to its typically faster inference speeds and lower latency for Whisper transcription tasks. This default optimizes for performance while maintaining OpenAI as a reliable fallback when Groq credentials are not present.

Is there a way to use a local Whisper model instead of Groq or OpenAI?

Based on the current implementation in the claude-video repository, the transcription functionality is specifically designed for cloud-based Groq and OpenAI APIs. The load_api_key function and backend validation logic in whisper.py do not currently support local Whisper model execution, though the modular structure would allow for future extension.

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