YouTube Acquisition

What this skill does

# YouTube Acquisition

Comprehensive yt-dlp command patterns for downloading video and audio content from YouTube, Vimeo, SoundCloud, and other supported platforms. Includes quality selection strategies, format filtering, the SABR 403 workaround, metadata extraction, and batch operations.

## Overview

**yt-dlp** is the primary tool for media acquisition from YouTube and 1000+ other sites. This skill documents proven patterns from production use, including workarounds for the n-challenge / EJS gate, PO-token requirements, and the older SABR 403 issue.

**Key Capabilities**:
- Download best available quality (video + audio)
- Extract audio-only in multiple formats
- Handle playlists and channels
- Embed metadata and thumbnails
- Download subtitles and auto-captions
- Work around platform restrictions

## Prerequisites (#1229)

As of 2026, basic format selectors return only image storyboards on most YouTube videos until two relatively new gates are satisfied. **Read this section before any acquisition attempt** — running yt-dlp without these prerequisites produces "Only images are available for download" failures that look like format-selector bugs but aren't.

### 1. n-challenge / EJS solver

YouTube returns ciphered streaming URLs whose `n` parameter must be transformed by JavaScript extracted from the player. yt-dlp delegates this to the `yt-dlp-ejs` plugin plus a JS runtime. Without both, all real formats are filtered out and only `sb*` storyboard formats remain.

```bash
# Install the EJS plugin
pip install --user yt-dlp-ejs

# JS runtime — deno preferred, node accepted
which deno || sudo apt install -y deno   # Debian/Ubuntu
# OR: yt-dlp --js-runtimes node:/usr/bin/node ...
```

Reference: <https://github.com/yt-dlp/yt-dlp/wiki/EJS>

### 2. PO Token (Proof of Origin)

Many client variants (`mweb`, `ios`, `web`) demand a Proof-of-Origin token tied to a logged-in / browser-attested session. Without a PO token provider those clients are skipped, narrowing the available format list. Standard provider:

```bash
pip install --user bgutil-ytdlp-pot-provider
```

Reference: <https://github.com/yt-dlp/yt-dlp/wiki/PO-Token-Guide>

### 3. Plugin discovery — install yt-dlp via pip, NOT the standalone zipapp

This is the gotcha that bites operators most often. The standalone yt-dlp **zipapp** (the form distributed at `/usr/local/bin/yt-dlp` from the official static download) does not expose user site-packages to its plugin-discovery path. Even after `pip install --user yt-dlp-ejs`, a zipapp invocation will silently fail to find the EJS solver. Symptoms: `n challenge solving failed` warnings even after installing the plugin.

The fix is to install yt-dlp itself via pip so it shares `site-packages` with the EJS plugin, then ensure `~/.local/bin` precedes `/usr/local/bin` on PATH:

```bash
pip install --user --break-system-packages yt-dlp-ejs   # plugin
pip install --user --break-system-packages -U yt-dlp    # 2026.03.17+ — same site-packages
export PATH="$HOME/.local/bin:$PATH"

# Verify the EJS solver is discovered
~/.local/bin/yt-dlp -F "https://www.youtube.com/watch?v=VIDEO_ID"
# Should now list real formats, not just sb*
```

After this, downloads typically succeed automatically — yt-dlp's EJS solver may even fall back to the `android_vr` client without needing the JS runtime.

## Basic Download Patterns

### Best Quality Video + Audio

Download highest quality video and audio, merge into single file.

```bash
# Recommended: Let yt-dlp choose best combination
yt-dlp "VIDEO_URL"

# Explicit best video+audio merge
yt-dlp -f "bestvideo+bestaudio" "VIDEO_URL"

# Prefer MP4 container
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]" --merge-output-format mp4 "VIDEO_URL"

# With metadata and thumbnail embedding
yt-dlp -f "bestvideo+bestaudio" \
  --embed-metadata \
  --embed-thumbnail \
  --embed-subs \
  "VIDEO_URL"
```

### Failure-Mode Triage (#1229)

Match the symptom to the right gate before changing format selectors. Three distinct failures look similar but require different fixes:

| Symptom | Cause | Fix |
|---|---|---|
| `-F` lists only `sb0..sb3` storyboard formats; warning `n challenge solving failed`, `Only images are available` | n-challenge / EJS missing | Install `yt-dlp-ejs` and a JS runtime (see Prerequisites). Most failures resolve here. |
| Client-specific 403s; warning `mweb formats require a GVS PO Token` or similar | PO token required | Install `bgutil-ytdlp-pot-provider` (see Prerequisites). |
| Explicit-format 403 on `bestvideo[ext=mp4]+bestaudio[ext=m4a]` selectors against newer videos | SABR | Simplify to `best[ext=mp4]/best` (below). |

