ytdl

yt-dlp Downloader

Download media from any yt-dlp-supported site as audio, video, or both, embed proper metadata + cover art, and transfer the result to an SSH remote configured when the plugin was enabled.

Two MCP tools are provided by the bundled youtube-dl server:

Tool	Purpose
`youtube_download`	Download one or more URLs and transfer them to the remote with rsync or scp.
`youtube_probe`	Read-only: resolve title/duration/uploader/format counts without downloading.

Defaults

Audio-first. mode defaults to audio, codec defaults to the configured audio_format (mp3 unless changed at enable time).
Destinations come from plugin config. Audio lands in the configured audio destination, video in the video destination. You do not normally pass remote, dest_path, or video_dest_path — they fall back to the user config.
Files are organized by artist. Output is Artist/Title [id].ext, with title, artist, album, date, and cover art embedded so media servers (Plex, etc.) index them cleanly.

Common usage

Download audio (the default) from a link:

youtube_download(urls="https://www.youtube.com/watch?v=...")

Download video at capped resolution:

youtube_download(urls="https://...", mode="video", max_height=1080)

Grab both audio and video (audio → music dest, video → movies dest):

youtube_download(urls="https://...", mode="both")

Re-pull a playlist and only fetch what's new:

youtube_download(urls="https://.../playlist?list=...", use_archive=true)

Check a target before a big download:

youtube_probe(urls="https://...")

Notes

YouTube mix/radio URLs (list=RD..., &start_radio=1) are auto-cleaned to the seed video so they don't resolve to an unrelated track.
Playlists are downloaded fully and flattened into per-artist folders.
On transfer failure the local staging copy is kept so the operation can be retried; on success it is removed unless keep_local=true.
yt-dlp auto-updates at server startup when stale (configurable), so a fresh session self-heals against extractor breakage.
yt-dlp and ffmpeg are resolved automatically: explicit env path, then PATH, then the per-user cache, then runtime download. Use YTDLP_PATH and FFMPEG_PATH only when you need known local binaries.

Operational controls

YTDLP_TIMEOUT_SECS controls each yt-dlp probe/download command timeout (default: 1800).
YTDLP_TRANSFER_TIMEOUT_SECS controls each SSH transfer phase timeout (default: 600).
YTDLP_PATH and FFMPEG_PATH override auto-resolution/auto-download with specific local binaries.
YTDLP_SHA256 and FFMPEG_SHA256 optionally require exact SHA-256 digests for the resolved yt-dlp and ffmpeg executables.
YTDLP_EXTRACTOR_ARGS is passed to yt-dlp --extractor-args, for example youtube:player_client=android when the default YouTube clients cannot fetch a video.
YTDLP_SSH_OPTS adds extra SSH options using shell-word syntax, for example -i "~/.ssh/ytdl key" -o ProxyJump=media-bastion. Malformed quoting is rejected.

Requirements (on the host running this plugin)

ssh / openssh-client
Passwordless key-based SSH auth to the configured remote
rsync is optional; transfers fall back to scp when rsync is unavailable
yt-dlp and ffmpeg are auto-resolved/auto-downloaded unless overridden with YTDLP_PATH / FFMPEG_PATH