GitHub – jmbannon/ytdl-sub: Automate downloading and metadata generation with YoutubeDL

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.