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

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, 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. 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.

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.

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:

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.

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 – Defines YouTubeChannel, its capability detection (check), and the transcribe entry point that delegates to the generic transcription engine.
• 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 – Provides helpers for locating the yt-dlp configuration file and rendering a fix command if a JS runtime is missing.
• 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.
• 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 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 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.

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