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.

• Docker Compose
  • with CPU passthrough
  • with GPU passthrough
• Docker CLI
• Windows
• Unraid
• Linux
• Linux ARM
• PIP
• Local Install
• Local Docker Build

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.