How to Configure Xiaoyuzhou Podcast Transcription with the Groq API in Agent Reach

Configure the Groq API key via agent-reach configure groq-key <key> or set the GROQ_API_KEY environment variable, ensure ffmpeg is installed, and install the Xiaoyuzhou transcription script with agent-reach install --env=auto to transcribe podcasts from xiaoyuzhoufm.com using Groq's Whisper model.

The Agent-Reach repository provides automated podcast transcription capabilities for Xiaoyuzhou (小宇宙) via the Groq API. To enable this functionality, you must satisfy three prerequisite checks implemented in the Xiaoyuzhou channel handler. This guide walks you through configuring the Xiaoyuzhou podcast transcription with the Groq API using the source code from Panniantong/Agent-Reach.

Prerequisites Check in the Xiaoyuzhou Channel

The Xiaoyuzhou channel implementation in agent_reach/channels/xiaoyuzhou.py enforces three mandatory checks before allowing transcription operations.

Verify ffmpeg Installation

The channel requires ffmpeg for audio conversion. In agent_reach/channels/xiaoyuzhou.py lines 24-36, the code probes for the ffmpeg executable using probe_command("ffmpeg", ["-version"], ...) and raises an error if the binary is not found in your system path.

Install the Transcription Helper Script

The channel looks for a helper script at ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh (verified in lines 38-45 of xiaoyuzhou.py). Install this dependency using the built-in installer:

agent-reach install --env=auto

This command copies the shell wrapper that streams audio chunks to the Groq API endpoint into the expected location.

Configure the Groq API Key

The Xiaoyuzhou channel authenticates with Groq using either an environment variable or the Agent-Reach configuration file. The credential resolution logic resides in agent_reach/channels/xiaoyuzhou.py lines 47-60, where the code checks os.environ.get("GROQ_API_KEY") first, then falls back to Config().get("groq_api_key").

Method 1: CLI Configuration (Recommended)

Use the built-in configure command to persist your API key to the Agent-Reach configuration file:

agent-reach configure groq-key gsk_youractualkeyhere

This command writes the key to ~/.agent-reach/config.yaml under the groq_api_key field. The CLI handling for this operation is implemented in agent_reach/cli.py approximately lines 80-110, which invokes the Config class from agent_reach/config.py to persist the value.

Method 2: Environment Variable

Alternatively, export the key in your shell session:

export GROQ_API_KEY=gsk_youractualkeyhere

The channel handler prioritizes the environment variable over the config file value, as implemented in the conditional logic at lines 47-60 of xiaoyuzhou.py.

Run Xiaoyuzhou Podcast Transcription

Once configured, trigger transcription using the generic read command. The URL routing logic in xiaoyuzhou.py lines 16-20 (can_handle method) automatically detects xiaoyuzhoufm.com URLs and routes requests to the appropriate channel:

agent-reach read https://xiaoyuzhoufm.com/episode/12345

The workflow proceeds as follows:

1. Validates ffmpeg availability via probe_command
2. Confirms the transcribe script exists at ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh
3. Retrieves the Groq API key from your configured source (environment or config)
4. Downloads the podcast audio and invokes the transcription script
5. Returns the transcribed text processed through Groq's Whisper model

Summary

• Install dependencies: Ensure ffmpeg is available on your system path (checked in xiaoyuzhou.py lines 24-36)
• Deploy helper script: Run agent-reach install --env=auto to install ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh (verified in lines 38-45)
• Configure API credentials: Use agent-reach configure groq-key <key> to write to ~/.agent-reach/config.yaml or set the GROQ_API_KEY environment variable (logic in lines 47-60)
• Execute transcription: Use agent-reach read <xiaoyuzhou_url> to automatically route to the Xiaoyuzhou channel (can_handle logic in lines 16-20)

Frequently Asked Questions

Where does Agent-Reach store the Groq API key?

Agent-Reach stores the key in ~/.agent-reach/config.yaml under the groq_api_key field when configured via the CLI. The Config class in agent_reach/config.py handles reading and writing this YAML file, with fallback to the GROQ_API_KEY environment variable if present.

What happens if ffmpeg is not installed?

The Xiaoyuzhou channel will raise a prerequisite error before attempting transcription. Specifically, the check method in agent_reach/channels/xiaoyuzhou.py lines 24-36 probes for the ffmpeg executable using probe_command and halts execution with a descriptive error message if the binary is missing from your system path.

Can I use the Groq API without installing the transcribe script?

No. The channel explicitly verifies the existence of ~/.agent-reach/tools/xiaoyuzhou/transcribe.sh in lines 38-45 of xiaoyuzhou.py. This shell wrapper is required to chunk audio files and stream them to the Groq API endpoint; transcription will fail with a file-not-found error if this script is absent.

How does Agent-Reach know to use the Xiaoyuzhou channel for a specific URL?

The can_handle method in agent_reach/channels/xiaoyuzhou.py lines 16-20 inspects the URL string using pattern matching and returns True for domains matching xiaoyuzhoufm.com. This enables automatic routing when you execute agent-reach read <url>, directing Xiaoyuzhou URLs to the appropriate channel handler.

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