How the Transcribe Command Works with Groq and OpenAI in Agent Reach

The transcribe command in Agent Reach converts audio to text using a provider-agnostic pipeline that automatically tries Groq's free whisper-large-v3 model first, then falls back to OpenAI's whisper-1 if authentication fails or errors occur.

Agent Reach is an open-source automation framework that simplifies audio transcription through a unified interface supporting multiple AI providers. The transcribe command—available both as a CLI tool and a Python API—handles everything from audio downloading and compression to provider authentication and error recovery. This article examines the implementation details in agent_reach/transcribe.py and agent_reach/cli.py to show how the system orchestrates Groq and OpenAI Whisper services.

Architecture of the Transcribe Pipeline

The transcription workflow consists of three distinct layers: the CLI parser, the public Python API, and the provider-specific HTTP handlers.

CLI Entry Point

User interaction begins in agent_reach/cli.py, where the _cmd_transcribe function (lines 1135–1142) parses command-line arguments and forwards them to the core library. This thin wrapper validates that the source path or URL exists before delegating to the transcription engine.

Core API Function

The public interface lives in agent_reach/transcribe.py via the transcribe(source, *, provider="auto", …) function (lines 8–13). This orchestrator manages the entire lifecycle: input validation, audio preprocessing, provider selection, and result aggregation. It returns a single string containing the complete transcript.

Provider Configuration

A static PROVIDERS dictionary (lines 32–43) defines the supported backends. Each entry maps the provider name to its API endpoint, model identifier (whisper-large-v3 for Groq, whisper-1 for OpenAI), and the configuration key used to retrieve API tokens from the system's config store.

Provider Selection and Automatic Fallback

Agent Reach eliminates provider lock-in through an intelligent routing system that prioritizes cost-effective options while ensuring reliability.

The Auto-Detection Logic

The helper _provider_order(provider) (lines 49–55) determines execution order. When provider="auto" (the default), it returns ["groq", "openai"], ensuring Groq's free tier is attempted first. If the user specifies a provider explicitly (e.g., provider="openai"), the function returns a single-item list containing only that provider, bypassing the fallback mechanism.

Chunk-Level Fallback Strategy

For each audio segment, _transcribe_with_fallback(chunk, order, config) (lines 306–318) iterates through the ordered provider list. It calls transcribe_chunk for each candidate until one succeeds. If all providers return errors, the function raises the last encountered TranscribeError, ensuring the user receives actionable diagnostic information.

The actual HTTP request occurs in transcribe_chunk, which constructs a multipart form-data POST containing the audio bytes, model identifier, and a request for plain-text output. The function retrieves API keys via the configuration system and validates that responses return HTTP 2xx status codes before extracting the transcript text.

Audio Processing Pipeline

Before any network request, the system ensures audio files meet Whisper's 25 MiB size limit and format requirements.

Download and Validation

For remote sources, download_audio pulls the file using yt-dlp. Immediately afterward, _assert_safe_public_url (lines 102–123) validates URLs to prevent Server-Side Request Forgery (SSRF) attacks by blocking private IP ranges, localhost, and non-HTTP(S) schemes.

Compression and Chunking

The compress_audio function forces mono channel, 16 kHz sample rate, and 32 kbps m4a encoding using ffmpeg. If the compressed file still exceeds 25 MiB, chunk_audio splits it into segments of approximately 10 minutes or less, ensuring each piece complies with API limits while maintaining temporal continuity for accurate transcription.

Using the Transcribe Command

You can interact with the transcription engine through the Python API or the command line.

Python API Examples

Use the transcribe function directly for programmatic access with automatic fallback:

from agent_reach.transcribe import transcribe

# Automatically tries Groq first, then OpenAI if needed

text = transcribe("https://www.youtube.com/watch?v=dQw4w9WgXcQ")
print(text)

To force a specific provider and handle configuration errors explicitly:

from agent_reach.transcribe import transcribe, NoProviderConfigured

try:
    # Explicitly request OpenAI; raises NoProviderConfigured if key missing

    text = transcribe("audio.mp3", provider="openai")
except NoProviderConfigured as e:
    print("Configure your OpenAI key first:", e)

CLI Usage

Transcribe a remote URL with automatic provider selection:

agent-reach transcribe https://example.com/podcast.mp3

Save output to a file instead of stdout:

agent-reach transcribe audio.m4a -o transcript.txt

Summary

• Provider-agnostic design: The transcribe command abstracts Groq and OpenAI behind a unified interface, routing requests through agent_reach/transcribe.py.
• Automatic fallback: Groq's whisper-large-v3 is prioritized over OpenAI's whisper-1 when provider="auto", with automatic retry logic handled by _transcribe_with_fallback.
• Audio preprocessing: The pipeline automatically downloads, compresses (via ffmpeg), and chunks audio to meet the 25 MiB API limit.
• Security: URL inputs are validated by _assert_safe_public_url to prevent SSRF attacks.
• Flexible interface: Available as both a CLI command (agent-reach transcribe) and a Python function (transcribe(source, provider="auto")).

Frequently Asked Questions

What happens if both Groq and OpenAI fail?

If Groq returns an error (including authentication failures) and OpenAI also fails, the _transcribe_with_fallback function raises the last TranscribeError encountered. This ensures the user receives the specific error message from the final provider attempted, making debugging straightforward.

How does Agent Reach handle large audio files?

The system automatically compresses audio to mono, 16 kHz, 32 kbps m4a format using ffmpeg. If the file still exceeds 25 MiB after compression, the chunk_audio function splits it into ≤10-minute segments. Each chunk is transcribed sequentially and concatenated into a single result string.

Can I force the transcribe command to use only OpenAI?

Yes. Pass provider="openai" to the Python API or use the --provider openai flag in the CLI. When specified, the _provider_order function returns only that provider, skipping Groq entirely and raising NoProviderConfigured if the OpenAI API key is not set in the configuration.

Is it safe to transcribe arbitrary URLs?

Agent Reach validates all URLs through _assert_safe_public_url, which blocks private IP addresses, localhost, and non-HTTP(S) schemes to prevent SSRF attacks. Only public internet resources reachable via standard web protocols are processed, ensuring the transcribe command cannot be used to probe internal network infrastructure.

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