6. Modifying Your Config for Your Media Player

At this point in the walk-through, we have ytdl-sub configured to download videos, playlists, or channels, and can place the video and thumbnail files into a desired folder. We can watch them via navigating the file system and opening them in VLC or other desktop video players.

ytdl-sub was written to support this use-case as well as format videos to watch them in Kodi, Jellyfin, Plex, Emby, or any other media player/server.

We have tested Kodi, Jellyfin, and Emby. We do not use Plex, and are unsure how it scrapes custom videos. If you use Plex, any help would be appreciated to contribute and test ytdl-sub to make it work.

Going forward, we will show how to make YouTube videos display as TV shows in Kodi, Jellyfin, and Emby. For simplicity, we will just say Kodi because both Jellyfin and Emby adopted Kodi's NFO metadata structure, and scrape videos in the same manner.

Displaying Videos as TV Shows

Having YouTube videos display as TV Shows in Kodi is the perfect way to organize them. We can

Have channels be their own TV show
Have playlists be their own TV show
Assign single videos, playlists, or channels to a TV show name we come up with

Our current subscription saves videos to Music Videos/ and Rick's channel's name, Rick Astley/. Let's make these show as separate TV shows with their respective names.

TV Show Structure

Most TV shows follow the same structure, where you have

The TV show itself
Seasons
Episodes

We want Music Videos and Rick Astley to be their own TV shows. We need to decide how to represent seasons and episodes. What we have found to work well is setting the season to be the year of when the video was uploaded, and the episode to be the month and day combined. Let's create additional override variables in our yt_video preset to show this in practice.

    overrides:
      video_name: "{upload_date_standardized}.{title_sanitized}"
      video_type: "{channel}"
      video_path: "{video_type_sanitized}/{video_name}"
      season: "{upload_year}"
      episode: "{upload_month}{upload_day_padded}"

We set the season to be {upload_year} and episode to be {upload_month}{upload_day_padded}. Why pad the day? Without it, episodes will be out of order. Suppose we have two videos uploaded on 2021-10-04 and 2021-05-23.

Episodes formatted as {upload_month}{upload_day} would be

104 (October 4th)
523 (May 23rd)

The numbers do not have the same ordering as the date - October 4th's episode number should be greater than May 23rd's.

Episodes formatted as {upload_month}{upload_day_padded} would be

1004 (October 4th)
523 (May 23rd)

October 4th's episode number is now greater than May 23rd's.

Naming TV Show Episode Files

Kodi's TV show file structure is relatively straight forward, it looks like:

TV Shows/
  Breaking Bad/
    Season 1/
      s01e01.Pilot.mp4
    Season 2/
      ...

We need our config to save videos in this format. Let's modify our override variables in the yt_video preset to have more representative names, and place files in this structure.

    overrides:
      tv_show_name: "OVERRIDE IN SUBSCRIPTION"
      season: "{upload_year}"
      episode: "{upload_month}{upload_day_padded}"
      episode_padded: "{upload_month_padded}{upload_day_padded}"
      episode_file_name: "s{season}e{episode_padded}.{title_sanitized}"
      episode_path: "Season {season}/{episode_file_name}"

We created the variable tv_show_name and set it to an obnoxious capitalized string. We did this for numerous reasons:

If we had set it to {channel}, downloading a playlist containing videos from multiple channels would create many new TV show folders
Channel names are often usernames that are not ideal for TV Show names, like videogamedunkey vs explicitly setting Dunkey
When override variables contain source variables within them, they cannot be used in OverridesStringFormatValidators. We will touch on this later.

We also created a new variable called episode_padded. This is used in episode_file_name to better order episode files when viewing them in the file system. episode_path contains our full path for saving the video with the appropriate TV show, season, and episode.

Let's update our config and subscriptions with our new override variable names. We are also going to add a few lines to download channel artwork, and format it so it shows in Kodi. Changed/added lines from our prior config are denoted with a comment above them.

Updating our Configs

config.yaml

configuration:
  working_directory: '/tmp/ytdl-sub-downloads'
  dl_aliases:
    video: "--preset yt_video"
    video-url: "--youtube.video_url"
    # changed from video-type: "--overrides.video_type"
    tv-show-name: "--overrides.tv_show_name"
    single-music-video: "--preset yt_video --overrides.tv_show_name 'Music Video' --youtube.video_url"

