Examples

This page shows how you can use ytdl-sub for various use cases. These are the configs I personally use and have incorporated as part of the e2e tests.

Each example has a config.yaml and subscription.yaml. The config defines how you format your media, whereas the subscription defines what you download plus some additional configuring if needed.

Also note that kodi examples are applicable for jellyfin, emby, and plex with the XBMC Movies or XBMC TV Show Plex importer. We would like to improve Plex support, please chime in here if you have experience with importing custom videos with metadata.

Kodi/Jellyfin TV Shows

config.yaml

# This example shows how to download and format an entire Youtube channel
# to display in Kodi as a TV show. The directory format will look like
#
#   /path/to/youtube_tv_shows/My Favorite Youtube Channel
#       /Season 2021
#           s2021.e0317 - St Pattys Day Video.jpg
#           s2021.e0317 - St Pattys Day Video.mp4
#           s2021.e0317 - St Pattys Day Video.nfo
#       /Season 2022
#           s2022.e1225 - Merry Christmas.jpg
#           s2022.e1225 - Merry Christmas.mp4
#           s2022.e1225 - Merry Christmas.nfo
#       poster.jpg
#       fanart.jpg
#       tvshow.nfo
#
# The idea is to use dates as the numeric to represent season and episode
# numbers. Once downloaded, it can immediately be recognized by Kodi.
configuration:
  working_directory: '.ytdl-sub-downloads'

presets:

  ###############################################################################
  # FULL ARCHIVE
  # This preset will download every single video in a YouTube channel.
  yt_channel_as_tv:
    # YouTube channels are our source/download strategy
    # Use the channel avatar and banner images for Kodi
    youtube:
      download_strategy: "channel"
      channel_avatar_path: "poster.jpg"
      channel_banner_path: "fanart.jpg"

    # For advanced YTDL users only; any YTDL parameter can be set here.
    # To download age-restricted videos, you will need to set your cookie
    # file here as a ytdl parameter. For more info, see
    # https://ytdl-sub.readthedocs.io/en/latest/faq.html#download-age-restricted-youtube-videos
    #
    # ytdl_options:
    #   cookiefile: "path/to/cookie_file.txt

    # For each video downloaded, set the file and thumbnail name here.
    # We set both with {episode_name}, which is a variable we define in
    # the overrides section further below to represent our date-like episode
    # naming convention. Using override variables helps reduce copy-paste.
    #
    # Another field worth mentioning is maintain_download_archive=True. This
    # is generally a good thing to enable with channels because it will
    # store previously downloaded video ids to tell YTDL not to re-download
    # them on a successive invocation.
    output_options:
      output_directory: "{youtube_tv_shows_directory}/{tv_show_name_sanitized}"
      file_name: "{episode_name}.{ext}"
      thumbnail_name: "{episode_name}-thumb.jpg"
      maintain_download_archive: True

    # For each video downloaded, add an episode NFO file for it. We give it
    # the same date-like episode name using our {episode_name} variable, and
    # populate the NFO with available video metadata that Kodi will recognize.
    nfo_tags:
      nfo_name: "{episode_name}.nfo"
      nfo_root: "episodedetails"
      tags:
        title: "{title}"
        season: "{upload_year}"
        episode: "{upload_month}{upload_day_padded}"
        plot: "{description}"
        year: "{upload_year}"
        aired: "{upload_date_standardized}"

    # In the output directory, create a tvshow.nfo file. Kodi looks for this
    # in the root of the TV show directory to get the TV show (title) name.
    output_directory_nfo_tags:
      nfo_name: "tvshow.nfo"
      nfo_root: "tvshow"
      tags:
        title: "{tv_show_name}"

    # Overrides is a section where we can define our own variables, and use them in
    # any other section. We define our tv show directory and episode file name here,
    # which gets reused above for the video, thumbnail, and NFO file.
    overrides:
      youtube_tv_shows_directory: "/path/to/youtube_tv_shows"
      episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {title_sanitized}"

  ###############################################################################
  # RECENT ARCHIVE
  # This preset shows how you can download just the last 14 days-worth of videos
  # on each download invocation.
  yt_channel_as_tv__recent:
    # `preset` can be set to any other preset in the config, and will inherit all its defined fields.
    # This helps reduce copy-paste in the config.yaml
    preset: "yt_channel_as_tv"

    # We will add the `after` field onto `yt_channel_as_tv`'s YouTube channel download strategy.
    # This is saying 'only download videos uploaded in the last 2 weeks'
    youtube:
      after: "today-2weeks"

  ###############################################################################
  # ROLLING ARCHIVE
  # This example shows how to only keep the last 14-days worth of videos, and
  # delete the rest.
  yt_channel_as_tv__only_recent:
    # Reuse `yt_channel_as_tv__recent` to only download the last 2 weeks' of videos
    preset: "yt_channel_as_tv__recent"

    # This is saying "only keep files if they were uploaded in the last 2 weeks".
    # All other files that this subscription had previously downloaded will be
    # deleted.
    output_options:
      keep_files_after: "today-2weeks"

