ytdl-sub/README.md

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_url: "https://youtube.com/channe/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_url "https://youtube.com/channel/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

The ytdl-sub docker image uses LinuxServer's base alpine image. It looks, feels, and operates like other LinuxServer images. This is the recommended way to use ytdl-sub.

Docker Compose

version: "2.1"
services:
  ytdl-sub:
    image: ghcr.io/jmbannon/ytdl-sub:latest
    container_name: ytdl-sub
    environment:
      - PUID=1000
      - PGID=1000
      - TZ=America/Los_Angeles
    volumes:
      - <path/to/ytdl-sub/config>:/config
      - <path/to/tv_shows>:/tv_shows # optional
      - <path/to/movies>:/movies # optional
      - <path/to/music_videos>:/music_videos # optional
      - <path/to/music>:/music # optional
    restart: unless-stopped

Docker CLI

docker run -d \
    --name=ytdl-sub \
    -e PUID=1000 \
    -e PGID=1000 \
    -e TZ=America/Los_Angeles \
    -v <path/to/ytdl-sub/config>:/config \
    -v <OPTIONAL/path/to/tv_shows>:/tv_shows \
    -v <OPTIONAL/path/to/movies>:/movies \
    -v <OPTIONAL/path/to/music_videos>:/music_videos \
    -v <OPTIONAL/path/to/music>:/music \
    --restart unless-stopped \
    ghcr.io/jmbannon/ytdl-sub:latest

Building Docker Image Locally

Run make docker in the root directory of this repo to build the image. This will build the python wheel and install it in the Dockerfile.

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 .

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.