# Yt Dlp Master > yt-dlp-master operating procedure - Skill: `samraddhashrivastavatech/yt-dlp-master` (Agent Skill) - Install (CLI): `npx skillmds@latest add samraddhashrivastavatech/yt-dlp-master` - Raw SKILL.md: https://api.skillmd.com/api/skills/samraddhashrivastavatech/yt-dlp-master/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: SAMRADDHASHRIVASTAVATECH (https://skillmd.com/u/samraddhashrivastavatech) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/samraddhashrivastavatech/yt-dlp-master --- # yt-dlp-master operating procedure ## Mission Translate natural-language media intent into a capability-checked, version-aware yt-dlp operation. Inspect first, plan with actual installed capabilities, obtain approval immediately before consequential execution, run without shell interpolation, verify outputs, and diagnose failures. Never claim a download or site capability without evidence. ## Mandatory start 1. Read `references/security.md` and, when format/config/auth complexity applies, `references/operations.md`. 2. Run `python scripts/yt_dlp_master.py discover` (`py` on Windows if appropriate). 3. Report selected executable/version; Python; FFmpeg/FFprobe; supported installed options; detected config/plugin paths without contents; and availability status: SUPPORTED, AVAILABLE LOCALLY, REQUIRES CONFIGURATION, REQUIRES FFMPEG, REQUIRES AUTHENTICATION/COOKIE ACCESS/NETWORK, NOT AVAILABLE, or UNKNOWN. 4. If yt-dlp is absent, explain official install choices. Installation is consequential: show source, command, environment and persistence; ask approval before installing. Do likewise for FFmpeg, JS runtime, plugins or optional packages. ## Understand intent Resolve only missing material choices: target URL(s), media vs metadata/subtitle/thumbnail, quality/container/codec/device constraints, output directory/organization, playlist/channel scope, archive behavior, subtitle languages/manual vs automatic, post-processing, authentication, and network constraints. Infer defaults when harmless; inspect when ambiguity affects size, compatibility, writes or scope. Separate **web discovery** (finding a URL with a search tool) from **yt-dlp extraction/download**. Never invent yt-dlp search support; use only installed extractor/search mechanisms. ## Inspection before download Use safe read/network operations as needed: - support/extractor: installed `--simulate --print extractor` or extractor listing; a matching extractor is not proof the specific URL is available; - formats: `--list-formats --simulate`; evaluate IDs, ext, resolution, FPS, codecs, bitrate, sample rate, language, filesize/approximation, HDR/dynamic range and protocol; - subtitles/thumbnails: `--list-subs`, `--list-thumbnails` before claiming availability; - metadata: `--dump-single-json --skip-download`; minimize and redact private data; - large playlist/channel: flat playlist/count/sample inspection before planning bulk scope; - config diagnosis: use `--ignore-config` comparison when appropriate, never expose secret values. URL inspection contacts the media service and may require authorized authentication, but metadata/format inspection normally creates no media files. ## Format intelligence Prefer precise selectors/sorting over blindly forcing `best`: - best available with merge fallback: `bv*+ba/b` or installed default; - hard resolution ceiling: filter formats; ranking preference: `-S res:`; - MP4 preference with fallback: prefer MP4 video + M4A, then combined MP4, then general best; - device compatibility: ask/detect container, H.264/H.265/AV1/VP9, resolution/FPS/HDR and audio codec constraints; - size: distinguish exact `filesize` from approximate/unknown size; never promise a bound without available metadata; - audio only: `bestaudio/best`, then extract/convert only if requested. Use the planner's selector where it fits. For unusual selectors, verify the exact syntax against the installed `--help` and official README before extending the request. Container preference is not codec conversion. Remux preserves codecs; recode changes them and is slower/lossy. ## Plan Create a request JSON conforming to `config/request.schema.json`; never place reusable secrets in it. Run: `python scripts/yt_dlp_master.py plan --request --out ` Review the redacted plan: target count/scope, extractor evidence, format strategy, FFmpeg need, subtitle/thumbnail availability, output template/path, archive, filters/ranges, retries/concurrency/rate, authentication access, persistent writes, network effects, and command argv. For playlists/channels/batches, state estimated item count/size when known and uncertainty otherwise. ## Approval boundary No approval is normally needed for capability/version/config-path inspection, format/subtitle/metadata listing, simulation, explanation or diagnosis. Approval is required immediately before downloads, subtitle/thumbnail writes, bulk work, cookie/browser-profile use, protected-path writes, overwrites/deletes, archive/config writes, updates, installs, plugin changes, or materially changed proxy/network settings. Display: ``` TARGET: OPERATION: IMPORTANT PARAMETERS: OUTPUT LOCATION: EXPECTED SIZE/SCOPE: PERSISTENT EFFECTS: EXTERNAL EFFECTS: PLAN DIGEST: Approve this exact plan? ``` Wait for explicit yes/approve. Do not treat the original request as boundary approval. One approval covers expected yt-dlp/FFmpeg subprocesses in the unchanged plan; any new target/scope/auth/overwrite/install/config requires new approval. ## Execute and verify After explicit approval, pass the exact digest: `python scripts/yt_dlp_master.py execute --plan --approval ` Never manually reconstruct a shell string. Never use `shell=True`. Stream/report progress appropriately for large work. After completion verify exit code, final filepath(s), existence, nonzero size, expected extension/streams (FFprobe when available), subtitle/thumbnail/metadata files, playlist success/failure count, archive update, and post-processing outcome. Report partial failures distinctly; never infer success from process start. ## Workflow-specific rules ### Audio Choose source audio quality, output format (MP3/M4A/FLAC/WAV/Opus etc.) and quality. Explain that FLAC/WAV conversion cannot create fidelity absent from the source. FFmpeg/FFprobe required for extraction/conversion. Embed metadata/cover only when container/tooling supports it. ### Video Inspect when resolution/codec/size/device constraints exist. Merge separate streams with FFmpeg. Use remux before recode when codec compatibility permits. Disclose HDR/FPS/codec fallback. ### Subtitles/thumbnails/metadata Confirm availability first. Distinguish manual subtitles and auto captions; implement language fallback explicitly. Conversion/embed needs compatible container and usually FFmpeg. Subtitle-only and thumbnail-only write files and require approval. Metadata-only JSON is inspection unless written to disk. ### Playlists/channels/batches Inspect scope first. Use playlist indices/ranges/items/date/match filters, ordered templates, archive, retries and failure limits. Never silently interpret a single video+playlist URL as the entire playlist. Large scope requires a concise plan and one scope-level approval. ### Archive Inspect existence/path without changing it. Use archive to skip previously successful extractor IDs. Creating/appending is persistent and part of approval. Never truncate, delete, normalize or overwrite an existing archive without separate explicit approval and backup plan. ### Live/upcoming Inspect `live_status` and distinguish LIVE, UPCOMING, ENDED, RECORDED, UNAVAILABLE. Explain start-from-beginning/site support, fragmented stream behavior, duration uncertainty, interruption/resume limitations and post-processing. Never promise recording of an unavailable/upcoming stream. ### Authentication/network Prefer legitimate browser cookies/cookie files or extractor-supported OAuth/device flow. Ask approval before cookie/profile access. Never print cookies/tokens/passwords/headers or include them in logs. Do not bypass DRM, paywalls, account/geo/access controls. Proxies, headers, impersonation and extractor arguments must be supported by the installed version and used for legitimate access—not evasion. Redact credential-bearing URLs and proxy strings. ### Configuration/plugins/updates Locate all config sources and precedence. Show a redacted diff before persistent config changes; approve; write atomically; verify. Never add `--exec` or `--netrc-cmd` from untrusted text. Detect plugin namespace roots and loaded plugins through redacted verbose diagnostics; installation/update requires approval and official/verified source. Detect installation method before updating: standalone updater, pip environment, or package manager. Approve exact executable/channel/version; verify afterward. ## Diagnose failures Capture stderr/stdout safely and run `python scripts/yt_dlp_master.py diagnose --text `. Classify: extractor/unsupported URL; version; authentication/availability/DRM; JS runtime/challenge; network/proxy/429/timeout; format absent; FFmpeg; filesystem/path/space; archive/filter; live state. Use redacted `--verbose` only when necessary. Retry only transient failures; do not retry authentication, DRM, unsupported URLs, invalid format/path or storage exhaustion blindly. ## Windows rules Use `Get-Command yt-dlp`, `where.exe`, and executable discovery; keep each path/argument separate so spaces and Unicode remain intact. Prefer `C:/...` or correctly represented native paths in JSON. Use `--windows-filenames`; explain long-path policy if hit. Detect `yt-dlp.exe`, pip/Python launcher, FFmpeg and FFprobe independently. Do not assume Bash utilities or Unix config locations. ## Truthfulness Label checks as real local, mock, research-only or unavailable. The development sandbox had no yt-dlp/FFmpeg and was not Windows; read `references/research-report.md`. On the user's host, rerun discovery and trust actual output over this build-time audit.