How to Extract YouTube Video Transcripts Using yt-dlp Integration in Agent Reach

Agent Reach routes YouTube transcript extraction through the YouTubeChannel class in agent_reach/channels/youtube.py, which orchestrates yt-dlp for audio download and Whisper APIs for transcription.

The Panniantong/Agent-Reach repository provides a lightweight orchestration layer for AI agents, treating each platform as a channel that delegates heavy lifting to native upstream tools. When you need to extract YouTube video transcripts using yt-dlp integration in Agent Reach, the system coordinates audio extraction, compression, and speech-to-text conversion through a pipeline of specialized modules.

Prerequisites and Channel Configuration

Before invoking transcripts, configure your API credentials in ~/.agent_reach.yaml. The Config class (defined in agent_reach/config.py) loads groq_api_key and openai_api_key for Whisper provider authentication.

How the YouTube Channel Handles URLs

Agent Reach uses channel-based routing to determine which upstream tool should process a given URL.

URL Detection with can_handle()

In agent_reach/channels/youtube.py (lines 29-34), the static method can_handle(url) validates hosts matching youtube.com or youtu.be before routing the request to the YouTube channel. This ensures that only valid YouTube URLs trigger the yt-dlp workflow.

Health Check and Binary Verification

The check() method in agent_reach/channels/youtube.py ensures upstream dependencies are functional before processing.

Verifying yt-dlp and JavaScript Runtimes

Lines 35-38 execute yt-dlp --version to confirm the binary exists. Because YouTube subtitle processing requires JavaScript execution, lines 50-58 verify Node.js or Deno availability. If Node is detected, render_ytdlp_fix_command() in agent_reach/utils/paths.py (lines 29-45) automatically injects --js-runtimes node into the configuration flags.

FFmpeg and Whisper Provider Checks

When Whisper providers (groq_whisper or openai_whisper) are configured, lines 68-78 verify ffmpeg installation and report audio-to-text transcription readiness. This validation prevents runtime failures during the compression stage.

The Transcription Pipeline

The transcribe() method (lines 81-90) acts as a thin wrapper that lazily imports the generic transcription engine from agent_reach/transcribe.py. This design keeps the YouTube channel lightweight while delegating complex audio processing to dedicated utilities.

Audio Download with yt-dlp

The download_audio() function (lines 77-94) invokes yt-dlp with -x --audio-format m4a to extract the audio stream into a temporary directory. This command extracts the best quality audio and converts it to the m4a container for downstream processing.

Compression and Chunking

compress_audio() (lines 101-122) runs ffmpeg to generate a mono 16 kHz, 32 kbps m4a file, ensuring compatibility with Whisper API size limits. If the compressed file exceeds 24 MiB, chunk_audio() (lines 126-150) splits it into segments of ≤10 minutes to respect API constraints.

Provider Selection and API Calls

The transcribe() function (lines 99-104, 198-204) selects the first configured provider in priority order: groq → openai. The transcribe_chunk() function (lines 163-190) POSTs each audio chunk to the selected Whisper endpoint using the API key retrieved from the Config object.

Code Examples

Basic Transcript Extraction

from agent_reach.channels.youtube import YouTubeChannel
from agent_reach.config import Config

cfg = Config()                     # loads API keys from ~/.agent_reach.yaml

yt = YouTubeChannel()
url = "https://www.youtube.com/watch?v=abc123"

# Run a health check first (optional)

status, msg = yt.check(config=cfg)
print(f"Channel status: {status} – {msg}")

# Extract the transcript

transcript = yt.transcribe(url, provider="auto", config=cfg)
print(transcript[:500])            # print first 500 characters

Using a Specific Provider

from agent_reach.channels.youtube import YouTubeChannel
from agent_reach.config import Config

yt = YouTubeChannel()
cfg = Config()

# Force OpenAI Whisper; will raise if the OpenAI key is missing.

text = yt.transcribe(
    "https://youtu.be/dQw4w9WgXcQ",
    provider="openai",
    config=cfg,
)
print(text)

Command Line Usage

# Ensure dependencies are present

$ agent-reach install --env=auto

# Verify YouTube channel status

$ agent-reach doctor

# Extract transcript

$ python -m agent_reach.cli transcribe https://youtu.be/xyz

Summary

• Agent Reach delegates YouTube audio extraction to yt-dlp and transcription to Whisper APIs, maintaining a minimal orchestration footprint.
• The YouTubeChannel class in agent_reach/channels/youtube.py validates URLs, checks binary dependencies including JavaScript runtimes, and initiates the transcription workflow.
• Audio processing occurs in agent_reach/transcribe.py, handling download, compression to 32 kbps m4a, and automatic chunking for files over 24 MiB.
• Configuration relies on ~/.agent_reach.yaml for API keys and agent_reach/config.py for runtime retrieval, with support for Groq and OpenAI Whisper providers.

Frequently Asked Questions

What dependencies are required to extract YouTube transcripts in Agent Reach?

You need yt-dlp for audio extraction, a JavaScript runtime (Node.js or Deno) for subtitle processing, and ffmpeg for audio compression. The check() method in agent_reach/channels/youtube.py verifies all binaries before execution, ensuring the pipeline fails fast with clear messaging if components are missing.

Can I force a specific Whisper provider instead of using auto-selection?

Yes. Pass provider="openai" or provider="groq" to the transcribe() method. The system validates that the corresponding API key exists in ~/.agent_reach.yaml before proceeding, raising an error immediately if the configuration is incomplete.

How does Agent Reach handle large video files that exceed API limits?

The compress_audio() function in agent_reach/transcribe.py converts audio to mono 16 kHz at 32 kbps. If the result exceeds 24 MiB, chunk_audio() automatically splits it into ≤10-minute segments that are transcribed individually and concatenated into a single transcript string.

Where does Agent Reach store API keys for transcription services?

API keys are stored in ~/.agent_reach.yaml under the keys groq_api_key and openai_api_key. The Config class in agent_reach/config.py loads these values at runtime for authentication with Whisper endpoints.

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