claude-video API Keys and Configuration: Complete Guide to config.py Setup

The claude-video project supports two Whisper transcription APIs—Groq and OpenAI—and manages configuration through a config.py file that parses a user-maintained .env file while never writing secrets to disk automatically.

The claude-video repository provides a video analysis skill that transcribes audio content using external Whisper services. Understanding which API keys are supported and how config.py orchestrates settings is essential for secure deployment. This guide breaks down the authentication options and the internal configuration architecture based on the actual source implementation.

Supported API Keys for Whisper Transcription

claude-video integrates with two transcription providers, with automatic failover between them.

Groq Whisper (Preferred)

• Environment variable: GROQ_API_KEY
• Characteristics: Cheaper pricing and faster inference
• Implementation: Checked first in whisper.py before falling back to OpenAI

OpenAI Whisper (Fallback)

• Environment variable: OPENAI_API_KEY
• Characteristics: Used only when GROQ_API_KEY is absent
• Implementation: Secondary check in whisper.py if Groq authentication unavailable

The routing logic resides in skills/watch/scripts/whisper.py. At runtime, the skill detects which key is present and routes the transcription request accordingly. No key is ever persisted to version control or generated automatically—all values must be supplied manually by the user.

How config.py Manages Configuration

The config.py module centralizes non-secret configuration for the watch skill. Located at skills/watch/scripts/config.py, it handles environment parsing, variable merging, and frame-extraction tuning.

Configuration File Location

The .env file lives in a dedicated configuration directory:

from pathlib import Path

CONFIG_DIR = Path.home() / ".config" / "watch"
CONFIG_FILE = CONFIG_DIR / ".env"

This keeps secrets outside the project directory and follows XDG Base Directory conventions.

Parsing the .env File

The read_env_file() function in config.py parses .env line-by-line with specific rules:

• Ignores blank lines and comment lines starting with #

• Strips inline comments appearing after unquoted values (e.g., WATCH_DETAIL=balanced # note)

• Preserves # characters inside quoted strings or API keys

This parsing approach prevents accidental truncation of API keys containing hash characters.

Merging Environment Variables

The get_config() function implements a two-layer configuration strategy:

1. Load and parse the .env file
2. Overlay any environment variables from the shell

Environment variables take precedence, enabling temporary overrides without editing files.

WATCH_DETAIL and Frame Extraction

The only tunable runtime setting exposed through config.py is WATCH_DETAIL, which controls how aggressively the skill extracts frames from videos:

Setting	Behavior	Frame cap
efficient	Minimal frames, fastest processing	50
balanced	Moderate frame sampling (default)	100
token-burner	Maximum frame extraction	No limit (None)
transcript	Audio-only mode, no visual frames	No limit (None)

The frame_cap(detail) function converts these string values into numeric limits consumed by the frame extraction pipeline.

Initial Setup with setup.py

When the watch skill is first installed, skills/watch/scripts/setup.py scaffolds a template .env file:

# /watch API configuration

GROQ_API_KEY=
OPENAI_API_KEY=
WATCH_DETAIL=balanced

Users must manually populate GROQ_API_KEY or OPENAI_API_KEY (or both) before the /watch command will function. The setup script never injects actual key values—it only creates the structural template.

Practical Configuration Examples

Populating the .env File

# ~/.config/watch/.env

GROQ_API_KEY=groq-your-key-here
OPENAI_API_KEY=sk-openai-fallback-key
WATCH_DETAIL=efficient

Using Shell Exports for Temporary Overrides

export GROQ_API_KEY=groq-live-key
export WATCH_DETAIL=token-burner
watch https://youtu.be/example-video

Accessing Configuration Programmatically

from skills.watch.scripts.config import get_config, frame_cap

cfg = get_config()

print(cfg["WATCH_DETAIL"])           # → 'balanced' or overridden value

print(cfg.get("GROQ_API_KEY"))       # → None (not stored in config dict)

cap = frame_cap(cfg["WATCH_DETAIL"])
print(cap)                           # → 100 for balanced, 50 for efficient

Note that get_config() returns the processed WATCH_DETAIL value and other non-sensitive options. API keys are read directly from the environment by whisper.py rather than passing through the configuration dictionary.

Security Architecture

The claude-video configuration design follows security best practices:

• No automatic secret generation—users must explicitly provide keys
• No secrets in repository—.env resides in ~/.config/watch, outside version control
• Environment variable precedence—allows ephemeral overrides without file modification
• Clean parsing—preserves special characters in API keys while stripping comments

The watch.py entry point validates key presence before invoking transcription, failing early with a clear error if neither GROQ_API_KEY nor OPENAI_API_KEY is available.

Summary

• Two API keys supported: GROQ_API_KEY (preferred, faster/cheaper) and OPENAI_API_KEY (fallback)
• Configuration location: ~/.config/watch/.env, scaffolded by setup.py with blank placeholders
• config.py responsibilities: Parse .env, merge with environment, expose WATCH_DETAIL setting, map detail levels to frame caps
• Security model: Secrets never written automatically; environment variables take precedence; keys read directly by whisper.py rather than centralized config dictionary

Frequently Asked Questions

What happens if I provide both GROQ_API_KEY and OPENAI_API_KEY?

whisper.py prioritizes Groq when both keys are present. The Groq service is checked first due to its cost and speed advantages. OpenAI serves only as a fallback mechanism.

Can I run claude-video without any API keys?

No. The watch.py entry point validates that at least one Whisper API key exists before proceeding. Without either GROQ_API_KEY or OPENAI_API_KEY, the skill exits with an authentication error.

Does WATCH_DETAIL affect transcription quality or just visual frame extraction?

WATCH_DETAIL controls only visual frame extraction aggressiveness. It does not modify audio transcription quality, bitrate, or Whisper model selection. The transcript value disables frame extraction entirely for audio-only analysis.

Why doesn't config.py return API keys in the configuration dictionary?

config.py intentionally excludes secrets from get_config() return values. API keys are accessed directly from os.environ within whisper.py. This separation prevents accidental logging or serialization of credentials while keeping the configuration surface minimal and auditable.

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