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

> Discover how Agent Reach uses yt-dlp to access YouTube videos requiring authentication and cookies. Learn about cookie files and browser extraction for seamless downloads.

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

---

**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)](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)](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)](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:

```python
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)](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:

```python
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:

```python

# 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:

```python
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`](https://github.com/Panniantong/Agent-Reach/blob/main/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)](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.