subscriptions.yaml

# This example shows how we can use the `kodi_tv_shows_config.yaml` preset
# to download channels in a few different ways. We will use made-up channels
# in each example.

###############################################################################
# LEVEL 1 - FULL ARCHIVE
#
# Subscription names are defined by you. We will call this one
# john_smith_archive because it will download every single video in
# john_smith's channel.
john_smith_archive:
  # We must define a preset to use from our config. The one that downloads the
  # entire YouTube channel is called "yt_channel_as_tv", so set that here.
  preset: "yt_channel_as_tv"

  # Our download strategy was Youtube channels. Define the channel url here
  # in our subscription.
  youtube:
    channel_url: "https://youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg"

  # Overrides can be defined per-subscription. If you noticed, we used
  # {tv_show_name} and {tv_show_name_sanitized} in our "yt_channel_as_tv"
  # preset. We intended to reserve that variable to be defined for each
  # individual subscription. Each override defined here will create a
  # '_sanitized' version that is safe for file systems.
  overrides:
    tv_show_name: "John /\ Smith"

###############################################################################
# LEVEL 2 - RECENT ARCHIVE
#
# Use the "yt_channel_as_tv__recent" preset to only download the last two
# weeks' worth of YouTube videos.
john_smith_recent_archive:
  preset: "yt_channel_as_tv__recent"
  youtube:
    channel_url: "https://youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg"
  overrides:
    tv_show_name: "John /\ Smith"

###############################################################################
# LEVEL 3 - ROLLING ARCHIVE
#
# Use the "yt_channel_as_tv__recent_only" preset to only download the last two
# weeks' worth of YouTube videos, and delete any existing older videos.
john_smith_rolling_archive:
  preset: "yt_channel_as_tv__only_recent"
  youtube:
    channel_url: "https://youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg"
  overrides:
    tv_show_name: "John /\ Smith"

Kodi/Jellyfin Music Videos

config.yaml

# This example shows how to download and format a Youtube video OR playlist
# to display in Kodi as a music video. Kodi requires music videos to be in
# a shared directory, so we will configure this to make the output directory
# formatted as:
#
#   /path/to/Music Videos
#       Elton John - Rocketman.jpg
#       Elton John - Rocketman.mp4
#       Elton John - Rocketman.nfo
#       System of a Down - Chop Suey.jpg
#       System of a Down - Chop Suey.mp4
#       System of a Down - Chop Suey.nfo
#       ...
#
configuration:
  working_directory: '.ytdl-sub-downloads'

