How to Use the Transcribe Command with Groq or OpenAI Whisper in Agent Reach

Agent Reach's transcribe command automatically selects Groq's free whisper-large-v3 model and falls back to OpenAI's whisper-1 when needed.

Agent Reach is a Python-based CLI and library designed to give AI agents unified access to internet platforms. The transcribe command converts any audio or video URL—or local media file—into text using Whisper-compatible APIs. According to the Panniantong/Agent-Reach source code, the implementation prioritizes Groq for cost-free transcription with seamless OpenAI fallback for reliability.

Setting Up API Keys for the Transcribe Command

Before running the transcribe command, you must configure at least one provider API key in ~/.agent-reach/config.yaml.

# Create the config directory and file

mkdir -p ~/.agent-reach
cat > ~/.agent-reach/config.yaml << 'EOF'
groq_api_key: "gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
openai_api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
EOF

The Config class in agent_reach/config.py retrieves these keys at runtime. If no valid provider is configured, the system raises NoProviderConfigured—a custom exception defined in agent_reach/transcribe.py.

CLI Usage: Transcribe Command with Groq or OpenAI Whisper

Basic Transcription with Auto Provider Selection

agent-reach transcribe "https://youtu.be/dQw4w9WgXcQ"

This command executes the following pipeline as implemented in agent_reach/transcribe.py:

1. URL validation – _assert_safe_public_url ensures the source is public-only (prevents SSRF attacks)
2. Media download – download_audio invokes yt-dlp to fetch the audio stream
3. Compression – compress_audio re-encodes to mono 16kHz, 32kbps m4a to fit Whisper's 25 MiB limit
4. Chunking – Files exceeding 24 MiB are split into ≤10-minute segments via ffmpeg
5. Transcription – _transcribe_with_fallback tries Groq first, then OpenAI

The _cmd_transcribe function in agent_reach/cli.py handles argument parsing and forwards to this engine.

Force Specific Provider Selection

# Skip Groq and use OpenAI directly

agent-reach transcribe "https://example.com/podcast.mp3" --provider openai -o transcript.txt

The --provider flag accepts three values:

• auto (default): Groq → OpenAI fallback order
• groq: Groq only, no fallback
• openai: OpenAI only, no fallback

The _provider_order function in transcribe.py expands auto to ["groq", "openai"] for sequential retry.

Python Library: Transcribe with Groq or OpenAI Whisper Programmatically

Simple API Call

from agent_reach.transcribe import transcribe, TranscribeError

try:
    text = transcribe(
        "https://v.redd.it/abcd1234",      # any public media URL

        provider="auto",                   # Groq → OpenAI fallback

    )
    print(text)
except TranscribeError as exc:
    print(f"Transcription failed: {exc}")

The transcribe function in agent_reach/transcribe.py wraps the full pipeline: download, compress, chunk, and transcribe with fallback logic.

Advanced: Custom Chunk Size and Direct Chunk Processing

from pathlib import Path
from agent_reach.transcribe import (
    download_audio,
    compress_audio,
    chunk_audio,
    transcribe_chunk,
)

# Download and prepare media

src = download_audio("https://example.com/long-audio.mp3", Path("/tmp"))
compressed = compress_audio(src, Path("/tmp"))

# Split into 5-minute chunks instead of default 10-minute

chunks = chunk_audio(compressed, Path("/tmp"), segment_seconds=300)

# Transcribe each chunk with explicit provider

texts = [transcribe_chunk(c, "groq") for c in chunks]
full_transcript = "\n".join(texts)
print(full_transcript)

The transcribe_chunk function performs the actual HTTP POST to the provider endpoint using requests, with the appropriate bearer token from your config.

Provider Configuration and Fallback Architecture

The PROVIDERS dictionary at the top of agent_reach/transcribe.py defines endpoint and model mappings:

Provider	Model	Endpoint
Groq	whisper-large-v3	https://api.groq.com/openai/v1/audio/transcriptions
OpenAI	whisper-1	https://api.openai.com/v1/audio/transcriptions

When _transcribe_with_fallback encounters a failure from Groq—quota exhaustion, rate limiting, or service error—it automatically retries with OpenAI. This resilience is hardcoded for provider="auto".

Required External Dependencies

The transcribe command requires these binaries on your system:

• yt-dlp – Media download from YouTube and other platforms
• ffmpeg – Audio re-encoding and chunking

Verify installation with:

agent-reach doctor

The doctor.py module diagnoses missing dependencies before you attempt transcription.

Error Handling for the Transcribe Command

Agent Reach implements granular exceptions in transcribe.py:

Exception	Trigger
NoProviderConfigured	Missing API keys for requested provider
MissingDependency	yt-dlp or ffmpeg not found in PATH
TranscribeError	General transcription failure (network, API error, invalid source)
UnsafeUrlError	URL failed public-only safety validation

Wrap your calls in try/except TranscribeError to handle all failure modes gracefully.

Summary

• The transcribe command in Agent Reach prioritizes Groq's free whisper-large-v3 with automatic OpenAI whisper-1 fallback.
• Configure API keys in ~/.agent-reach/config.yaml before use.
• The CLI entry point is _cmd_transcribe in agent_reach/cli.py; the engine lives in agent_reach/transcribe.py.
• The pipeline handles download (yt-dlp), compression (ffmpeg), chunking, and provider failover automatically.
• Use provider="auto" for resilience, or specify "groq" or "openai" explicitly for predictable costs.

Frequently Asked Questions

Do I need both Groq and OpenAI API keys to use the transcribe command?

No. You only need at least one configured provider. Configure Groq for free transcription, OpenAI as a paid backup, or both for automatic failover. If neither is configured, Agent Reach raises NoProviderConfigured before attempting any download.

Why does my transcription fail with "MissingDependency: ffmpeg"?

The transcribe command requires ffmpeg for audio compression and chunking. Install it system-wide (apt install ffmpeg, brew install ffmpeg, etc.) and verify with agent-reach doctor. The compress_audio and chunk_audio functions in transcribe.py shell out to ffmpeg directly.

How does Agent Reach handle large files that exceed Whisper's 25 MiB limit?

Files are automatically compressed to mono 16kHz, 32kbps m4a. If still over 24 MiB, chunk_audio splits them into segments (default 10 minutes, configurable) using ffmpeg -f segment. Each chunk is transcribed independently and concatenated with newlines in the final output.

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