Skip to main content

Automate downloading metadata generation with YoutubeDL

Project description

ytdl-sub

Automate downloading and metadata generation with YoutubeDL.

codecov Code Qaulity Checks License

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

unknown

Jellyfin

jellyfin

Music Videos and Concerts

Kodi

kodi

Jellyfin

jelly_mv

SoundCloud Discography

Writes proper music-tags via beets API

sc_mb

Bandcamp Discography

bc_nav

How it Works

ytdl-sub uses YAML files to define subscriptions. Each subscription imports presets that define how to handle and output media files. ytdl-sub comes packaged with many prebuilt presets that 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 Shows
    tv_show_directory: "/tv_shows"
    
    # Root folder of all ytdl-sub Music
    music_directory: "/music"
    
    # Root folder of all ytdl-sub Music Videos
    music_video_directory: "/music_videos"
    
    # For 'Only Recent' preset, only keep vids within this range and limit
    only_recent_date_range: "2months"
    only_recent_max_files: 30
    
  # Pass any arg directly to yt-dlp's Python API
  ytdl_options:
    cookiefile: "/config/cookie.txt" 

###################################################################
# TV Show Presets. Can replace Plex with Plex/Jellyfin/Kodi

Plex TV Show by Date:

  # Sets genre tag to "Documentaries"
  = Documentaries:
    "NOVA PBS": "https://www.youtube.com/@novapbs"
    "National Geographic": "https://www.youtube.com/@NatGeo"
    "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"

  # Sets genre tag to "Kids", "TV-Y" for content rating
  = Kids | = TV-Y:
    "Jake Trains": "https://www.youtube.com/@JakeTrains"
    "Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel"

  = Music:
    # TV show subscriptions can support multiple urls and store in the same TV Show
    "Rick Beato":
      - "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:
    "BBC News": "https://www.youtube.com/@BBCNews"

Plex TV Show Collection:
  = Music:
    # Prefix with ~ to set specific override variables
    "~Beyond the Guitar":
      s01_name: "Videos"
      s01_url: "https://www.youtube.com/c/BeyondTheGuitar"
      s02_name: "Covers"
      s02_url: "https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W"

###################################################################
# Music Presets. Can replace Plex with Plex/Jellyfin/Kodi

YouTube Releases:
  = Jazz:  # Sets genre tag to "Jazz"
    "Thelonious Monk": "https://www.youtube.com/@theloniousmonk3870/releases"

YouTube Full Albums:
  = Lofi:
    "Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"

SoundCloud Discography:
  = Chill Hop:
    "UKNOWY": "https://soundcloud.com/uknowymunich"
  = Synthwave:
    "Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords"
    "Earmake": "https://soundcloud.com/earmake"

Bandcamp:
  = Lofi:
    "Emily Hopkins": "https://emilyharpist.bandcamp.com/"

###################################################################
# Music Video Presets
"Plex Music Videos":
  = Pop:  # Sets genre tag to "Pop"
    "Rick Astley": "https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"
    "Michael Jackson": "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 command

ytdl-sub sub subscriptions.yaml

See our example subscriptions for more detailed examples and use-cases.

Output

After ytdl-sub runs, 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.mp4

Custom Configs

Any part of this process is modifiable by using custom configs. See our walk-through guide on how to build your first config from scratch. Ready-to-use example configurations can be found here alongside our readthedocs for detailed information on all config fields.

Installation

ytdl-sub can be installed on the following platforms.

Docker Installation

Docker installs can be either headless or use the Web-GUI image, which comprises LSIO's code-server Docker image with ytdl-sub preinstalled. This is the recommended way to use ytdl-sub.

image

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.

Project details


Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ytdl_sub-2024.11.18.tar.gz (191.0 kB view details)

Uploaded Source

Built Distribution

ytdl_sub-2024.11.18-py3-none-any.whl (231.0 kB view details)

Uploaded Python 3

File details

Details for the file ytdl_sub-2024.11.18.tar.gz.

File metadata

  • Download URL: ytdl_sub-2024.11.18.tar.gz
  • Upload date:
  • Size: 191.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for ytdl_sub-2024.11.18.tar.gz
Algorithm Hash digest
SHA256 21599551897bacffd4f5d9c2f240606f17ff4020311e5eeba25fb74943342be6
MD5 2e924740eaf2298fc5b181e230076fc3
BLAKE2b-256 4f73477a410f3ad1765b8575e9c0d91cb6ed4def0e2ea5c46aed70b20e2a223b

See more details on using hashes here.

File details

Details for the file ytdl_sub-2024.11.18-py3-none-any.whl.

File metadata

File hashes

Hashes for ytdl_sub-2024.11.18-py3-none-any.whl
Algorithm Hash digest
SHA256 b58f07011ea414672f6a61611e193da0f77517abc74197aaa667c7ce06484b90
MD5 9973c84504ebd1ecbf994d0f193b4028
BLAKE2b-256 d16c33f7e4a2ab050460f60dfd2c514a6a5fe502c3f65e5cc4b1d85c4035a07b

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page