Package: ytdl-sub
ytdl-subAutomate downloading and metadata generation with YoutubeDL.ytdl-subis a command-line tool that downloads media viayt-dlpand prepares it for your favorite media player, includingKodi,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 ShowsPlexJellyfinMusic Videos and ConcertsKodiJellyfinSoundCloud DiscographyWrites proper music-tags via beets APIBandcamp DiscographyHow it Worksytdl-subuses YAML files to define subscriptions. Each subscription importspresetsthat
define how to handle and output media files.ytdl-subcomes packaged with manyprebuilt presetsthat do the work of config-building, so you can start downloading immediately.# subscriptions.yaml:# Everything in here can be downloaded using the command:#   ytdl-sub sub subscriptions.yaml# __preset__ is a place to define global overrides for all subscriptions__preset__:overrides:# Root folder of all ytdl-sub TV Showstv_show_directory:"/tv_shows"# Root folder of all ytdl-sub Musicmusic_directory:"/music"# Root folder of all ytdl-sub Music Videosmusic_video_directory:"/music_videos"# For 'Only Recent' preset, only keep vids within this range and limitonly_recent_date_range:"2months"only_recent_max_files:30# Pass any arg directly to yt-dlp's Python APIytdl_options:cookiefile:"/config/cookie.txt"#################################################################### Subscriptions nested under this will use the# `Plex TV Show by Date` preset.## Can choose between:#   - Plex TV Show by Date:#   - Jellyfin TV Show by Date:#   - Kodi TV Show by Date:Plex TV Show by Date:# Sets genre tag to "Documentaries"= Documentaries:"NOVAPBS":"https://www.youtube.com/@novapbs""NationalGeographic":"https://www.youtube.com/@NatGeo""Cosmos-WhatIf":"https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"# Sets genre tag to "Kids", "TV-Y" for content rating= Kids | = TV-Y:"JakeTrains":"https://www.youtube.com/@JakeTrains""KidsToysPlay":"https://www.youtube.com/@KidsToysPlayChannel"= Music:# TV show subscriptions can support multiple urls and store in the same TV Show"RickBeato":-"https://www.youtube.com/@RickBeato"-"https://www.youtube.com/@rickbeato240"# Set genre tag to "News", use `Only Recent` preset to only store videos uploaded recently= News | Only Recent:"BBCNews":"https://www.youtube.com/@BBCNews"#################################################################### Subscriptions nested under these will use the various prebuilt# music presetsYouTube Releases:= Jazz:# Sets genre tag to "Jazz""TheloniousMonk":"https://www.youtube.com/@theloniousmonk3870/releases"YouTube Full Albums:= Lofi:"GameChops":"https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"SoundCloud Discography:= Chill Hop:"UKNOWY":"https://soundcloud.com/uknowymunich"= Synthwave:"LazerdiscsRecords":"https://soundcloud.com/lazerdiscsrecords""Earmake":"https://soundcloud.com/earmake"Bandcamp:= Lofi:"EmilyHopkins":"https://emilyharpist.bandcamp.com/"#################################################################### Can choose between:#   - Plex Music Videos:#   - Jellyfin Music Videos:#   - Kodi Music Videos:"PlexMusicVideos":= Pop:# Sets genre tag to "Pop""RickAstley":"https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc""MichaelJackson":"https://www.youtube.com/playlist?list=OLAK5uy_mnY03zP6abNWH929q2XhGzWD_2uKJ_n8E"All of this can be downloaded and ready to import to your favorite player
using the commandytdl-sub sub subscriptions.yamlSee ourexample subscriptionsfor more detailed examples and use-cases.OutputAfterytdl-subruns, the end result will download and format the files into something ready
to be consumed by your favorite media player/server.tv_shows/
  Jake Trains/
    Season 2021/
      s2021.e031701 - Pattys Day Video-thumb.jpg
      s2021.e031701 - Pattys Day Video.mp4
      s2021.e031701 - Pattys Day Video.nfo
      s2021.e031702 - Second Pattys Day Video-thumb.jpg
      s2021.e031702 - Second Pattys Day Video.mp4
      s2021.e031702 - Second Pattys Day Video.nfo
    Season 2022/
      s2022.e122501 - Merry Christmas-thumb.jpg
      s2022.e122501 - Merry Christmas.mp4
      s2022.e122501 - Merry Christmas.nfo
    poster.jpg
    fanart.jpg
    tvshow.nfo

music/
  Artist/
    [2022] Some Single/
      01 - Some Single.mp3
      folder.jpg
    [2023] Latest Album/
      01 - Track Title.mp3
      02 - Another Track.mp3
      folder.jpg

music_videos/
  Elton John/
    Elton John - Rocketman.jpg
    Elton John - Rocketman.mp4Custom ConfigsAny part of this process is modifiable by using custom configs. See ourwalk-through guideon how to build your first config from scratch. Ready-to-useexample configurationscan be found here alongside ourreadthedocsfor detailed information on all config fields.Installationytdl-subcan be installed on the following platforms.Docker ComposeWeb-GUIHeadlessCPU / GPU PassthroughDocker CLIWindowsUnraidLinuxLinux ARMPIPLocal InstallLocal Docker BuildDocker InstallationDocker installs can be either headless or use the Web-GUI image, which comprisesLSIO'scode-serverDocker image withytdl-subpreinstalled. This is the recommended way to useytdl-sub.ContributingThere are many ways to contribute, even without coding. Please take a look in
ourGitHub Issuesto submit a feature request, or
pick up a bug.SupportWe are pretty active in ourDiscord channelif you have any questions. Also see ourFAQfor commonly asked questions.