ytdl-sub

ytdl-sub is a command-line tool that orchestrates yt-dlp to download media and prepare it for media servers and players. It uses a declarative YAML configuration and preset system to control what to download and how files and metadata are produced.

Key Features

• Declarative subscriptions and presets written in YAML to describe channels, playlists, formats, and destination library layouts.
• Wraps and runs yt-dlp for downloads and can remux/transcode using FFmpeg/ffprobe when needed.
• Rich plugin system (audio_extract, chapters, subtitles, file_convert, embed_thumbnail, music_tags, nfo_tags, video_tags, etc.) to control metadata, tagging, thumbnails, and post-processing.
• Presets for media server targets and media types (Plex, Jellyfin, Emby, Kodi, music players) to produce naming, NFO files, and metadata formats those servers expect.
• Scripting and template functions for conditional filtering, custom variables, and fine-grained automation of downloads.
• Docker images provided (headless and GUI/code-server variant) plus a standalone executable and PyPI package; recommended deployment via Docker Compose or cron for automation.

Use Cases

• Archive YouTube channels or playlists as TV shows or seasons for Plex/Jellyfin/Emby with server-compatible metadata.
• Build and tag local music/video libraries (music videos, concerts, SoundCloud/Bandcamp imports) with embedded tags and external NFOs.
• Automate periodic downloads via scheduled runs (cron/container) to keep a local media library in sync.

Limitations and Considerations

• Requires external dependencies: Python 3.10+ and FFmpeg/ffprobe; these are mandatory for post-processing and packaging tasks.
• CLI-first tool aimed at power users; configuration is flexible but has a steeper learning curve than polished web-UIs.
• Relies on yt-dlp for site extractor correctness; changes to source sites may require updating yt-dlp and the tool's dependencies.

ytdl-sub is focused on providing flexible, reproducible control over media download and metadata generation rather than a one-click consumer UI. It is well-suited for users who need precise filename/metadata control and integration with media servers.