#### SABR 403 (legacy fix — keep for explicit-selector failures)

```bash
# BROKEN (SABR 403 on explicit selectors):
yt-dlp -f "bestvideo[ext=mp4]+bestaudio[ext=m4a]" "VIDEO_URL"

# WORKS (SABR-compatible):
yt-dlp -f "best[ext=mp4]/best" "VIDEO_URL"

# Audio-only SABR-safe:
yt-dlp -f "bestaudio/best" -x --audio-format mp3 "VIDEO_URL"
```

**Why this still helps even with EJS in place**: `best[ext=mp4]/best` lets yt-dlp pick a single combined stream rather than negotiating separate video/audio tracks, which sidesteps both SABR 403s and several PO-token edge cases.

### Audio-Only Extraction

Extract audio track without video.

```bash
# Best audio quality, convert to MP3
yt-dlp -f "bestaudio" -x --audio-format mp3 "VIDEO_URL"

# FLAC (lossless)
yt-dlp -f "bestaudio" -x --audio-format flac "VIDEO_URL"

# Opus (high quality, small size)
yt-dlp -f "bestaudio" -x --audio-format opus "VIDEO_URL"

# M4A (AAC, good compatibility)
yt-dlp -f "bestaudio" -x --audio-format m4a "VIDEO_URL"

# MP3 with bitrate specification
yt-dlp -f "bestaudio" -x --audio-format mp3 --audio-quality 320K "VIDEO_URL"

# SABR-safe audio extraction
yt-dlp -f "bestaudio/best" -x --audio-format mp3 "VIDEO_URL"
```

**Audio Quality Ladder**:
1. **FLAC** - Lossless, large files, archival quality
2. **Opus** - Best quality/size ratio, not universally supported
3. **M4A/AAC 256kbps** - Excellent quality, wide compatibility
4. **MP3 320kbps** - Good quality, universal compatibility
5. **MP3 192kbps** - Acceptable quality, smaller files

### Specific Resolution

Download specific video resolution.

```bash
# 1080p MP4
yt-dlp -f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]" "VIDEO_URL"

# 720p (standard HD)
yt-dlp -f "bestvideo[height<=720]+bestaudio" "VIDEO_URL"

# 4K (2160p)
yt-dlp -f "bestvideo[height<=2160]+bestaudio" "VIDEO_URL"

# SABR-safe resolution preference
yt-dlp -f "best[height<=1080]/best" "VIDEO_URL"
```

### Specific Format Codes

Use YouTube format codes directly (use `yt-dlp -F URL` to list available formats).

```bash
# List all available formats
yt-dlp -F "VIDEO_URL"

# Download specific format code
yt-dlp -f 137+140 "VIDEO_URL"  # 1080p video (137) + M4A audio (140)

# Fallback chain
yt-dlp -f "137+140/136+140/best" "VIDEO_URL"  # Try 1080p, then 720p, then best
```

**Common YouTube Format Codes**:
- **137**: 1080p MP4 video
- **136**: 720p MP4 video
- **140**: M4A 128kbps audio
- **251**: Opus 160kbps audio
- **bestaudio**: Highest quality audio available

## Playlist Operations

### Download Entire Playlist

```bash
# All videos in playlist
yt-dlp "PLAYLIST_URL"

# Playlist with numbering
yt-dlp -o "%(playlist_index)s - %(title)s.%(ext)s" "PLAYLIST_URL"

# Playlist to specific directory
yt-dlp -o "~/Music/%(playlist)s/%(title)s.%(ext)s" "PLAYLIST_URL"

# Audio-only playlist
yt-dlp -f "bestaudio" -x --audio-format mp3 "PLAYLIST_URL"
```

### Playlist Range Selection

```bash
# Download items 1-10
yt-dlp --playlist-start 1 --playlist-end 10 "PLAYLIST_URL"

# Download every other video
yt-dlp --playlist-items "1,3,5,7,9" "PLAYLIST_URL"

# Skip first 5 videos
yt-dlp --playlist-start 6 "PLAYLIST_URL"

# Download only specific item numbers
yt-dlp --playlist-items "1,5,10,15" "PLAYLIST_URL"
```

### Reverse Playlist Order

```bash
# Download oldest-first instead of newest-first
yt-dlp --playlist-reverse "PLAYLIST_URL"