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

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 (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 (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. This method constructs a yt-dlp command with subtitle-specific flags:

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:

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:

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:

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

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