yt-dlp-direct

yt-dlp Direct

This skill is responsible for only one thing:

Directly use the locally installed yt-dlp CLI to handle online video or audio download tasks

Not responsible for:

Explaining copyright compliance policies
Bypassing platform DRM
Using browser manual screen recording instead of downloading
Reinstalling yt-dlp

One-sentence principle: if the user wants to download, extract audio, get subtitles, view formats, or grab playlists, prioritize directly using yt-dlp, do not first write a bunch of scripts.

When To Use

Applicable scenarios:

The user says "use yt-dlp to download this video"
The user says "help me extract it to mp3 / m4a"
The user says "download the subtitles too"
The user says "first see what formats are available"
The user says "download the entire playlist / channel / search results"
The user says "can this site use yt-dlp”

Not applicable scenarios:

The user just wants to know what yt-dlp is
The user wants to crack DRM or protected streams
The user wants to do complex media editing, and should really use ffmpeg

Preconditions

Confirm before starting:

yt-dlp is in PATH
The current directory or target directory is writable
If the task involves merging video and audio, transcoding, or embedding thumbnails, it is best to already have ffmpeg

Prioritize checking:

which yt-dlp
yt-dlp --version

If you need to determine whether ffmpeg is available, you can also check:

ffmpeg -version
ffprobe -version

Working Rules

By default, do a read-only probe first, then actually download
When unsure about the format, first -F
When the user has not specified output rules, prioritize giving a safe output template
For playlists, by default remind about the number of items and size risk
When login state is involved, prioritize --cookies-from-browser
When more stable YouTube support is needed, remember the JavaScript runtime / ejs dependency
Do not overwrite a large number of files without authorization; when necessary, explicitly specify the output path

Core Workflow

1. Inspect First

First determine whether the link can be recognized by the extractor:

yt-dlp --simulate --print "%(title)s" "<url>"

If you only want to view metadata without downloading:

yt-dlp --dump-single-json "<url>"

2. Check Formats Before Download

When the user wants to specify resolution, codec, or audio track, first check the formats:

yt-dlp -F "<url>"

If the user has no explicit requirement, usually prioritize:

yt-dlp -f "bv*+ba/b" "<url>"

This is also the combination approach currently preferred by yt-dlp by default.

3. Safe Single-Video Download

By default, it is recommended to include an output template:

yt-dlp -o "%(title)s [%(id)s].%(ext)s" "<url>"

If a fixed directory is needed:

yt-dlp -P "/target/dir" -o "%(title)s [%(id)s].%(ext)s" "<url>"

4. Extract Audio

When the user wants audio, prioritize:

yt-dlp -x --audio-format mp3 "<url>"

To more conservatively preserve high-quality audio formats:

yt-dlp -x --audio-format m4a "<url>"

5. Download Subtitles

Download only subtitles, not video:

yt-dlp --write-subs --write-auto-subs --skip-download "<url>"

If the user only wants a specific language:

yt-dlp --write-subs --sub-langs "en,zh-Hans,zh-Hant" --skip-download "<url>"

6. Playlists and Channels

When the user provides a playlist, first remind about the scale. Common commands:

yt-dlp --flat-playlist "<playlist-url>"
yt-dlp -I 1:10 "<playlist-url>"
yt-dlp -o "%(playlist_index)s - %(title)s [%(id)s].%(ext)s" "<playlist-url>"

First use --flat-playlist to view the entries, then decide whether to download all of them.

7. Search Shortcuts

If the user only has keywords and no direct link, you can use the search prefix:

yt-dlp "ytsearch5:Claude Code skills"

When only getting results without downloading immediately:

yt-dlp --simulate --print "%(title)s | %(webpage_url)s" "ytsearch5:Claude Code skills"

Authentication and Cookies

Many sites or private content require login state. Priority order:

--cookies-from-browser
--cookies <file>
Username/password or netrc

Frequently used usage:

yt-dlp --cookies-from-browser chrome "<url>"
yt-dlp --cookies-from-browser safari "<url>"
yt-dlp --cookies cookies.txt "<url>"

If the site requires browser fingerprinting or TLS impersonation, consider:

yt-dlp --impersonate chrome "<url>"

Output Templates

Default template recommendation:

%(title)s [%(id)s].%(ext)s

Commonly used for playlists:

%(playlist_index)s - %(title)s [%(id)s].%(ext)s

Archive by uploader:

%(uploader)s/%(upload_date>%Y-%m-%d)s - %(title)s [%(id)s].%(ext)s

Format and Postprocessing Notes

Merging audio and video, advanced transcoding, and embedding thumbnails usually depend on ffmpeg
-x extracts audio, it does not copy the audio track as-is
To control the container or codec, prioritize specifying -f、-S、--remux-video、--recode-video

Common examples:

yt-dlp -S "res:1080,ext:mp4:m4a" "<url>"
yt-dlp --remux-video mp4 "<url>"
yt-dlp --embed-thumbnail --add-metadata "<url>"

Supported Sites

yt-dlp Many sites are supported, but being "listed in the list" doesn't mean it will definitely work today.

Order of judgment:

First try --simulate
then check whether the error is login, region, format, or site change
If you really need to confirm the extractor name, check the supported sites list

Read when needed:

references/high-frequency-patterns.md

Output Contract

After execution, the reply should at least state:

what command was run
whether it was a successful probe, formats were listed, or an actual download occurred
where the file landed
if it failed, whether it got stuck on the extractor, authentication, format, network, or local dependencies

Safety and Boundaries

Do not proactively help users bypass DRM
Do not promise that all protected sites can be downloaded
Before scraping large playlists or channels, remind about size and quantity
Remind before overwriting existing files
Do not copy sensitive information from command output with cookies into the reply

Troubleshooting

YouTube or site changed

First check the version:

yt-dlp --version

If it is too old, remind the user to update.

Format merge problems