presets:
  yt_video:
    youtube:
      download_strategy: "video"

    output_options:
      # changed from "/config/first_config/output_videos"
      output_directory: "/config/first_config/output_videos/{tv_show_name_sanitized}"
      # changed from "{video_path}.{ext}"
      file_name: "{episode_path}.{ext}"
      # changed from "{video_path}.{thumbnail_ext}"
      thumbnail_name: "{episode_path}-thumb.{thumbnail_ext}"

    overrides:
      tv_show_name: "OVERRIDE IN SUBSCRIPTION"
      season: "{upload_year}"
      episode: "{upload_month}{upload_day_padded}"
      episode_padded: "{upload_month_padded}{upload_day_padded}"
      episode_file_name: "s{season}e{episode_padded}.{title_sanitized}"
      episode_path: "Season {season}/{episode_file_name}"

  yt_playlist:
    preset: "yt_video"
    youtube:
      download_strategy: "playlist"
    output_options:
      maintain_download_archive: True

  yt_channel:
    preset: "yt_playlist"
    youtube:
      download_strategy: "channel"
      # added: downloads channel avatar and banner to the output directory
      channel_avatar_path: "poster.jpg"
      channel_banner_path: "fanart.jpg"

  yt_channel_recent:
    preset: "yt_channel"
    youtube:
      after: "now-6months"
    output_options:
      keep_files_after: "now-6months"

subscription.yaml

rick_a_music_video_playlist:
  preset: "yt_playlist"
  youtube:
    playlist_url: "https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"
  overrides:
    # changed from video_type: "Music Videos"
    tv_show_name: "Music Videos"
rick_a_channel:
  preset: "yt_channel_recent"
  youtube:
    channel_url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
  # added explicit tv_show_name override
  overrides:
    tv_show_name: "Rick Astley"

We now use {tv_show_name_sanitized} in the output_options.output_directory. This makes it so all file paths within the config are relative to this directory. In addition, any download archive JSON files will now reside in the TV show's respective directory.

If we had set tv_show_name as {channel}, our config would raise a validation error. This is because {channel} is a source variable and output_options.output_directory cannot use source variables because it needs to be a static string with respect to the subscription. In our docs, any field denoted as a OverridesStringFormatterValidator must meet this condition.

We also changed output_options.thumbnail_name to have -thumb at the end of the file name. This a Kodi convention for naming thumbnails.

Redownloading Subscriptions with Config Changes

Since we already downloaded our subscriptions and they are maintained by a download archive, we unfortunately have to delete what we have and redownload. Let's do that with

rm -rf /config/first_config/output_videos

Now let's dry run to make sure our config is working as expected.

ytdl-sub --dry-run sub

