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

> Learn to extract YouTube video transcripts using yt-dlp in Agent Reach. This guide details the integration for efficient audio download and transcription.

- Repository: [Pnant/Agent-Reach](https://github.com/Panniantong/Agent-Reach)
- Tags: how-to-guide
- Published: 2026-06-13

---

**Agent Reach routes YouTube transcript extraction through the `YouTubeChannel` class in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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

```python
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

```python
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

```bash

# 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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/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`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/config.py) loads these values at runtime for authentication with Whisper endpoints.