ff66ff5be0
* docs(docker): Recommended image DEFAULT_WORKSPACE * fix(docker): Add default crontab download command Clarify the `/config/ytdl-sub-configs/cron` script with explanatory comments and a default `--dry-run` command. Also change the wrapper script to echo commands for easier debugging. To update an existing script, move the old script aside, restart the container to regenerate it, and edit the new script. Also clarify the Automating page in the Getting Started guide docs. * fix(docker): Unintentional unattended dry runs [PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2315215600) prompted me to reconsider having a default command at all. We should assume, unfortunately, that many new users will just skim the docs enough to enable the image's cron integration but not actually incrementally test their configuration. In those cases, they'd end up sending dry-run non-download requests for all their subscriptions every 6 hours for no good reason. There's just no way to provide a default command that isn't also providing a footgun. * docs(docker): More open cron schedule generator From [PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2320521024), this seems like less of an ad than the previous and the source for the page is itself open source. * docs(docker): Document image environment footgun From [PR feedback](https://github.com/jmbannon/ytdl-sub/pull/1321#discussion_r2320515419). * docs(automate): Avoid external link 404 responses * docs(automate): False simultaneous run warning * docs(automate): Clarify Docker daemon restarts * docs(automate): Revert run start non-recommended * docs(automate): Remove footgun manual run command Addressing this underlying issue requires more thought and should be a separate PR. * docs(automate): Restore env var footgun in example
228 lines
9.1 KiB
Markdown
228 lines
9.1 KiB
Markdown
# ytdl-sub
|
|
## Automate downloading and metadata generation with YoutubeDL.
|
|
[<img src="https://img.shields.io/badge/readthedocs-link-blue?logo=readthedocs">](https://ytdl-sub.readthedocs.io/en/latest/index.html)
|
|
[<img src="https://img.shields.io/discord/994270357957648404?logo=Discord">](https://discord.gg/v8j9RAHb4k)
|
|
[](https://app.codecov.io/gh/jmbannon/ytdl-sub)
|
|
|
|
|
|
|
|
|
|
`ytdl-sub` is a command-line tool that downloads media via
|
|
[yt-dlp](https://github.com/yt-dlp/yt-dlp)
|
|
and prepares it for your favorite media player, including
|
|
[Kodi](https://github.com/xbmc/xbmc),
|
|
[Jellyfin](https://github.com/jellyfin/jellyfin),
|
|
[Plex](https://github.com/plexinc/pms-docker),
|
|
[Emby](https://emby.media/),
|
|
and modern music players. No additional plugins or external scrapers are needed.
|
|
|
|
We recognize that everyone stores their
|
|
media differently. Our approach for file and metadata formatting is to provide
|
|
maximum flexibility while maintaining simplicity.
|
|
|
|
### YouTube Channels as TV Shows
|
|
#### Plex
|
|
|
|
|
|
#### Jellyfin
|
|
|
|
|
|
### Music Videos and Concerts
|
|
#### Kodi
|
|
|
|
#### Jellyfin
|
|
|
|
|
|
### SoundCloud Discography
|
|
#### Writes proper music-tags via beets API
|
|
|
|
|
|
### Bandcamp Discography
|
|
|
|
|
|
## How it Works
|
|
`ytdl-sub` uses YAML files to define subscriptions. Each subscription imports _presets_ that
|
|
define how to handle and output media files. `ytdl-sub` comes packaged with many _prebuilt presets_
|
|
that do the work of config-building, so you can start downloading immediately.
|
|
|
|
```yaml
|
|
# subscriptions.yaml:
|
|
# Everything in here can be downloaded using the command:
|
|
# ytdl-sub sub subscriptions.yaml
|
|
|
|
# __preset__ is a place to define global overrides for all subscriptions
|
|
__preset__:
|
|
overrides:
|
|
# Root folder of all ytdl-sub TV Shows
|
|
tv_show_directory: "/tv_shows"
|
|
|
|
# Root folder of all ytdl-sub Music
|
|
music_directory: "/music"
|
|
|
|
# Root folder of all ytdl-sub Music Videos
|
|
music_video_directory: "/music_videos"
|
|
|
|
# For 'Only Recent' preset, only keep vids within this range and limit
|
|
only_recent_date_range: "2months"
|
|
only_recent_max_files: 30
|
|
|
|
# Pass any arg directly to yt-dlp's Python API
|
|
ytdl_options:
|
|
cookiefile: "/config/ytdl-sub-configs/cookie.txt"
|
|
|
|
###################################################################
|
|
# TV Show Presets. Can replace Plex with Plex/Jellyfin/Emby/Kodi
|
|
|
|
Plex TV Show by Date:
|
|
|
|
# Sets genre tag to "Documentaries"
|
|
= Documentaries:
|
|
"NOVA PBS": "https://www.youtube.com/@novapbs"
|
|
"National Geographic": "https://www.youtube.com/@NatGeo"
|
|
"Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
|
|
|
|
# Sets genre tag to "Kids", "TV-Y" for content rating
|
|
= Kids | = TV-Y:
|
|
"Jake Trains": "https://www.youtube.com/@JakeTrains"
|
|
"Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel"
|
|
|
|
= Music:
|
|
# TV show subscriptions can support multiple urls and store in the same TV Show
|
|
"Rick Beato":
|
|
- "https://www.youtube.com/@RickBeato"
|
|
- "https://www.youtube.com/@rickbeato240"
|
|
|
|
# Set genre tag to "News", use `Only Recent` preset to only store videos uploaded recently
|
|
= News | Only Recent:
|
|
"BBC News": "https://www.youtube.com/@BBCNews"
|
|
|
|
Plex TV Show Collection:
|
|
= Music:
|
|
# Prefix with ~ to set specific override variables
|
|
"~Beyond the Guitar":
|
|
s01_name: "Videos"
|
|
s01_url: "https://www.youtube.com/c/BeyondTheGuitar"
|
|
s02_name: "Covers"
|
|
s02_url: "https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W"
|
|
|
|
###################################################################
|
|
# Music Presets.
|
|
|
|
YouTube Releases:
|
|
= Jazz: # Sets genre tag to "Jazz"
|
|
"Thelonious Monk": "https://www.youtube.com/@theloniousmonk3870/releases"
|
|
|
|
YouTube Full Albums:
|
|
= Lofi:
|
|
"Game Chops": "https://www.youtube.com/playlist?list=PLBsm_SagFMmdWnCnrNtLjA9kzfrRkto4i"
|
|
|
|
SoundCloud Discography:
|
|
= Chill Hop:
|
|
"UKNOWY": "https://soundcloud.com/uknowymunich"
|
|
= Synthwave:
|
|
"Lazerdiscs Records": "https://soundcloud.com/lazerdiscsrecords"
|
|
"Earmake": "https://soundcloud.com/earmake"
|
|
|
|
Bandcamp:
|
|
= Lofi:
|
|
"Emily Hopkins": "https://emilyharpist.bandcamp.com/"
|
|
|
|
###################################################################
|
|
# Music Video Presets. Can replace Plex with Plex/Jellyfin/Kodi
|
|
"Plex Music Videos":
|
|
= Pop: # Sets genre tag to "Pop"
|
|
"Rick Astley": "https://www.youtube.com/playlist?list=PLlaN88a7y2_plecYoJxvRFTLHVbIVAOoc"
|
|
"Michael Jackson": "https://www.youtube.com/playlist?list=OLAK5uy_mnY03zP6abNWH929q2XhGzWD_2uKJ_n8E"
|
|
```
|
|
|
|
All of this can be downloaded and ready to import to your favorite player
|
|
using the command
|
|
```commandline
|
|
ytdl-sub sub subscriptions.yaml
|
|
```
|
|
See our
|
|
[example subscriptions](https://github.com/jmbannon/ytdl-sub/tree/master/examples)
|
|
for more detailed examples and use-cases.
|
|
|
|
### Output
|
|
After `ytdl-sub` runs, the end result will download and format the files into something ready
|
|
to be consumed by your favorite media player/server.
|
|
```
|
|
tv_shows/
|
|
Jake Trains/
|
|
Season 2021/
|
|
s2021.e031701 - Pattys Day Video-thumb.jpg
|
|
s2021.e031701 - Pattys Day Video.mp4
|
|
s2021.e031701 - Pattys Day Video.nfo
|
|
s2021.e031702 - Second Pattys Day Video-thumb.jpg
|
|
s2021.e031702 - Second Pattys Day Video.mp4
|
|
s2021.e031702 - Second Pattys Day Video.nfo
|
|
Season 2022/
|
|
s2022.e122501 - Merry Christmas-thumb.jpg
|
|
s2022.e122501 - Merry Christmas.mp4
|
|
s2022.e122501 - Merry Christmas.nfo
|
|
poster.jpg
|
|
fanart.jpg
|
|
tvshow.nfo
|
|
|
|
music/
|
|
Artist/
|
|
[2022] Some Single/
|
|
01 - Some Single.mp3
|
|
folder.jpg
|
|
[2023] Latest Album/
|
|
01 - Track Title.mp3
|
|
02 - Another Track.mp3
|
|
folder.jpg
|
|
|
|
music_videos/
|
|
Elton John/
|
|
Elton John - Rocketman.jpg
|
|
Elton John - Rocketman.mp4
|
|
```
|
|
|
|
## Custom Configs
|
|
Any part of this process is modifiable by using custom configs. See our
|
|
[walk-through guide](https://ytdl-sub.readthedocs.io/en/latest/guides/index.html)
|
|
on how to build your first config from scratch. Ready-to-use
|
|
[example configurations](https://github.com/jmbannon/ytdl-sub/tree/master/examples)
|
|
can be found here alongside our
|
|
[readthedocs](https://ytdl-sub.readthedocs.io/en/latest/index.html)
|
|
for detailed information on all config fields.
|
|
|
|
## Installation
|
|
`ytdl-sub` can be installed on the following platforms.
|
|
|
|
- [Docker Compose](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#install-with-docker-compose)
|
|
- [Web-GUI](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#install-with-docker-compose)
|
|
- [Headless](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#install-with-docker-compose)
|
|
- [CPU / GPU Passthrough](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#device-passthrough)
|
|
- [Docker CLI](https://ytdl-sub.readthedocs.io/en/latest/guides/install/docker.html#docker-cli)
|
|
- [Windows](https://ytdl-sub.readthedocs.io/en/latest/guides/install/windows.html)
|
|
- [Unraid](https://ytdl-sub.readthedocs.io/en/latest/guides/install/unraid.html)
|
|
- [Linux](https://ytdl-sub.readthedocs.io/en/latest/guides/install/linux.html)
|
|
- [Linux ARM](https://ytdl-sub.readthedocs.io/en/latest/guides/install/linux.html)
|
|
- [PIP](https://ytdl-sub.readthedocs.io/en/latest/guides/install/agnostic.html#pip-install)
|
|
- [Local Install](https://ytdl-sub.readthedocs.io/en/latest/guides/install/agnostic.html#local-install)
|
|
- [Local Docker Build](https://ytdl-sub.readthedocs.io/en/latest/guides/install/agnostic.html#local-docker-build)
|
|
|
|
### Docker Installation
|
|
Docker installs can be either headless or use the Web-GUI image, which comprises
|
|
[LSIO's](https://www.linuxserver.io/)
|
|
[code-server](https://hub.docker.com/r/linuxserver/code-server)
|
|
Docker image with `ytdl-sub` preinstalled. This is the recommended way to use ``ytdl-sub``.
|
|
|
|
|
|
|
|
|
|
## 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 submit a feature request, or
|
|
pick up a bug.
|
|
|
|
## Support
|
|
We are pretty active in our
|
|
[Discord channel](https://discord.gg/v8j9RAHb4k)
|
|
if you have any questions. Also see our
|
|
[FAQ](https://ytdl-sub.readthedocs.io/en/latest/faq/index.html)
|
|
for commonly asked questions.
|