[ytdl-sub] Downloads for rick_a_music_video_playlist:
Files created in '/config/first_config/output_videos/Music Videos'
----------------------------------------
.ytdl-sub-rick_a_music_video_playlist-download-archive.json
Season 2009/s2009e1025.Rick Astley - Cry for Help (Official Music Video)-thumb.jpg
Season 2009/s2009e1025.Rick Astley - Cry for Help (Official Music Video).webm
Season 2009/s2009e1025.Rick Astley - Hold Me In Your Arms (Official Music Video)-thumb.jpg
Season 2009/s2009e1025.Rick Astley - Hold Me In Your Arms (Official Music Video).webm
Season 2009/s2009e1025.Rick Astley - Never Gonna Give You Up (Official Music Video)-thumb.jpg
Season 2009/s2009e1025.Rick Astley - Never Gonna Give You Up (Official Music Video).mp4
Season 2009/s2009e1025.Rick Astley - Together Forever (Official Video) [Remastered in 4K]-thumb.jpg
Season 2009/s2009e1025.Rick Astley - Together Forever (Official Video) [Remastered in 4K].webm
Season 2009/s2009e1025.Rick Astley - Whenever You Need Somebody (Official Music Video)-thumb.jpg
Season 2009/s2009e1025.Rick Astley - Whenever You Need Somebody (Official Music Video).webm
Season 2012/s2012e0314.Rick Astley - Giving Up On Love (Official Video)-thumb.jpg
Season 2012/s2012e0314.Rick Astley - Giving Up On Love (Official Video).webm
Season 2012/s2012e0314.Rick Astley - Hopelessly (Official Music Video)-thumb.jpg
Season 2012/s2012e0314.Rick Astley - Hopelessly (Official Music Video).webm
Season 2012/s2012e0314.Rick Astley - She Wants To Dance With Me (Official Music Video)-thumb.jpg
Season 2012/s2012e0314.Rick Astley - She Wants To Dance With Me (Official Music Video).webm
Season 2012/s2012e0314.Rick Astley - Take Me to Your Heart (Official Music Video)-thumb.jpg
Season 2012/s2012e0314.Rick Astley - Take Me to Your Heart (Official Music Video).webm
Season 2013/s2013e0822.Rick Astley - Never Gonna Give You Up (Live) (Top Of The Pops 1987)-thumb.jpg
Season 2013/s2013e0822.Rick Astley - Never Gonna Give You Up (Live) (Top Of The Pops 1987).webm
Season 2015/s2015e0201.Rick Astley - Lights Out (Official Music Video)-thumb.jpg
Season 2015/s2015e0201.Rick Astley - Lights Out (Official Music Video).webm
Season 2016/s2016e0406.Rick Astley - Keep Singing (Official Music Video)-thumb.jpg
Season 2016/s2016e0406.Rick Astley - Keep Singing (Official Music Video).webm
Season 2016/s2016e0609.Rick Astley - Angels On My Side (Official Music Video)-thumb.jpg
Season 2016/s2016e0609.Rick Astley - Angels On My Side (Official Music Video).webm
Season 2016/s2016e0706.Rick Astley - Never Gonna Give You Up (Live) (The Roxy 1987)-thumb.jpg
Season 2016/s2016e0706.Rick Astley - Never Gonna Give You Up (Live) (The Roxy 1987).webm
Season 2016/s2016e0706.Rick Astley - Whenever You Need Somebody (Live) (The Roxy 1987)-thumb.jpg
Season 2016/s2016e0706.Rick Astley - Whenever You Need Somebody (Live) (The Roxy 1987).webm
Season 2016/s2016e0907.Rick Astley - Dance (Official Video)-thumb.jpg
Season 2016/s2016e0907.Rick Astley - Dance (Official Video).webm
Season 2016/s2016e1110.Rick Astley - Pray With Me (Official Music Video)-thumb.jpg
Season 2016/s2016e1110.Rick Astley - Pray With Me (Official Music Video).webm
Season 2017/s2017e0620.Rick Astley - This Old House (Official Music Video)-thumb.jpg
Season 2017/s2017e0620.Rick Astley - This Old House (Official Music Video).webm
Season 2018/s2018e0309.Rick Astley - Walk Like A Panther (Official Music Video)-thumb.jpg
Season 2018/s2018e0309.Rick Astley - Walk Like A Panther (Official Music Video).webm
Season 2018/s2018e0705.Rick Astley - Beautiful Life (Official Music Video)-thumb.jpg
Season 2018/s2018e0705.Rick Astley - Beautiful Life (Official Music Video).webm
Season 2018/s2018e0913.Rick Astley - Try (Official Music Video)-thumb.jpg
Season 2018/s2018e0913.Rick Astley - Try (Official Music Video).webm
Season 2018/s2018e1109.Rick Astley - She Makes Me (Official Music Video)-thumb.jpg
Season 2018/s2018e1109.Rick Astley - She Makes Me (Official Music Video).webm
Season 2019/s2019e0531.Rick Astley - Try (Champions League Tribute Version)-thumb.jpg
Season 2019/s2019e0531.Rick Astley - Try (Champions League Tribute Version).webm
Season 2019/s2019e0606.Rick Astley - Giant (Official Audio)-thumb.jpg
Season 2019/s2019e0606.Rick Astley - Giant (Official Audio).webm
Season 2019/s2019e0619.Rick Astley - Giant (Tour Video)-thumb.jpg
Season 2019/s2019e0619.Rick Astley - Giant (Tour Video).webm
Season 2019/s2019e1030.Rick Astley - Every One of Us (Rehearsal Video)-thumb.jpg
Season 2019/s2019e1030.Rick Astley - Every One of Us (Rehearsal Video).webm
Season 2019/s2019e1119.Rick Astley - It Would Take a Strong Strong Man (Official HD Video)-thumb.jpg
Season 2019/s2019e1119.Rick Astley - It Would Take a Strong Strong Man (Official HD Video).webm
Season 2019/s2019e1121.Rick Astley - Move Right Out (UK Version) [Official HD Video]-thumb.jpg
Season 2019/s2019e1121.Rick Astley - Move Right Out (UK Version) [Official HD Video].webm
Season 2019/s2019e1128.Rick Astley - The Ones You Love (Official HD Video)-thumb.jpg
Season 2019/s2019e1128.Rick Astley - The Ones You Love (Official HD Video).webm
Season 2019/s2019e1212.Rick Astley - Never Gonna Give You Up (Pianoforte) (Performance)-thumb.jpg
Season 2019/s2019e1212.Rick Astley - Never Gonna Give You Up (Pianoforte) (Performance).webm
Season 2020/s2020e1015.Rick Astley ft.The Unsung Heroes - Every One of Us (Heroes Edit) (Official Music Video)-thumb.jpg
Season 2020/s2020e1015.Rick Astley ft.The Unsung Heroes - Every One of Us (Heroes Edit) (Official Music Video).webm
Season 2020/s2020e1023.Rick Astley ft.The Unsung Heroes - Every One of Us (Lyric Video)-thumb.jpg
Season 2020/s2020e1023.Rick Astley ft.The Unsung Heroes - Every One of Us (Lyric Video).webm
Season 2020/s2020e1130.Rick Astley - Love This Christmas (Lyric Video)-thumb.jpg
Season 2020/s2020e1130.Rick Astley - Love This Christmas (Lyric Video).webm
Season 2020/s2020e1210.Rick Astley - Love This Christmas (Official Music Video)-thumb.jpg
Season 2020/s2020e1210.Rick Astley - Love This Christmas (Official Music Video).webm
Season 2021/s2021e0408.Rick Astley - Unwanted (Official Song from the Podcast) (Lyric Video)-thumb.jpg
Season 2021/s2021e0408.Rick Astley - Unwanted (Official Song from the Podcast) (Lyric Video).webm

