a79fcaa25b
* youtube video url * WIP, channel /user/ and /c/ should be valid * unit tests passing * soundcloud artist url * soundcloud username * break configs with name change * Update all yamls with urls * update all docs * more negative url tests
139 lines
4.6 KiB
Markdown
139 lines
4.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_url: "https://youtube.com/channe/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_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](https://www.linuxserver.io/)
|
|
[base alpine image](https://github.com/linuxserver/docker-baseimage-alpine).
|
|
It looks, feels, and operates like other LinuxServer images. This is the
|
|
recommended way to use ytdl-sub.
|
|
|
|
### Docker Compose
|
|
```yaml
|
|
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
|
|
```commandline
|
|
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
|
|
```commandline
|
|
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](https://github.com/jmbannon/ytdl-sub/issues) to ask
|
|
questions, submit a feature request, or pick up a bug.
|