# How the Agent Reach Transcribe Command Handles Provider Fallback > Learn how the Agent Reach transcribe command handles provider fallback by trying transcription services in order until one works. Discover the sequence and failure handling. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: internals - Published: 2026-07-19 --- **The `transcribe` command implements provider fallback by iterating through a pre-configured priority list of transcription services, attempting each in sequence until one succeeds or all fail.** The `transcribe` command in the [Panniantong/Agent-Reach](https://github.com/Panniantong/Agent-Reach) repository provides resilient audio transcription through an intelligent fallback mechanism. When primary providers like Groq or OpenAI experience outages, the system automatically degrades to secondary services without interrupting the workflow. This implementation is used by both the CLI interface and channel classes such as `YouTubeChannel` to ensure continuous transcription capabilities. ## Provider Configuration and Priority Order The fallback behavior is driven by the **provider order** defined in the `Config` class within [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). When the `transcribe()` function is invoked, it defaults to `provider="auto"` (as seen in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) lines 9-12), which signals the system to use the configured priority list rather than a single service. The configuration typically specifies an ordered array such as `["groq", "openai"]`. This sequence determines the exact order in which transcription providers are attempted, with the first provider serving as the primary and subsequent entries acting as backups. ## The Fallback Loop in `_transcribe_with_fallback` The core fallback logic resides in the `_transcribe_with_fallback()` helper function, defined starting at line 306 in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py). This function receives individual audio chunks and the provider priority list, implementing a defensive iteration pattern that ensures transcription attempts continue until success or exhaustion. ### Iterating Through Providers Inside `_transcribe_with_fallback()`, the function loops through each provider in the configured order. For every provider `p` in the list, it attempts transcription by calling `transcribe_chunk(chunk, p, config=config)` at line 314. This call delegates the actual API interaction to the specific provider implementation while maintaining consistent error handling. ### Error Handling and Continuation If a provider raises a `TranscribeError`, the exception is caught immediately within the loop. The system logs a warning message documenting the failure, then continues to the next provider in the sequence. This process repeats until either: - A provider returns successful text, causing the function to return immediately with the result - The provider list is exhausted, triggering a final `TranscribeError` indicating that all available services failed ## Audio Chunking and Result Aggregation Before the fallback logic executes, the source audio—whether from a YouTube URL handled by `YouTubeChannel` or a local file—is split into manageable chunks. The main `transcribe()` function orchestrates this process by calling `_transcribe_with_fallback()` for each segment individually. Once all chunks are processed successfully, the per-chunk results are concatenated at line 301 in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) to form the final transcript string. This chunk-based approach ensures that transient failures affect only small portions of the audio, and the fallback mechanism operates at the granular level of individual segments. ## Usage Examples ### CLI Usage with Automatic Fallback To leverage the fallback mechanism via command line, invoke the transcribe command without specifying a provider: ```bash # Automatic provider selection with fallback agent-reach transcribe "https://www.youtube.com/watch?v=abcd1234" # Explicit single provider (disables fallback) agent-reach transcribe "https://www.youtube.com/watch?v=abcd1234" --provider groq ``` ### Python API Integration When using the Python API directly, the fallback occurs automatically with default parameters: ```python from agent_reach.transcribe import transcribe # Uses provider="auto" by default, enabling fallback text = transcribe("https://www.youtube.com/watch?v=abcd1234") print(text) ``` ## Summary - **Configuration-driven priority**: The `Config` class supplies the ordered provider list (e.g., `["groq", "openai"]`) that determines the exact fallback sequence. - **Defensive iteration**: `_transcribe_with_fallback()` at line 306 implements a loop that attempts each provider sequentially via `transcribe_chunk()` at line 314. - **Graceful degradation**: `TranscribeError` exceptions are caught and logged, allowing the system to proceed to the next provider without crashing the transcription process. - **Chunk-based processing**: Audio is split into chunks with fallback logic applied per-chunk, and results aggregated at line 301 in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py). - **Cross-interface support**: Both the CLI entry point in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) and the Python API support automatic fallback when `provider="auto"`. ## Frequently Asked Questions ### What happens if all providers fail during transcription? If every provider in the configured order fails to transcribe a chunk, the `_transcribe_with_fallback()` function exhausts its provider list and raises a `TranscribeError`. This error propagates up through the `transcribe()` function, indicating that transcription could not be completed for that specific audio segment. ### How do I disable provider fallback and use only one specific service? To bypass the fallback mechanism entirely, specify a concrete provider name instead of using the default `"auto"` setting. In the CLI, use the `--provider` flag with a specific service name like `groq` or `openai`. In Python, pass `provider="groq"` explicitly to the `transcribe()` function to restrict execution to that single provider. ### Where is the provider priority order defined? The provider priority list is defined in the `Config` class within [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). The default order typically prioritizes services like Groq first, followed by OpenAI, though this can be customized by modifying the configuration object passed to the transcription functions. ### Does the fallback mechanism work for both URLs and local files? Yes, the fallback mechanism operates at the chunk level after the input source—whether a YouTube URL processed by `YouTubeChannel` or a local audio file—has been downloaded and split. The `_transcribe_with_fallback()` function processes audio chunks identically regardless of the original source format, ensuring consistent fallback behavior across all input types.