[DOCS] Add a config.yaml example and more info in the README (#124)

* add config in readme

* subtitle

* download aliases

* automated bit

* better subtitle
This commit is contained in:
Jesse Bannon 2022-07-22 22:46:33 -07:00 committed by GitHub
parent bd5b2e76d8
commit 3d46909b4a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -1,4 +1,5 @@
# ytdl-sub # 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/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) [<img src="https://img.shields.io/discord/994270357957648404?logo=Discord">](https://discord.gg/v8j9RAHb4k)
[![codecov](https://img.shields.io/codecov/c/github/jmbannon/ytdl-sub)](https://app.codecov.io/gh/jmbannon/ytdl-sub) [![codecov](https://img.shields.io/codecov/c/github/jmbannon/ytdl-sub)](https://app.codecov.io/gh/jmbannon/ytdl-sub)
@ -6,8 +7,6 @@
![Checks](https://img.shields.io/github/checks-status/jmbannon/ytdl-sub/master) ![Checks](https://img.shields.io/github/checks-status/jmbannon/ytdl-sub/master)
![License](https://img.shields.io/github/license/jmbannon/ytdl-sub?color=blue) ![License](https://img.shields.io/github/license/jmbannon/ytdl-sub?color=blue)
Automate downloading and adding metadata with youtube-dl.
This package downloads media via This package downloads media via
[yt-dlp](https://github.com/yt-dlp/yt-dlp) [yt-dlp](https://github.com/yt-dlp/yt-dlp)
and prepares it for your favorite media player and prepares it for your favorite media player
@ -27,25 +26,68 @@ after it is downloaded. See our
[example configurations](https://github.com/jmbannon/ytdl-sub/tree/master/examples) [example configurations](https://github.com/jmbannon/ytdl-sub/tree/master/examples)
that we personally use and that we personally use and
[readthedocs](https://ytdl-sub.readthedocs.io/en/latest/config.html#) [readthedocs](https://ytdl-sub.readthedocs.io/en/latest/config.html#)
for detailed information on specific sections or fields. for detailed information on specific sections or fields. Downloading looks like this.
Once configured, you can begin downloading using two different methods. ### Config
The `config.yaml` defines how our downloads will look. For this example, let's
download YouTube channels to look like TV shows, and generate `.nfo` files
so they appear in Kodi/Jellyfin/Emby.
### 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 ```yaml
presets:
# Each 'preset' defines a source, download strategy, and options for
# configuring the download. We will name this preset 'yt_channel_as_tv'
yt_channel_as_tv:
# Use YouTube as our source. Our strategy is download the entire channel.
# Configure channel-specific parameters to make images appear as artwork
youtube:
download_strategy: "channel"
channel_avatar_path: "poster.jpg"
channel_banner_path: "fanart.jpg"
# Define media file output options using variables
output_options:
output_directory: "{youtube_tv_shows_directory}/{tv_show_name_sanitized}"
file_name: "{episode_name}.{ext}"
thumbnail_name: "{episode_name}-thumb.jpg"
# Define 'override' variables, which can contain a mix of hardcoded strings
# and 'source' variables that are derived from the video itself.
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} - {title_sanitized}"
# Use the 'nfo_tags' plugin to generate an NFO file for each video.
# See the config in the `examples/` directory for a full example
nfo_tags:
...
```
### Subscriptions
The `subscriptions.yaml` file is where we define content to download using
presets in the `config.yaml`.
```yaml
# The name of our subscription
john_smith_channel: john_smith_channel:
# Inherit all fields in the 'yt_channel_as_tv' preset
preset: "yt_channel_as_tv" preset: "yt_channel_as_tv"
# Add the `channel_url` parameter here since it's unique for each subscription
youtube: youtube:
channel_url: "https://youtube.com/channe/UCsvn_Po0SmunchJYtttWpOxMg" channel_url: "https://youtube.com/channe/UCsvn_Po0SmunchJYtttWpOxMg"
# Similarly, define the {tv_show_name} variable since it's also unique to each
# subscription.
overrides: overrides:
tv_show_name: "John Smith Vlogs" tv_show_name: "John Smith Vlogs"
``` ```
The download can be performed using: The download can now be performed using:
```shell ```shell
ytdl-sub sub subscription.yaml ytdl-sub sub subscriptions.yaml
``` ```
This method makes it easy to pull new videos from channels or playlists, or
experiment with new configurations.
### One-time Download ### One-time Download
There are things we will only want to download once and never again. Anything There are things we will only want to download once and never again. Anything
@ -58,6 +100,23 @@ ytdl-sub dl \
--overrides.tv_show_name "John Smith Vlogs" --overrides.tv_show_name "John Smith Vlogs"
``` ```
#### Download Aliases
In the `config.yaml`, we can define alias to make `dl` commands shorter.
```yaml
configuration:
dl_aliases:
tv: "--preset yt_channel_as_tv"
channel: "--youtube.channel_url"
name: "--overrides.tv_show_name"
```
The above command can now be shortened to
```shell
ytdl-sub dl \
--tv \
--channel "https://youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg" \
--name "John Smith Vlogs"
```
### Output ### Output
After `ytdl-sub` runs, the end result will download and format the channel After `ytdl-sub` runs, the end result will download and format the channel
files into something ready to be consumed by your favorite media player or files into something ready to be consumed by your favorite media player or
@ -85,9 +144,13 @@ The ytdl-sub docker image uses
It looks, feels, and operates like other LinuxServer images. This is the It looks, feels, and operates like other LinuxServer images. This is the
recommended way to use ytdl-sub. recommended way to use ytdl-sub.
ytdl-sub is a command-line tool. The docker image is intended to be used
as a console. For automating `subscriptions.yaml` downloads to pull new media, see
[this guide](https://ytdl-sub.readthedocs.io/en/latest/getting_started.html#setting-up-automated-downloads)
on how set up a cron job in the docker container.
### Docker Compose ### Docker Compose
```yaml ```yaml
version: "2.1"
services: services:
ytdl-sub: ytdl-sub:
image: ghcr.io/jmbannon/ytdl-sub:latest image: ghcr.io/jmbannon/ytdl-sub:latest