How yt-dlp Handles YouTube Videos Requiring Authentication or Cookies in Agent Reach

Agent Reach delegates all YouTube authentication to yt-dlp, supporting cookie files and browser-based extraction through standard yt-dlp configuration flags while running downloads as a backend-only channel.

When processing YouTube videos that require login credentials or age verification, Agent Reach relies entirely on yt-dlp's native authentication mechanisms rather than implementing custom OAuth flows. This architecture keeps the codebase lightweight while allowing users to leverage yt-dlp's mature cookie handling for private or restricted content.

Backend-Only YouTube Channel Architecture

Agent Reach treats YouTube as a backend-only channel, meaning all media processing occurs server-side through external tooling rather than client-side embedding.

YouTubeChannel Class and Backend Detection

The YouTubeChannel class in [agent_reach/channels/youtube.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/channels/youtube.py) manages the integration. Before processing any URLs, the check() method runs yt-dlp --version via probe_command to verify the binary exists and is executable. If yt-dlp is missing or fails to run, the channel reports an error and disables the backend.

JavaScript Runtime Requirements

YouTube's streaming protocols require a JavaScript runtime (Node.js or Deno). The check() method searches for node or deno executables, and when Node is present, ensures the yt-dlp config file contains --js-runtimes node. This configuration is handled by render_ytdlp_fix_command() in [agent_reach/utils/paths.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), which locates the config path and inserts the necessary runtime flag.

Authentication Mechanisms

Agent Reach does not embed special YouTube authentication logic. Instead, it relies on yt-dlp's standard mechanisms for handling authenticated sessions.

Cookie File Support

Users can create a cookie file at ~/.config/yt-dlp/cookies.txt (or any path passed via --cookies). When present, yt-dlp automatically sends these cookies with download requests, enabling access to age-restricted videos or private uploads. The transcription pipeline in [agent_reach/transcribe.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/transcribe.py) invokes yt-dlp with these configurations already in place.

Browser-Based Cookie Extraction

For users who prefer not to manually export cookies, the CLI's install routine supports browser-based extraction. The render_ytdlp_fix_command() helper can generate commands that add --cookies-from-browser chrome (or other supported browsers) to the yt-dlp config. This mirrors yt-dlp's native flag and allows the tool to reuse existing browser sessions for videos requiring login credentials.

Audio Download Implementation

When transcribe() processes a YouTube URL, it delegates to the download_audio() helper, which constructs yt-dlp commands like:

yt-dlp -x --audio-format m4a --audio-quality 0 -o source.%(ext)s -- <url>

This command extracts audio in M4A format at the highest available quality. The URL can be public, age-restricted, or private—yt-dlp handles the authentication transparently based on the provided cookie configuration.

Safety Checks and SSRF Prevention

Before executing any download, download_audio() calls _assert_safe_public_url() to block private IP ranges and internal URLs, preventing Server-Side Request Forgery (SSRF) attacks. Once the URL passes validation, yt-dlp runs with the same security model as a direct command-line invocation.

Configuration Setup via CLI

The [agent_reach/cli.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/cli.py) entry point provides an installation helper that guides users through yt-dlp configuration. The "install" sub-command prints commands for setting up the JS runtime and optionally configuring cookie support, ensuring users can authenticate without manually editing config files.

Code Examples

Transcribing a public video:

from agent_reach.transcribe import transcribe

text = transcribe(
    "https://www.youtube.com/watch?v=example",
    provider="auto",
)
print(text)

Transcribing an age-restricted video with browser cookies:

# Ensure yt-dlp can read browser cookies via:

# agent-reach install

# Then run transcription - yt-dlp automatically uses available cookies

from agent_reach.transcribe import transcribe

text = transcribe(
    "https://www.youtube.com/watch?v=restricted_id",
    provider="groq",
)
print(text)

Manual cookie file usage:

import subprocess

subprocess.run([
    "yt-dlp",
    "--cookies", "/home/user/.config/yt-dlp/cookies.txt",
    "-x", "--audio-format", "m4a",
    "--audio-quality", "0",
    "-o", "source.%(ext)s",
    "https://www.youtube.com/watch?v=example",
])

Summary

• Agent Reach treats YouTube as a backend-only channel, delegating all authentication to yt-dlp.
• Cookie files placed in ~/.config/yt-dlp/cookies.txt enable access to restricted videos without custom auth code.
• Browser extraction via --cookies-from-browser allows reuse of existing login sessions through the CLI install helper.
• Safety checks in _assert_safe_public_url() prevent SSRF before yt-dlp execution.
• JavaScript runtime configuration via render_ytdlp_fix_command() ensures compatibility with YouTube's streaming protocols.

Frequently Asked Questions

How does Agent Reach authenticate with YouTube for private videos?

Agent Reach does not implement direct YouTube authentication. Instead, it relies on yt-dlp's ability to read cookies from files or browsers. Users must provide authentication via ~/.config/yt-dlp/cookies.txt or configure browser cookie extraction through the CLI install helper.

What JavaScript runtime does Agent Reach require for YouTube processing?

Agent Reach requires Node.js or Deno to handle YouTube's JavaScript-heavy streaming protocols. The check() method in youtube.py detects available runtimes and ensures the yt-dlp config includes --js-runtimes node when Node.js is available.

Can Agent Reach access age-restricted YouTube videos?

Yes, by leveraging yt-dlp's cookie support. If the user provides valid authentication cookies—either exported from a browser or extracted automatically via --cookies-from-browser—yt-dlp can download age-restricted content and Agent Reach will transcribe it normally.

Where does Agent Reach store yt-dlp configuration files?

Configuration files are managed through get_ytdlp_config_path() in [agent_reach/utils/paths.py](https://github.com/Panniantong/Agent-Reach/blob/main/agent_reach/utils/paths.py), typically resolving to ~/.config/yt-dlp/ on Unix systems. The render_ytdlp_fix_command() helper ensures this directory and config file exist with proper JS runtime settings.

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