7.6 KiB
ytdl-sub: Youtube-DL-Subscribe
Automate downloading and adding metadata with YoutubeDL.
This package strives to download media via yt-dlp and prepare it for consumption in your favorite media player (Kodi, Jellyfin, Plex, Emby, modern music players) in the most hassle-free way possible. We recognize that everyone stores their media differently. Our approach for file and metadata formatting is to provide maximum flexibility while maintaining simplicity. Read more about it here.
Supported Features
Below lists supported download schemes. You can see our various example configurations we personally use to get an idea on how to use ytdl-sub to your liking.
- Download any and all audio/video from a channel or playlist
- Format videos to look like
- Movies
- TV Shows
- TV Show Seasons
- Music Videos
- Format and tag audio files to look like
- Albums, Singles
- Audiobooks
- Download thumbnails, channel avatars, and banners to set as
- Posters
- Fanart
- Banners
- Album Artwork
- Format videos to look like
- Download a soundcloud artist's albums and singles
- Format the music tags and save any artwork for album covers
- Manually download a single audio/video file
- Reuse configs you have defined to format it as anything you like
- Only download recent audio/video, optionally remove old files
Configuration
Formatting video and audio files are defined by presets. The {variables} used
in the strings are derived from the media itself or defined by you in the overrides
section. Below shows what a config.yaml and subscription.yaml look like to
download a Youtube channel as a TV show with artwork. The files are formatted
to look like:
/path/to/youtube_tv_shows/Your Favorite YT Channel
/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
config.yaml
The config file defines how to download and format media. You can define any number of presets to represent media as whatever you want.
configuration:
working_directory: '.ytdl-sub-downloads'
presets:
yt_channel_as_tv:
youtube:
download_strategy: "channel"
channel_avatar_path: "poster.jpg"
channel_banner_path: "fanart.jpg"
# Pass any ytdl parameter to the downloader. It is recommended to leave
# ignoreerrors=True for things like age-restricted or hidden videos.
ytdl_options:
ignoreerrors: True
output_options:
output_directory: "{youtube_tv_shows_directory}/{sanitized_tv_show_name}"
file_name: "{episode_name}.{ext}"
thumbnail_name: "{episode_name}.jpg"
maintain_download_archive: True
convert_thumbnail:
to: "jpg"
nfo_tags:
nfo_name: "{episode_name}.nfo"
nfo_root: "episodedetails"
tags:
title: "{title}"
season: "{upload_year}"
episode: "{upload_month}{upload_day_padded}"
plot: "{description}"
year: "{upload_year}"
aired: "{upload_date_standardized}"
output_directory_nfo_tags:
nfo_name: "tvshow.nfo"
nfo_root: "tvshow"
tags:
title: "{tv_show_name}"
overrides:
youtube_tv_shows_directory: "/path/to/youtube_tv_shows"
episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {sanitized_title}"
subscription.yaml
The subscription file defines what to download. Anything in the preset can be overwritten by a subscription.
# Downloads the entire channel
john_smith_archive:
preset: "yt_channel_as_tv"
youtube:
channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
# Any user-defined override variables will automatically create a `_sanitized`
# variable name, which is safe to use for file names and paths
overrides:
tv_show_name: "John /\ Smith"
# Downloads and only keeps videos uploaded in the last 2 weeks
john_doe_recent_archive:
preset: "yt_channel_as_tv"
youtube:
channel_id: "UCsvn_Po0SmunchJYtttWpOxMg"
after: "today-2weeks"
overrides:
tv_show_name: "John /\ Smith"
# Will stop looking at channel videos if it already exists or the upload date
# is out of range
ytdl_options:
break_on_existing: True
break_on_reject: True
output_options:
keep_files:
after: "today-2weeks"
Usage
You can have multiple subscription files for better organizing. We can invoke the subscription download using the command below. For cron jobs, this is the recommended command to use.
ytdl-sub sub subscription.yaml
One-time Downloads
There are things we want to download, but not subscribe to. In this case, you
can invoke ytdl-sub dl and add any fields like a subscription. This example is
equivalent to using the subscription yaml above, but without the yaml.
ytdl-sub dl \
--preset "yt_channel_as_tv" \
--youtube.channel_id "UCsvn_Po0SmunchJYtttWpOxMg" \
--overrides.tv_show_name "John /\ Smith"
REST API [not available yet]
The dream will be to create mobile apps or browser extensions to invoke downloads from the couch. Once the server and API is written, the short-term plan is to self-host a swaggerhub io instance and invoke the rest api from the browser. It will be a while before this gets implemented, but when it does, it will look like this.
# spin-up the server
ytdl-sub server
POST request to invoke the same one-time download example via REST.
curl -X POST -H "Content-type: application/json" \
-d '{ \
"youtube.channel_id": "UCsvn_Po0SmunchJYtttWpOxMg" \
"overrides.tv_show_name": "John /\ Smith" \
}' \
'localhost:8080/yt_channel_as_tv'
Installation
Once we are ready for our first release, we will add this package to pypi. Then, we plan to create a docker image that uses the LinuxServer.io base image, and hopefully become a part of their fleet someday.
Until then, you will have to clone this repo and run it using python 3.10
git clone https://github.com/jmbannon/ytdl-sub.git
cd ytdl-sub
pip install -e .
Additional Documentation
We are actively working on documenting all ytdl-sub features within our readthedocs page. It is still a work-in-progress, but you can still find some useful things in there.
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. I try to be responsive and provide constructive PR feedback to maintain excellent code quality ;)