ytdl-sub
Automate downloading and metadata generation with YoutubeDL.
ytdl-sub
is a command-line tool that downloads media via
yt-dlp
and prepares it for your favorite media player, including
Kodi,
Jellyfin,
Plex,
Emby,
and modern music players. No additional plugins or external scrapers are needed.
We recognize that everyone stores their media differently. Our approach for file and metadata formatting is to provide maximum flexibility while maintaining simplicity.
YouTube Channels as TV Shows
Plex
Jellyfin
Music Videos and Concerts
Kodi
Jellyfin
SoundCloud Albums and Singles
MusicBee (any file or tag-based music players)
Bandcamp Discography
Navidrome (any file or tag-based music servers)
How it Works
ytdl-sub
uses YAML configs to define a layout for how you want media to look
after it is downloaded. See our
walk-through guide
on how to get started. Ready-to-use
example configurations
can be found here alongside our
readthedocs
for detailed information on config fields.
Config
The config.yaml
defines how our downloads will look. For this example, let us
download YouTube channels and generate metadata to look like TV shows using
ytdl-sub's prebuilt presets. No additional plugins or programs are needed for
Kodi, Jellyfin, Plex, or Emby to recognize your downloads. This can also be
used to download any yt-dlp supported URL, including YouTube playlists, Bitchute channels, etc.
# Set the working directory which will be used to stage downloads
# before placing them in your desired output directory.
configuration:
working_directory: '.ytdl-sub-downloads'
# Presets are where you create 'sub-configs' that can can be
# merged together to dictate what is downloaded, how to format it,
# and what metadata to generate.
presets:
# Let us create a preset called `only_recent_videos` that will
# only download recent videos in the last 2 months.
only_recent_videos:
# Use the `date_range` plugin to specify ytdl-sub to only
# download videos after today MINUS {download_range}, which
# is an override variable that we can alter per channel.
date_range:
after: "today-{download_range}"
# Any yt-dlp argument can be passed via ytdl-sub. Let us set
# yt-dlp's `break_on_reject` to True to stop downloading after
# any video is rejected. Videos will be rejected if they are
# uploaded after our {download_range}.
ytdl_options:
break_on_reject: True
# Deletes any videos uploaded after {download_range}.
output_options:
keep_files_after: "today-{download_range}"
# Set the override variable {download_range} to 2months.
# This will serve as our default value. We can override
# this per channel or in a child preset.
overrides:
download_range: "2months"
####################################################################
# Now let us create a preset that downloads videos and formats
# as TV shows.
tv_show:
# Presets can inherit all attributes from other presets. Our
# `tv_show` preset will inherit these presets built into ytdl-sub.
preset:
# Let us specify all the TV show by date presets to support all
# players. You only need to specify one, but this ensures
# compatibility with all players.
- "kodi_tv_show_by_date"
- "jellyfin_tv_show_by_date"
- "plex_tv_show_by_date"
# Now we choose a preset that defines how our seasons and
# episode numbers look.
- "season_by_year__episode_by_month_day"
# Set override variables that will be applicable to all downloads
# in main presets.
overrides:
tv_show_directory: "/tv_shows" # Replace with desired directory
Subscriptions
The subscriptions.yaml
file is where we define content to download using
presets in the config.yaml
. Each subscription can overwrite any field used
in a preset.
# The name of our subscription. Let us create one to download
# ALL of Rick A's videos
rick_a:
# Inherit our `tv_show` preset we made above
preset:
- "tv_show"
# Set override variables to set the channel URL and the
# name we want to give the TV show.
overrides:
tv_show_name: "Rick A"
url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
# Let us make another subscription that will only download Rick A's
# video's in the last 2 weeks.
rick_a_recent:
# Inherit our `tv_show` AND `only_recent_videos` preset
# Bottom-most presets take precedence.
preset:
- "tv_show"
- "only_recent_videos"
# Set override variables for this subscription. Modify the
# `download_range` to only download and keep 2 weeks' worth
# of videos.
overrides:
tv_show_name: "Rick A"
url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
download_range: "2weeks"
The download can now be performed using:
ytdl-sub sub subscriptions.yaml
To preview what your output files before doing any downloads, you can dry run using:
ytdl-sub --dry-run sub subscriptions.yaml
One-time Download
There are things we will only want to download once and never again. Anything you can define in a subscription can be defined using CLI arguments. This example is equivalent to the subscription example above:
ytdl-sub dl \
--preset "tv_show" \
--overrides.tv_show_name "Rick A" \
--overrides.url "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
Download Aliases
In the config.yaml
, we can define aliases to make dl
commands shorter.
configuration:
dl_aliases:
tv: "--preset tv_show"
name: "--overrides.tv_show_name"
url: "--overrides.url"
The above command can now be shortened to
ytdl-sub dl \
--tv \
--name "Rick A" \
--url "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
Output
After ytdl-sub
runs, the end result will download and format the channel
files into something ready to be consumed by your favorite media player or
server.
/path/to/tv_shows/Rick AΓ
/Season 2021
s2021.e0317 - Pattys Day Video-thumb.jpg
s2021.e0317 - Pattys Day Video.mp4
s2021.e0317 - Pattys Day Video.nfo
/Season 2022
s2022.e1225 - Merry Christmas-thumb.jpg
s2022.e1225 - Merry Christmas.mp4
s2022.e1225 - Merry Christmas.nfo
poster.jpg
fanart.jpg
tvshow.nfo
Beyond TV Shows
The above example made heavy-use of ytdl-sub
prebuilt presets and hides many
features that are offered. ytdl-sub
strives to support any use case that first requires
a download via yt-dlp. Use ytdl-sub
to download, format, and convert media for your media
player to recognize downloads as:
- Movies
- TV shows
- From a single channel or playlist
- From multiple channels or playlists
- From individual videos
- Extracted audio as podcasts
- Music videos
- Music, including:
- Individual songs
- Albums
- Discographies
Installation
ytdl-sub
can be installed on the following platforms.
Contributing
There are many ways to contribute, even without coding. Please take a look in our GitHub Issues to submit a feature request, or pick up a bug.
Support
We are pretty active in our Discord channel if you have any questions. Also see our FAQ for commonly asked questions.