By name: yt-dlp description: Download audio/video from YouTube and other sites using yt-dlp. Use when the user asks to download music, songs, albums, podcasts, or video from YouTube or similar platforms. Triggers on 'download song', 'get mp3', 'yt-dlp', 'youtube download', 'rip audio'.
yt-dlp — Media Downloads
Download audio/video from YouTube (and 1000+ other sites) via yt-dlp CLI.
Installation
pip3 install --break-system-packages yt-dlp
Note: On macOS with system Python, --break-system-packages is required (PEP 668).
Common Workflows
Download as MP3 (best quality)
yt-dlp -x --audio-format mp3 --audio-quality 0 -o "$HOME/Documents/%(title)s.%(ext)s" "ytsearch1:ARTIST TITLE"
Download with custom filename
yt-dlp -x --audio-format mp3 --audio-quality 0 -o "$HOME/Documents/Artist - Title.%(ext)s" "ytsearch1:Artist Title"
Download from direct URL
yt-dlp -x --audio-format mp3 --audio-quality 0 -o "$HOME/Documents/%(title)s.%(ext)s" "https://www.youtube.com/watch?v=XXXX"
Download video (best quality)
yt-dlp -f "bestvideo+bestaudio" --merge-output-format mp4 -o "$HOME/Documents/%(title)s.%(ext)s" "URL"
Metadata only (no download)
yt-dlp --dump-json "ytsearch1:query" | jq '{title, duration, url}'
Key Flags
| Flag | Purpose |
|---|---|
-x |
Extract audio only |
--audio-format mp3 |
Convert to mp3 |
--audio-quality 0 |
Best quality (VBR ~245kbps) |
-o TEMPLATE |
Output filename template |
-f 2 |
Download format #2 (often 360p mp4) |
--cookies-from-browser chrome |
Use browser cookies for age-gated content |
ytsearch1:query |
Search YouTube, take first result |
ytsearch5:query |
Search YouTube, take first 5 results |
Output Templates
| Template | Expands to |
|---|---|
%(title)s |
Video title |
%(uploader)s |
Channel name |
%(duration)s |
Duration in seconds |
%(ext)s |
File extension |
%(playlist_index)s |
Index in playlist |
Pitfalls
- JS runtime warning: "No supported JavaScript runtime" warning appears but downloads still work via Android API fallback. Install
denoto suppress and get all formats. - Google Drive sync: On this machine, Google Drive mounts at
~/Library/CloudStorage/GoogleDrive-USER_EMAIL/My Drive/, NOT at~/Documents/. If the user wants files on Google Drive, output there. - Playlists: Add
--no-playlistto avoid downloading entire playlists when given a video URL that's part of one. - Rate limiting: YouTube may throttle. Add
--sleep-interval 3for batch downloads. - Age-gated content: Use
--cookies-from-browser chromeor--cookies cookies.txt.
File Delivery
After downloading, send the file back to the user:
MEDIA:/absolute/path/to/file.mp3