How to Transcribe Audio or Video with Groq or OpenAI Whisper Using Agent-Reach

Agent-Reach provides a unified transcribe() function that automatically downloads audio from URLs, compresses files exceeding 25 MiB, and transcribes them using Groq's free tier or OpenAI's Whisper API with automatic fallback between providers.

The agent_reach library abstracts the complexity of audio transcription into a fully automated pipeline. It handles media extraction from video platforms, format conversion to Whisper-compatible specifications, and API orchestration, allowing you to transcribe audio or video with Groq or OpenAI Whisper using either a URL or a local file path.

Prerequisites

Before invoking the transcription pipeline, ensure you have configured API credentials and installed the required system binaries.

API Key Configuration. The Config class in agent_reach/config.py resolves credentials by checking ~/.agent-reach/config.yaml first, then falling back to environment variables. For Groq, use the key groq_api_key (or the environment variable GROQ_API_KEY). For OpenAI, use openai_api_key (or OPENAI_API_KEY). If neither is found, the code raises NoProviderConfigured at lines 52-55 of agent_reach/transcribe.py.

System Dependencies. The pipeline requires yt-dlp for downloading audio from URLs and ffmpeg for audio compression. The _require() helper at lines 56-62 verifies binary availability at runtime and raises FileNotFoundError if either is missing.

The Transcription Pipeline

The transcribe() function in agent_reach/transcribe.py implements an eight-step workflow that prepares arbitrary media sources for Whisper APIs.

Source Handling and Download

The public transcribe(source, ...) interface accepts either a web URL or a local filesystem path. When a URL is provided, download_audio() invokes yt-dlp to extract the audio track in high-quality M4A format (lines 77-95). This eliminates the need for manual pre-downloading when transcribing YouTube videos, Vimeo links, or other streaming content.

Audio Compression and Chunking

Raw audio is re-encoded to a Whisper-compatible format via compress_audio() at lines 101-123. The function uses ffmpeg to produce mono, 16 kHz, 32 kbps output, significantly reducing file size while preserving speech clarity.

Whisper APIs enforce a 25 MiB upload limit. If the compressed file exceeds 24 MiB, chunk_audio() (lines 126-154) splits the audio into segments of ≤10 minutes, re-encoding each chunk to the same mono specification. This ensures large files—such as hour-long podcasts or lecture recordings—are processed automatically without manual splitting.

Provider Selection and API Orchestration

The provider parameter controls which Whisper endpoint receives the audio:

• provider="auto" (default): The module attempts transcription with Groq first, then falls back to OpenAI if Groq fails (lines 99-104 and 198-204).
• provider="groq": Forces the Groq API using model whisper-large-v3.
• provider="openai": Forces the OpenAI API using model whisper-1.

Each chunk is transmitted via transcribe_chunk() (lines 81-89), which constructs a multipart HTTP request with the appropriate model name and requests plain-text output. Network or API errors are wrapped in TranscribeError (lines 91-93).

Result Aggregation

Successful transcriptions are stripped of leading/trailing whitespace and concatenated with newline characters (lines 42-46). The final aggregated string is returned as the complete transcript, preserving chronological order from the chunked segments.

Configuration

Store credentials in ~/.agent-reach/config.yaml with the following structure:

groq_api_key: gsk_...
openai_api_key: sk-...

Alternatively, export environment variables before running your script:

export GROQ_API_KEY="gsk_..."
export OPENAI_API_KEY="sk-..."

The configuration loader at lines 69-78 of agent_reach/config.py merges these sources, with YAML values taking precedence over environment variables.

Usage Examples

Python API

Transcribe a YouTube video using the automatic provider fallback:

from agent_reach.transcribe import transcribe

text = transcribe(
    "https://www.youtube.com/watch?v=example",
    provider="auto",  # Optional: defaults to "auto"

)
print(text)

Force OpenAI Whisper for a local file, skipping Groq:

from agent_reach.transcribe import transcribe

text = transcribe(
    "/path/to/local/file.m4a",
    provider="openai",
)
print(text)

Command Line Interface

The agent_reach/cli.py module exposes the same functionality via the terminal:

python -m agent_reach.cli transcribe \
  --source "https://vimeo.com/12345678" \
  --provider groq

Summary

• Source flexibility: Accepts URLs (auto-downloaded via yt-dlp) or local audio files.
• Automatic optimization: Compresses audio to mono 16 kHz and chunks files >24 MiB into ≤10-minute segments.
• Provider resilience: Default "auto" mode tries Groq first (free tier) then falls back to OpenAI.
• Credential management: Reads from ~/.agent-reach/config.yaml or environment variables GROQ_API_KEY and OPENAI_API_KEY.
• Error handling: Raises NoProviderConfigured for missing keys and TranscribeError for API failures.

Frequently Asked Questions

What file formats does Agent-Reach support for transcription?

The pipeline accepts any audio or video format that yt-dlp can extract or ffmpeg can decode, including MP4, MP3, WAV, M4A, and WebM. The compress_audio() function automatically converts these to the required 16 kHz mono MP3 before sending to Whisper APIs.

Why does the transcription fail with a "NoProviderConfigured" error?

This error occurs when neither groq_api_key nor openai_api_key is found in ~/.agent-reach/config.yaml and the corresponding environment variables (GROQ_API_KEY, OPENAI_API_KEY) are unset. Verify your configuration file exists and contains valid credentials, or export the environment variables before execution.

How does the automatic provider fallback work?

When provider="auto", the _transcribe_with_fallback() logic first attempts to send chunks to the Groq API. If Groq returns an error or the request times out, the code catches the exception and retries the same chunk using the OpenAI API. This ensures maximum availability without manual intervention.

What is the maximum audio length Agent-Reach can process?

There is no explicit duration limit. The chunk_audio() function automatically splits audio exceeding 24 MiB into ≤10-minute segments, each under the 25 MiB API limit. This allows processing of multi-hour recordings, with the final transcript concatenating all segments in chronological order.

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