presets:
  yt_music_video:
    # A single YouTube video is our source/download strategy. However, this
    # can be overwritten to download music videos from a "playlist", as we
    # will see in a preset below
    youtube:
      download_strategy: "video"

    # For advanced YTDL users only; any YTDL parameter can be set here.
    # To download age-restricted videos, you will need to set your cookie
    # file here as a ytdl parameter. For more info, see
    # https://ytdl-sub.readthedocs.io/en/latest/faq.html#download-age-restricted-youtube-videos
    #
    # ytdl_options:
    #   cookiefile: "path/to/cookie_file.txt

    # For each video downloaded, set the file and thumbnail name here.
    # We set both with {music_video_name}, which is a variable we define in
    # the overrides section further below to represent consistent naming format.
    output_options:
      output_directory: "{music_video_directory}"
      file_name: "{music_video_name}.{ext}"
      thumbnail_name: "{music_video_name}-thumb.jpg"

    # For each video downloaded, add a music video NFO file for it. Populate it
    # with tags that Kodi will read and use to display it in the music or music
    # videos section.
    nfo_tags:
      nfo_name: "{music_video_name}.nfo"
      nfo_root: "musicvideo"
      tags:
        artist: "{artist}"
        title: "{title}"
        album: "Music Videos"
        year: "{upload_year}"

    # Overrides is a section where we can define our own variables, and use them in
    # any other section. We define our music video directory and episode file name
    # here, which gets reused above for the video, thumbnail, and NFO file.
    overrides:
      music_video_directory: "path/to/Music Videos"
      music_video_name: "{artist_sanitized} - {title_sanitized}"

  # It is not always ideal to download all of an artist's music videos.
  # Maybe you only like one song of theirs. We can reuse our preset above
  # to download a single video instead.
  yt_music_video_playlist:
    preset: "yt_music_video"
    youtube:
      download_strategy: "playlist"

    # Setting maintain_download_archive=True is generally a good thing to enable
    # with playlists and channels because it will store previously downloaded
    # video ids to tell YTDL not to re-download them on a successive invocation.
    output_options:
      maintain_download_archive: True

subscriptions.yaml

# This example shows how we can use the `kodi_music_videos_config.yaml` preset
# to download music videos in a few different ways. We will use made-up artists
# in each example

###############################################################################
# LEVEL 1 - DOWNLOAD MUSIC VIDEO PLAYLIST

# Subscription names are defined by you. We will call this one john_smith
# for simplicity, and it will download every single video in john_smith's music
# video playlist. Many artists maintain a playlist of all their music videos,
# which makes this an easy way to grab all of them.
john_smith:
  # We must define a preset to use from our config. We named the one in the
  # config example "yt_music_video", so set that here.
  preset: "yt_music_video_playlist"

  # Since our preset download strategy is set to 'playlist', set the playlist url
  youtube:
    playlist_url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"

  # Overrides can be defined per-subscription. If you noticed, we used {artist}
  # and {artist_sanitized} in our "yt_music_video" preset. We intended to reserve
  # that variable to be defined for each individual subscription. Each override
  # defined here will create a '_sanitized' version that is safe for file systems.
  #
  # A note for Kodi music videos, it is important to make sure your artist name
  # exactly matches how it is formatted in Kodi itself, otherwise it will be
  # read in as a new artist
  overrides:
    artist: "John Smith and the Instrument Players"

###############################################################################
# LEVEL 2 - DOWNLOAD SINGLE MUSIC VIDEO

# It is not always ideal to download all of an artist's music videos.
# Maybe you only like one song of theirs. We can reuse our preset
# to download a single video instead.
#
# The only difference between this example and the one above is
# - preset
#     Use the music video preset, not the playlist preset
# - youtube.video_url
#     The video url to download
#
# Of course, defining yaml configuration to download a single video once
# and never again seems weird. Instead, we can perform this download via
# command:
#
#     ytdl-sub dl                                                        \
#         --preset "yt_music_video"                                      \
#         --youtube.video_url "https://youtube.com/watch?v=QhY6r6oAErg"  \
#         --overrides.artist "John Smith and the Instrument Players"
#
john_smith_one_hit_wonder:
  preset: "yt_music_video"
  youtube:
    video_url: "https://youtube.com/watch?v=QhY6r6oAErg"
  overrides:
    artist: "John Smith and the Instrument Players"

Read the Docs v: v0.2.0

Versions: latest; v0.2.0

Downloads

On Read the Docs: Project Home; Builds