[ytdl-sub] Downloads for rick_a_channel:
Files created in '/config/first_config/output_videos/Rick Astley'
----------------------------------------
.ytdl-sub-rick_a_channel-download-archive.json
Season 2022/s2022e0308.Rick Astley - abcdefu (GAYLE Cover)-thumb.jpg
Season 2022/s2022e0308.Rick Astley - abcdefu (GAYLE Cover).webm
Season 2022/s2022e0413.Rick Astley – My Arms Keep Missing You (Official Audio)-thumb.jpg
Season 2022/s2022e0413.Rick Astley – My Arms Keep Missing You (Official Audio).webm
Season 2022/s2022e0520.Rick Astley - Never Gonna Give You Up (Official Animated Video)-thumb.jpg
Season 2022/s2022e0520.Rick Astley - Never Gonna Give You Up (Official Animated Video).webm
fanart.jpg
poster.jpg

Looking good, everything is in its appropriate directory.

Understanding Kodi NFOs

NFO files are used to populate the music and video library in Kodi using locally stored information. For every video we download, we need to create an NFO file to represent it as an episode. ytdl-sub offers an NFO plugin to generate NFOs for each entry.

Generating Kodi NFO Files

Episode NFO Files

Let's add the following section to the yt_video preset.

    nfo_tags:
      nfo_name: "{episode_path}.nfo"
      nfo_root: "episodedetails"
      tags:
        title: "{title}"
        season: "{season}"
        episode: "{episode}"
        year: "{upload_year}"
        aired: "{upload_date_standardized}"

This sets both source and override variables to an episode NFO file that Kodi can read. Notice that we use {episode} and not {episode_padded}. This will be the episode number that Kodi ingests internally. We do not want that to be padded and error in case something like 0123 is not a valid number.

TV Show NFO File

We need create one more TV show NFO file in the TV show directory. There is another ytdl-sub plugin called NFO Output Directory that lets us define this. Let's write it directly below the nfo_tags section:

    output_directory_nfo_tags:
      nfo_name: "tvshow.nfo"
      nfo_root: "tvshow"
      tags:
        title: "{tv_show_name}"

Since our output_options.output_directory points to the TV show directory, and all file path fields are relative to it, nfo_name will get written to <TV Show Name>/tvshow.nfo

Testing TV Shows in Kodi

Our config is finally ready transform YouTube videos into Kodi TV shows. Let's take another look at the entire config and do another dry-run to make sure our NFO generation looks good.