Agent-Reach Transcribe Feature: Groq Whisper vs OpenAI Whisper Implementation Guide

TLDR: Agent-Reach provides a unified transcription pipeline in agent_reach/transcribe.py that routes audio to Groq Whisper by default, with automatic fallback to OpenAI Whisper, requiring only API key configuration in ~/.agent-reach/config.yaml.

The Panniantong/Agent-Reach repository offers a provider-agnostic transcription system that converts audio from YouTube videos or local files into text using either Groq's or OpenAI's Whisper implementations. This article examines the architectural differences between these providers and demonstrates how to configure and invoke the Agent-Reach transcribe feature through both Python and CLI interfaces.

Provider Architecture and Configuration

The PROVIDERS Registry

At the core of the system lies the PROVIDERS dictionary defined in agent_reach/transcribe.py. This registry maps provider identifiers to their respective API endpoints, model names, and configuration key requirements:

PROVIDERS = {
    "groq": {
        "endpoint": "https://api.groq.com/openai/v1/audio/transcriptions",
        "model": "whisper-large-v3",
        "key_field": "groq_api_key",
    },
    "openai": {
        "endpoint": "https://api.openai.com/v1/audio/transcriptions",
        "model": "whisper-1",
        "key_field": "openai_api_key",
    },
}

Each entry specifies the HTTP endpoint for audio transcriptions, the specific model identifier (whisper-large-v3 for Groq, whisper-1 for OpenAI), and the configuration key name used to retrieve the API token.

Configuration Requirements

The configuration system (agent_reach/config.py) stores user secrets in ~/.agent-reach/config.yaml. The Agent-Reach transcribe feature requires one or both of these keys:

• groq_api_key – Enables Groq Whisper access
• openai_api_key – Enables OpenAI Whisper access

The FEATURE_REQUIREMENTS map in the configuration module validates that at least one provider is properly configured before allowing transcription operations. The Config.is_configured helper method checks for these prerequisites, enabling the YouTube channel to advertise transcription capability only when ready.

Audio Processing Pipeline

Download and Compression

When processing URLs (particularly YouTube videos), the download_audio function utilizes yt-dlp to fetch M4A files. The compress_audio function then normalizes audio to mono, 16 kHz, 32 kbps, guaranteeing that files remain under the Whisper 25 MiB limit. This compression step is critical for subsequent API transmission.

Chunking Strategy

For audio exceeding the 25 MiB limit after compression, the chunk_audio function splits files into segments defined by CHUNK_SECONDS = 600 (10 minutes). Each chunk is processed independently by transcribe_chunk, with results concatenated using newline characters to form the complete transcript.

Provider Selection and Fallback Logic

The public transcribe(source, *, provider="auto", …) function accepts a provider argument that determines routing behavior:

• provider="auto" (default): Uses the internal _provider_order list ["groq", "openai"], attempting Groq first due to its free tier and fast inference, then falling back to OpenAI if needed.
• Explicit selection: Passing "groq" or "openai" bypasses the order and targets that specific service.

The _transcribe_with_fallback internal method implements the retry logic. If a provider fails (e.g., returns a 429 error), the system silently attempts the next configured provider. If no API keys are configured, the NoProviderConfigured exception is raised immediately to prevent unnecessary audio downloads. Other specific exceptions include TranscribeError for API failures and MissingDependency for missing ffmpeg or yt-dlp binaries.

Usage Examples

Python API

Configure Groq Whisper explicitly:

from agent_reach import transcribe as tr
from agent_reach.config import Config

cfg = Config()
cfg.set("groq_api_key", "YOUR_GROQ_KEY")

text = tr.transcribe(
    "https://youtu.be/abc123",
    provider="groq",
    config=cfg,
)
print(text)

Utilize automatic fallback to OpenAI:

cfg.set("openai_api_key", "YOUR_OPENAI_KEY")

# With Groq unavailable, auto mode will try OpenAI directly

text = tr.transcribe("my_podcast.m4a", provider="auto", config=cfg)

Handle large files with automatic chunking:

# Files >24 MiB automatically split into 10-minute chunks

transcript = tr.transcribe("large_audio.wav", provider="auto", config=cfg)

CLI Interface

Install optional dependencies:

pip install "agent-reach[transcribe]"

Configure your preferred provider:

agent-reach configure groq-key YOUR_GROQ_KEY

# or

agent-reach configure openai-key YOUR_OPENAI_KEY

Transcribe content:

# Explicit Groq usage

agent-reach transcribe https://youtu.be/abc123 --provider groq

# Auto-fallback (Groq → OpenAI)

agent-reach transcribe https://youtu.be/abc123

Key Source Files

• agent_reach/transcribe.py – Core orchestration including download, compression, chunking, provider routing, and fallback logic.
• agent_reach/config.py – YAML-based configuration management, environment-variable overrides, and feature-requirement mapping.
• agent_reach/channels/youtube.py – YouTube channel implementation that checks for yt-dlp, ffmpeg, and Whisper readiness before delegating to the transcribe orchestrator.
• agent_reach/cli.py – Command-line interface entry point exposing the transcribe sub-command and configuration helpers.
• tests/test_transcribe.py – Test suite validating provider routing, fallback logic, and chunking workflows.

Summary

• Agent-Reach transcribe feature uses a unified transcribe() function that abstracts Groq Whisper and OpenAI Whisper behind a single interface.
• The PROVIDERS registry in agent_reach/transcribe.py defines endpoint URLs, model names (whisper-large-v3 vs whisper-1), and required API keys.
• Automatic fallback follows the order Groq → OpenAI when provider="auto" is specified, with _transcribe_with_fallback handling retry logic.
• The chunking system automatically processes files larger than 25 MiB by splitting them into 10-minute segments via chunk_audio.
• Configuration requires storing groq_api_key or openai_api_key in ~/.agent-reach/config.yaml, validated through Config.is_configured.

Frequently Asked Questions

How does Agent-Reach decide which Whisper provider to use?

When provider="auto" is specified (the default), Agent-Reach consults the internal _provider_order list ["groq", "openai"] and attempts Groq first. If Groq returns an error or lacks configuration, _transcribe_with_fallback automatically retries with OpenAI. You can override this by passing provider="groq" or provider="openai" explicitly.

What audio file limits does the transcribe feature enforce?

The system enforces a 25 MiB limit per API request. The compress_audio function normalizes audio to mono, 16 kHz, 32 kbps to stay under this limit. If compression alone is insufficient, chunk_audio splits files into 10-minute segments using CHUNK_SECONDS = 600, processing each chunk separately and concatenating results.

Why does Agent-Reach require both groq_api_key and openai_api_key?

Neither key is strictly required individually; you only need at least one configured provider to use the transcription feature. However, configuring both enables the fallback mechanism, allowing the system to automatically switch to OpenAI Whisper if Groq reaches rate limits or experiences outages. The NoProviderConfigured exception prevents execution when neither key is present.

Where does Agent-Reach store configuration and API keys?

According to the source code in agent_reach/config.py, the system stores secrets in ~/.agent-reach/config.yaml. The Config class manages these values, supporting direct file edits or programmatic setting via cfg.set("groq_api_key", "value"). The FEATURE_REQUIREMENTS map validates that required keys exist before attempting expensive audio downloads.

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