# How to Use the YouTube Subtitle Extraction Feature in Agent-Reach: A Complete Guide

> Learn to extract YouTube subtitles with Agent-Reach. This guide details using yt-dlp and the YouTubeChannel class for direct subtitle file downloads. Master subtitle extraction today.

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

---

**Agent-Reach routes YouTube subtitle extraction through the `YouTubeChannel` class, which uses `yt-dlp` to download subtitle files directly when you set the `YT_DLP_OPTS` environment variable before running the `transcribe` command.**

The `Panniantong/Agent-Reach` repository treats every platform as a **channel** that delegates upstream tasks to specialized tools. For **YouTube subtitle extraction**, the channel leverages `yt-dlp` for video data retrieval and Whisper-compatible APIs for transcription. Understanding the backend pipeline makes it possible to capture auto-generated or user-provided subtitle files alongside your transcripts.

## How Agent-Reach Handles YouTube Subtitles

### Backend Detection in YouTubeChannel

In [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py), the `YouTubeChannel.check()` method validates that `yt-dlp` and a JavaScript runtime—either **Node** or **Deno**—are present on the system. If either dependency is missing, the method emits a warning that includes the exact command needed to fix the issue, as implemented in lines 35–66 of the source.

### The Transcription and Download Pipeline

When you invoke the channel’s `transcribe()` method, it lazily imports `agent_reach.transcribe.transcribe` from [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py). The helper executes the following workflow:

- Validates that the URL is a public YouTube link.
- Downloads the **audio** stream via `yt-dlp` using the internal `download_audio` routine.
- Compresses the audio with `ffmpeg` and splits the file into **10-minute chunks** if necessary.
- Sends each chunk to a configured Whisper provider, falling back from **Groq** to **OpenAI**.

## Step-by-Step: Extract YouTube Subtitles with Agent-Reach

### Install Required Dependencies

Before extraction, ensure `yt-dlp`, a JS runtime, and `ffmpeg` are installed.

```bash
pip install -e .                # install Agent-Reach in editable mode

pip install yt-dlp              # install yt-dlp

# Install a JS runtime (Node.js example)

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

```

Run the built-in `doctor` or `check` routine to confirm readiness.

### Configure yt-dlp Subtitle Options

Because `yt-dlp` is the actual download backend, you can pass native subtitle flags through the **`YT_DLP_OPTS`** environment variable.

```bash
export YT_DLP_OPTS="--write-auto-sub --sub-lang en"

```

Other useful flags include `--write-sub` for user-uploaded captions.

### Run the Transcription Command

Invoke the CLI entry point from [`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py):

```bash
python -m agent_reach.cli transcribe "https://www.youtube.com/watch?v=example_id"

```

With `YT_DLP_OPTS` exported, `yt-dlp` writes the subtitle files during the same pass that downloads the audio stream.

### Locate the Saved Subtitle Files

After the run finishes, retrieve the `.vtt` or `.srt` file—such as `source.en.vtt`—from the temporary work directory. Enable **`--verbose`** on the CLI to print the exact directory path.

## Programmatic YouTube Subtitle Extraction in Python

You can also call the pipeline directly from Python. The `transcribe()` function returns the transcript text and leaves the subtitle artifacts in the temporary folder used by `yt-dlp`.

```python
from agent_reach.transcribe import transcribe
from agent_reach.config import Config

cfg = Config()                     # loads your API keys, if needed

text = transcribe(
    "https://www.youtube.com/watch?v=example_id",
    provider="auto",              # Groq → OpenAI fallback

    config=cfg,
)
print(text)                        # printed transcript

# Subtitles are saved automatically by yt-dlp in the same temporary folder.

```

## Key Source Files for YouTube Subtitle Extraction

- **[`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py)** – Defines `YouTubeChannel`, its capability detection (`check`), and the `transcribe` entry point that delegates to the generic transcription engine.
- **[`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py)** – Implements the full audio-to-text pipeline: URL safety checks, audio download via `yt-dlp`, compression, chunking, and provider fallback logic.
- **[`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py)** – Provides helpers for locating the `yt-dlp` configuration file and rendering a fix command if a JS runtime is missing.
- **[`agent_reach/cli.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py)** – CLI entry point that parses commands (`transcribe`, `doctor`, etc.) and forwards them to the appropriate channel methods.

## Summary

- Agent-Reach routes YouTube tasks through the **`YouTubeChannel`** class in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py).
- The **`check()`** method enforces prerequisites: `yt-dlp` and a JavaScript runtime.
- Subtitle downloads rely on native **`yt-dlp`** flags supplied via the `YT_DLP_OPTS` environment variable.
- The **`transcribe()`** method in [`agent_reach/transcribe.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) downloads audio, compresses it with `ffmpeg`, chunks it into 10‑minute segments, and routes it to Whisper providers.
- Subtitle files are written to the temporary work directory and can be located by enabling verbose CLI output.

## Frequently Asked Questions

### Does Agent-Reach provide a dedicated subtitle-only extraction method?

No. According to the `Panniantong/Agent-Reach` source code, there is no standalone subtitle extraction endpoint. Instead, the framework reuses the `yt-dlp` backend that powers `YouTubeChannel.transcribe()`, and you obtain subtitles by setting the appropriate flags in `YT_DLP_OPTS` before running the transcription pipeline.

### What prerequisites are required for Agent-Reach YouTube subtitle extraction?

The system requires `yt-dlp`, a JavaScript runtime such as **Node.js** or **Deno**, and optionally `ffmpeg` if you intend to process audio for transcription. The `YouTubeChannel.check()` method in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) probes for these binaries and emits a warning with the exact fix command when something is missing.

### Can I extract subtitles without downloading and transcribing the audio?

In practice, the most straightforward path is to let the `transcribe` command run because `yt-dlp` fetches both audio and subtitles in the same operation. You can ignore the resulting transcript and keep only the subtitle files written to the temporary directory. The pipeline does not currently expose a pure subtitle-only flag.

### Where does Agent-Reach save the downloaded subtitle files?

`yt-dlp` writes subtitle files to the same temporary work directory used during audio processing. When you run the CLI with **`--verbose`**, the path is printed to stdout, allowing you to copy `.vtt` or `.srt` files such as `source.en.vtt` after the job completes.