# How to Configure yt-dlp with Node.js for YouTube Subtitle Extraction in Agent Reach

> Configure yt-dlp with Node js for YouTube subtitle extraction in Agent Reach. Learn how to set up the JavaScript runtime for reliable downloads.

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

---

**Agent Reach configures yt-dlp to use Node.js as its JavaScript runtime by detecting the Node binary, locating the OS-specific config file, and appending the `--js-runtimes node` flag to enable reliable YouTube subtitle extraction.**

Agent Reach is an open-source automation framework that extracts YouTube subtitles using yt-dlp. To handle YouTube's dynamic JavaScript-heavy pages, yt-dlp requires an external JS runtime, which Agent Reach configures to use Node.js through an automated three-step validation process.

## Prerequisites and Node.js Detection

Agent Reach validates the execution environment before attempting subtitle extraction. The system checks for the presence of a JavaScript runtime to ensure yt-dlp can process YouTube's dynamically loaded content.

### Checking for Node.js Installation

In [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py), the `YouTubeChannel.check` method (lines 51-56) uses `shutil.which("node")` to verify that Node.js is available in the system PATH. If the binary is missing, the channel reports a warning prompting the user to install Node.js or Deno before proceeding with YouTube operations.

## Configuration File Management

Once Node.js is confirmed, Agent Reach manages the yt-dlp configuration file to persist the runtime settings across sessions.

### Locating the yt-dlp Config Path

The helper function `get_ytdlp_config_path()` in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) (lines 32-35) constructs the platform-specific configuration directory:

- **Linux/macOS**: `~/.config/yt-dlp/config`
- **Windows**: `%APPDATA%\yt-dlp\config`

This ensures that yt-dlp reads the settings from the standard configuration location regardless of operating system.

### Applying the JavaScript Runtime Flag

The `render_ytdlp_fix_command()` function in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py) (lines 38-54) checks whether the config file already contains the `--js-runtimes` option. If absent, it generates a shell command that creates the necessary directory structure and appends `--js-runtimes node` to the configuration file. This flag instructs yt-dlp to delegate JavaScript execution to Node.js when processing YouTube pages.

## Configuration Methods

You can configure yt-dlp with Node.js manually, programmatically, or through the automated CLI installer.

### Manual Configuration on Linux and macOS

Run the following commands to verify Node.js and create the configuration:

```bash

# Verify Node.js installation

node --version

# Create config directory and append the runtime flag

mkdir -p "${HOME}/.config/yt-dlp"
printf '%s\n' '--js-runtimes node' >> "${HOME}/.config/yt-dlp/config"

```

### Manual Configuration on Windows

Using PowerShell, execute the following to set up the configuration:

```powershell

# Verify Node.js installation

node -v

# Create config directory and append the runtime flag

$cfg = "$env:APPDATA\yt-dlp\config"
New-Item -ItemType Directory -Force -Path (Split-Path $cfg) | Out-Null
if (-not (Test-Path $cfg) -or -not (Select-String -Path $cfg -Pattern '--js-runtimes' -Quiet)) {
    Add-Content -Path $cfg -Value '--js-runtimes node'
}

```

### Programmatic Configuration via Python

Import the utility function to generate the appropriate command for your platform:

```python
from agent_reach.utils.paths import render_ytdlp_fix_command

# Outputs an OS-specific shell command

print(render_ytdlp_fix_command())

```

### Automated CLI Installation

The `agent_reach.cli` module (line 35) provides an automated setup that handles the entire configuration flow:

```bash
python -m agent_reach.cli install --env=auto

```

This command performs the following actions automatically:

1. Detects Node.js using `shutil.which`
2. Creates the yt-dlp configuration directory if it does not exist
3. Appends `--js-runtimes node` to the config file if missing
4. Reports success or configuration warnings

## Summary

- **Prerequisite detection**: Agent Reach verifies Node.js availability using `shutil.which("node")` in [`youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/youtube.py) before allowing YouTube operations.
- **Cross-platform paths**: The `get_ytdlp_config_path()` function handles OS-specific configuration locations in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py).
- **Runtime configuration**: The `--js-runtimes node` flag is appended to the yt-dlp config file via `render_ytdlp_fix_command()` to enable JavaScript processing.
- **Flexible setup**: Users can configure the integration manually via shell commands, programmatically via Python imports, or automatically through the CLI installer.

## Frequently Asked Questions

### Why does yt-dlp need Node.js for YouTube subtitle extraction?

YouTube's modern interface relies heavily on JavaScript to load content dynamically. yt-dlp requires an external JavaScript runtime to execute this code and extract subtitle metadata. According to the Agent Reach source code in [`agent_reach/channels/youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py), Node.js (or Deno) must be available to process these dynamic pages successfully.

### Where is the yt-dlp configuration file stored on my system?

The configuration location depends on your operating system. As implemented in [`agent_reach/utils/paths.py`](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), the file is stored at `~/.config/yt-dlp/config` on Linux and macOS, or `%APPDATA%\yt-dlp\config` on Windows. The `get_ytdlp_config_path()` function automatically resolves these paths based on the host platform.

### Can I use Deno instead of Node.js with yt-dlp in Agent Reach?

Yes, the Agent Reach codebase supports Deno as an alternative JavaScript runtime. The `shutil.which("node")` check in [`youtube.py`](https://github.com/Panniantong/Agent-Reach/blob/main/youtube.py) (lines 51-56) explicitly mentions Deno as an acceptable alternative, and yt-dlp's `--js-runtimes` flag accepts either `node` or `deno` as valid values.

### What happens if Node.js is not installed when I run the Agent Reach installer?

If the CLI installer detects that Node.js is missing, it will display a warning message prompting you to install the runtime, as referenced in the `YouTubeChannel.check` implementation. The installer will not write the configuration file until Node.js is present, ensuring that yt-dlp does not attempt to execute JavaScript without a valid runtime.