ytdl-sub: Youtube-DL-Subscribe

Automate downloading and adding metadata with YoutubeDL.

This package downloads media via yt-dlp and prepares it for your favorite media player (Kodi, Jellyfin, Plex, Emby, modern music players).

We recognize that everyone stores their media differently. Our approach for file and metadata formatting is to provide maximum flexibility while maintaining simplicity.

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 example configurations that we personally use and readthedocs for detailed information on specific sections or fields.

Once configured, you can begin downloading using two different methods.

Subscription

You can define a subscriptions.yaml for things to recurrently download, like a YouTube channel to pull new videos. It looks something like:

john_smith_channel:
  preset: "yt_channel_as_tv"
  youtube:
    channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
  overrides:
    tv_show_name: "John Smith Vlogs"

The download can be performed using:

ytdl-sub sub subscription.yaml

One-time Download

There are things we will only want to download once and never again, like a one-hit wonder music video. 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 "yt_channel_as_tv"                         \
    --youtube.channel_id "UCsvn_Po0SmunchJYtttWpOxMg"   \
    --overrides.tv_show_name "John Smith Vlogs"

After ytdl-sub runs, the end result would download and format the channel files into something ready to be consumed by your favorite media player or server:

/path/to/youtube_tv_shows/John Smith Vlogs
  /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

Installation

Virtualenv

With a Python 3.10 virtual environment, you can clone and install the repo using

git clone https://github.com/jmbannon/ytdl-sub.git
cd ytdl-sub

pip install -e .

Local Docker

If you are familiar with LinuxServer.io, you will be happy to hear that we use their base image for our docker image. Documentation on how to build the image locally can be found in the docker readme.

Contributing

There are many ways to contribute, even without coding. Please take a look in our Github Issues to ask questions, submit a feature request, or pick up a bug.