102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# ytdl-sub: Youtube-DL-Subscribe
|
|
[<img src="https://img.shields.io/badge/readthedocs-link-blue?logo=readthedocs">](https://ytdl-sub.readthedocs.io/en/latest/index.html)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Automate downloading and adding metadata with YoutubeDL.
|
|
|
|
This package downloads media via
|
|
[yt-dlp](https://github.com/yt-dlp/yt-dlp)
|
|
and prepares it for your favorite media player
|
|
([Kodi](https://github.com/xbmc/xbmc),
|
|
[Jellyfin](https://github.com/jellyfin/jellyfin),
|
|
[Plex](https://github.com/plexinc/pms-docker),
|
|
[Emby](https://github.com/plexinc/pms-docker),
|
|
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](https://github.com/jmbannon/ytdl-sub/tree/master/examples)
|
|
that we personally use and
|
|
[readthedocs](https://ytdl-sub.readthedocs.io/en/latest/config.html#)
|
|
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:
|
|
```yaml
|
|
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:
|
|
```shell
|
|
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:
|
|
```shell
|
|
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
|
|
```commandline
|
|
git clone https://github.com/jmbannon/ytdl-sub.git
|
|
cd ytdl-sub
|
|
|
|
pip install -e .
|
|
```
|
|
|
|
### Local Docker
|
|
If you are familiar with
|
|
[LinuxServer.io](https://www.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](https://github.com/jmbannon/ytdl-sub/tree/master/docker#running-ytdl-sub-in-docker).
|
|
|
|
|
|
## Contributing
|
|
There are many ways to contribute, even without coding. Please take a look in
|
|
our [Github Issues](https://github.com/jmbannon/ytdl-sub/issues) to ask
|
|
questions, submit a feature request, or pick up a bug.
|