# How the Agent-Reach YouTube Channel Extracts Subtitles Using yt-dlp and JS Runtime Configuration

> Learn how Agent-Reach extracts YouTube subtitles with yt-dlp and JS runtime configuration. Discover the steps for ensuring proper setup and executing subtitle downloads efficiently.

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

---

**The YouTubeChannel class in Agent-Reach extracts subtitles by verifying yt-dlp is installed, ensuring a JavaScript runtime (Deno or Node.js) is available, and validating that Node.js users have the `--js-runtimes node` flag in their yt-dlp config file before executing subtitle download commands.**

The Agent-Reach repository provides a `YouTubeChannel` class that simplifies subtitle extraction from YouTube videos. This implementation relies on yt-dlp for downloading subtitle tracks, but requires specific JavaScript runtime configuration to handle YouTube's modern web player. Understanding how the channel validates prerequisites and constructs extraction commands is essential for troubleshooting setup issues.

## Prerequisites for YouTube Subtitle Extraction

### Verifying the yt-dlp Binary

The `check` method in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) (lines 35-66) first validates that yt-dlp is installed and functional. It executes `yt-dlp --version` via `probe_command` to detect missing binaries, broken installations, or runtime errors. If the binary is not found or returns an error, the channel reports the dependency as unavailable.

### JavaScript Runtime Detection

YouTube's playback pages require JavaScript execution capabilities. The code checks for available runtimes using `shutil.which("deno")` or `shutil.which("node")` to locate Deno or Node.js on the system PATH. While Deno works without additional configuration, Node.js requires specific flags to interface with yt-dlp.

## The Configuration Check Logic

When Node.js is present but Deno is absent, the channel validates the yt-dlp user configuration. The helper `_has_js_runtime_config()` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) (lines 23-30) inspects the config file located at `~/.config/yt-dlp/config` on Linux/macOS or `$APPDATA\yt-dlp\config` on Windows. The code verifies the presence of the `--js-runtimes` flag to ensure yt-dlp can invoke Node.js for JavaScript execution.

If the configuration is missing, the `render_ytdlp_fix_command()` function (lines 30-45 in paths.py) generates an OS-specific shell command to create the config directory and append the required flag.

## Subtitle Extraction Command Construction

Once prerequisites pass, `YouTubeChannel` inherits the `read` implementation from `BaseChannel` in [`agent_reach/channels/base.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/base.py). This method constructs a yt-dlp command with subtitle-specific flags:

```python
yt_dlp_cmd = [
    "yt-dlp",
    "--skip-download",          # Skip video download

    "--write-auto-subs",        # Capture auto-generated subtitles

    "--write-subs",             # Capture user-uploaded subtitles

    "--sub-lang", "en",         # Filter by language

    "--output", "%(title)s.%(ext)s",
    url,
]

```

Because the JS runtime flag is already present in the user config file, yt-dlp executes the necessary JavaScript to access YouTube's player and retrieves available subtitle tracks in VTT or SRT format.

## Fixing Missing JS Runtime Configuration

When the doctor command detects missing configuration, it prints a remediation command. For Linux and macOS users:

```bash
mkdir -p ~/.config/yt-dlp && \
  printf '--js-runtimes node\n' >> ~/.config/yt-dlp/config

```

Windows users receive the equivalent command targeting `%APPDATA%\yt-dlp\config`. After applying this fix, the channel successfully extracts subtitles.

## Practical Example

To extract subtitles from a YouTube URL:

```python
from agent_reach.channels.youtube import YouTubeChannel

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

# Returns paths like "MyVideo.en.vtt"

```

Before running extraction, verify your setup with:

```bash
python -m agent_reach.cli doctor

```

This executes the `check` method and reports any missing JS runtime configuration.

## Summary

- The `YouTubeChannel.check` method in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) validates yt-dlp installation and JavaScript runtime availability.
- Node.js users must include `--js-runtimes node` in their yt-dlp config file, located at `~/.config/yt-dlp/config` on Linux/macOS or `$APPDATA\yt-dlp\config` on Windows.
- The `render_ytdlp_fix_command()` helper in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) generates the exact command to create this configuration.
- Subtitle extraction uses `BaseChannel.read` with flags `--write-auto-subs` and `--write-subs` to download both automatic and manual captions.

## Frequently Asked Questions

### Why does yt-dlp need a JavaScript runtime for YouTube subtitle extraction?

YouTube's modern web interface requires JavaScript execution to decrypt player responses and access subtitle manifests. yt-dlp delegates this execution to an external JS engine like Node.js or Deno, requiring the `--js-runtimes` configuration flag to specify which engine to use.

### Where is the yt-dlp config file located on my system?

According to the source code in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), the config file resides at `~/.config/yt-dlp/config` on Linux and macOS, or `%APPDATA%\yt-dlp\config` on Windows. The `_has_js_runtime_config()` function checks this specific path for the required `--js-runtimes` flag.

### Can I use Deno instead of Node.js for subtitle extraction?

Yes. The `check` method detects Deno via `shutil.which("deno")` and accepts it without requiring additional configuration flags. Deno users do not need to modify their yt-dlp config file, unlike Node.js users who must add `--js-runtimes node`.

### What subtitle formats does the YouTube channel return?

The implementation downloads subtitle files in the formats provided by YouTube, typically WebVTT (.vtt) or SubRip (.srt) files. The `read` method returns file paths to these downloaded subtitles, which are saved using the video title as the filename base.