yt-dlp Agent — YouTube & Video CLI

Agent-native CLI wrapper for yt-dlp. Oxylabs ISP proxy by default. All commands return JSON for pipeline use.

Install

cd D:\ClaudeDev\00_GITHUB\cliit\clis\ytdlp-agent
pip install -e .

Proxy Rule

All YouTube and video downloads must use the Oxylabs proxy (home IP rule). The --no-proxy flag is available for non-scraping one-off checks.

Commands

download — video or audio

ytdlp-agent download <url>                    # MP4, current dir
ytdlp-agent download <url> -o D:/Downloads   # custom dir
ytdlp-agent download <url> --format mp3      # extract MP3
ytdlp-agent download <url> --format wav      # extract WAV
ytdlp-agent download <url> --json            # JSON output
ytdlp-agent download <url> --no-proxy        # bypass proxy

transcript — captions as plain text

Downloads VTT subtitles, strips timestamps and HTML, deduplicates lines.

ytdlp-agent transcript <url>
ytdlp-agent transcript <url> --lang es
ytdlp-agent transcript <url> -o D:/Transcripts --json

info — metadata

Returns: id, title, uploader, channel, duration, view_count, like_count, upload_date, description (first 500 chars), thumbnail, formats.

ytdlp-agent info <url>
ytdlp-agent info <url> --json

audio — MP3 extract

ytdlp-agent audio <url>
ytdlp-agent audio <url> -o D:/Audio --json

thumbnail — grab thumbnail

ytdlp-agent thumbnail <url>
ytdlp-agent thumbnail <url> -o D:/Thumbs

playlist — download playlist

ytdlp-agent playlist <playlist_url>
ytdlp-agent playlist <playlist_url> --format mp3 -o D:/Downloads/playlist
ytdlp-agent playlist <playlist_url> --info-only --json   # metadata only

channel — channel videos

ytdlp-agent channel <channel_url> --limit 10
ytdlp-agent channel <channel_url> --info-only --json

search — search YouTube

ytdlp-agent search "how to fix roof leak" --limit 5 --json

JSON Output Schema

{
  "ok": true,
  "url": "https://youtube.com/...",
  "file": "/path/to/output.mp4",
  "title": "Video Title",
  "duration_seconds": 127,
  "format": "mp4"
}

Agent Pipeline Pattern

import subprocess, json

result = subprocess.run(
    ["ytdlp-agent", "transcript", video_url, "--json"],
    capture_output=True, text=True
)
data = json.loads(result.stdout)
if data["ok"]:
    print(data["transcript"])

Related Topics

• [[youtube-fetch]] — lightweight YouTube metadata + transcript sub-skill
• [[yt-transcript-pipeline]] — automated daily transcript vault
• [[social-transcript-extractor]] — social platform transcripts via API
• [[assemblyai-transcription]] — AI-powered audio intelligence layer

#video-sop #ytdlp #youtube #download #transcript #cli #proxy