diff --git a/README.md b/README.md
index 68d86bf2..28744ebd 100644
--- a/README.md
+++ b/README.md
@@ -1,4 +1,5 @@
# ytdl-sub
+## Automate downloading and metadata generation with YoutubeDL.
[
](https://ytdl-sub.readthedocs.io/en/latest/index.html)
[
](https://discord.gg/v8j9RAHb4k)
[](https://app.codecov.io/gh/jmbannon/ytdl-sub)
@@ -6,8 +7,6 @@
-Automate downloading and adding metadata with youtube-dl.
-
This package downloads media via
[yt-dlp](https://github.com/yt-dlp/yt-dlp)
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)
that we personally use and
[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
+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:
+ # Inherit all fields in the 'yt_channel_as_tv' preset
preset: "yt_channel_as_tv"
+
+ # Add the `channel_url` parameter here since it's unique for each subscription
youtube:
channel_url: "https://youtube.com/channe/UCsvn_Po0SmunchJYtttWpOxMg"
+
+ # Similarly, define the {tv_show_name} variable since it's also unique to each
+ # subscription.
overrides:
tv_show_name: "John Smith Vlogs"
```
-The download can be performed using:
+The download can now be performed using:
```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
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"
```
+#### 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
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
@@ -85,9 +144,13 @@ The ytdl-sub docker image uses
It looks, feels, and operates like other LinuxServer images. This is the
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
```yaml
-version: "2.1"
services:
ytdl-sub:
image: ghcr.io/jmbannon/ytdl-sub:latest