# How to Use the Agent-Reach Transcribe Command for YouTube Video Transcription with Groq Whisper > Learn to transcribe YouTube videos with Groq Whisper using the Agent-Reach transcribe command. Easily generate transcripts from video URLs with this powerful tool. - Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach) - Tags: how-to-guide - Published: 2026-06-20 --- **To transcribe YouTube videos with Groq Whisper using Agent-Reach, configure your Groq API key with `agent-reach configure groq-key`, then run `agent-reach transcribe --provider groq` to download audio, chunk it, and generate transcripts using the free `whisper-large-v3` model.** The **Agent-Reach** open-source repository (`Panniantong/Agent-Reach`) provides a unified transcription pipeline that automates the entire workflow from video download to text generation. This guide explains how to leverage the built-in `transcribe` command with Groq's free Whisper API to convert YouTube videos into accurate text transcripts. ## Prerequisites: Configure Your Groq API Key Before processing videos, you must store your Groq API key in the Agent-Reach configuration. The CLI stores this in `~/.agent-reach/config.yaml` or reads from environment variables via [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py). ```bash agent-reach configure groq-key YOUR_GROQ_API_KEY ``` This one-time setup persists the key for all future transcription requests. ## Basic CLI Usage The `transcribe` command in [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) accepts a YouTube URL and optional provider flags. Use the `--provider groq` flag to explicitly route requests to Groq's Whisper endpoint. ```bash # Transcribe with explicit Groq provider agent-reach transcribe "https://www.youtube.com/watch?v=abc123DEF" --provider groq # Output to a file instead of stdout agent-reach transcribe "https://youtu.be/xyz789" -o transcript.txt ``` You can also omit the provider flag entirely. The default `"auto"` setting attempts Groq first, then falls back to OpenAI if Groq returns an error. ## How the Transcription Pipeline Works The Agent-Reach transcription pipeline is implemented across three core modules: [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) for argument parsing, [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) for URL handling, and [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) for the core audio processing logic. ### CLI Parsing and Provider Selection In [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) (lines 117-124), the `transcribe` sub-parser accepts the `source` parameter and `--provider` flag. Valid provider values are `auto`, `groq`, or `openai`. The provider selection logic in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) uses a `_provider_order` list (lines 99-104) that maps `"auto"` to `["groq", "openai"]`. When you specify `groq` explicitly, the system looks up the provider configuration in the `PROVIDERS` dictionary and routes requests to Groq's API endpoint at `https://api.groq.com/openai/v1/audio/transcriptions`. ### Audio Processing and Chunking The `download_audio` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 77-95) calls `yt-dlp` to extract the best audio stream from the YouTube URL and saves it locally. The pipeline then processes this audio through two critical stages: 1. **Compression**: The `compress_audio` function (lines 101-124) re-encodes the audio to mono 16 kHz at 32 kbps in M4A format. This optimizes the file for Whisper's input requirements while minimizing bandwidth. 2. **Chunking**: The `chunk_audio` function (lines 126-154) checks if the compressed file exceeds 24 MiB. If it does, the audio is split into segments of no more than 10 minutes each to comply with Groq's API limits. ### Groq Whisper API Integration Each audio chunk is processed by the `transcribe_chunk` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 63-90). This function sends the binary audio data to Groq's API using the `whisper-large-v3` model. The `_transcribe_with_fallback_` wrapper (lines 49-61) handles retry logic and provider failover when using `auto` mode. Finally, the main `transcribe` function (lines 107-125) aggregates all chunk transcripts into a single string, handling the concatenation before returning the result to the CLI or writing to the output file specified by `-o`. ## Python API Usage You can bypass the CLI and use the core transcription functions directly in Python scripts. The [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) module exposes the main `transcribe` function that accepts URLs and provider strings. ```python from agent_reach.transcribe import transcribe text = transcribe( "https://www.youtube.com/watch?v=abc123DEF", provider="groq" # Optional: defaults to "auto" which tries Groq first ) print(text[:200]) # Preview first 200 characters ``` The [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) module (lines 81-90) provides a thin wrapper class `YouTubeChannel` with a `transcribe` method that simply forwards to the core `transcribe` function, allowing seamless integration for channel-specific processing workflows. ## Summary - **Configuration**: Store your Groq API key using `agent-reach configure groq-key` before running transcriptions. - **CLI Command**: Use `agent-reach transcribe --provider groq` to process videos with Groq's free `whisper-large-v3` model. - **Audio Pipeline**: The system automatically downloads audio via `yt-dlp`, compresses it to mono 16 kHz 32 kbps M4A, and chunks files larger than 24 MiB into 10-minute segments. - **Provider Logic**: The `auto` provider setting tries Groq first, then falls back to OpenAI if errors occur. - **Core Files**: [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) handles the heavy lifting (download, compression, chunking, API calls), while [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) provides URL-specific wrappers. ## Frequently Asked Questions ### What Whisper model does Groq use for transcription? According to the implementation in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py), Agent-Reach specifically calls Groq's `whisper-large-v3` model endpoint. This is the free, production-ready model hosted on Groq's infrastructure, offering fast transcription speeds without API usage charges. ### How does Agent-Reach handle large video files? The `chunk_audio` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 126-154) automatically splits audio files exceeding 24 MiB into chunks of 10 minutes or less. This ensures compliance with Groq's API size limits while maintaining sequential processing. The `transcribe` function then reassembles these chunks into a single coherent transcript. ### Can I use automatic fallback if Groq fails? Yes. When using `--provider auto` (the default), the `_transcribe_with_fallback_` function in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) (lines 49-61) implements a retry mechanism that attempts Groq first based on the `_provider_order` list, then automatically switches to OpenAI if Groq returns an error or is unavailable. ### Where are API keys stored in Agent-Reach? API keys are managed by [`agent_reach/config.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) and stored in a YAML configuration file at `~/.agent-reach/config.yaml`. The system also checks for environment variables, allowing keys to be set via `export` commands or loaded from `.env` files as fallback mechanisms.