danvics/ytdl-sub
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

[DOCS] Update README with prebuilt preset example (#308)

Browse source
This commit is contained in:
Jesse Bannon 2022-11-02 08:57:34 -07:00 committed by GitHub
parent 032acdbb6e
commit 6280ea562a
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 132 additions and 57 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

181
README.md
View file

@ -35,74 +35,131 @@ maximum flexibility while maintaining simplicity.
## How it Works ## How it Works
`ytdl-sub` uses YAML configs to define a layout for how you want media to look `ytdl-sub` uses YAML configs to define a layout for how you want media to look
after it is downloaded. See the after it is downloaded. See our
[walk-through in our wiki](https://github.com/jmbannon/ytdl-sub/wiki) [walk-through guide](https://github.com/jmbannon/ytdl-sub/wiki)
to learn how `ytdl-sub` works, our on how to get started. Ready-to-use
[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 can be found here alongside our
[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. Downloading looks like this. for detailed information on config fields.
### Config ### Config
The `config.yaml` defines how our downloads will look. For this example, let's The `config.yaml` defines how our downloads will look. For this example, let us
download YouTube channels to look like TV shows, and generate `.nfo` files download YouTube channels and generate metadata to look like TV shows using
so they appear in Kodi/Jellyfin/Emby. ytdl-sub's prebuilt presets. No additional plugins or programs are needed for
Kodi, Jellyfin, Plex, or Emby to recognize your downloads. This can also be
used to download any yt-dlp supported URL, including YouTube playlists, Bitchute channels, etc.
```yaml ```yaml
# Set the working directory which will be used to stage downloads
# before placing them in your desired output directory.
configuration:
working_directory: '.ytdl-sub-downloads'
# Presets are where you create 'sub-configs' that can can be
# merged together to dictate what is downloaded, how to format it,
# and what metadata to generate.
presets: 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. # Let us create a preset called `only_recent_videos` that will
# Configure channel-specific parameters to make images appear as artwork # only download recent videos in the last 2 months.
youtube: only_recent_videos:
download_strategy: "channel"
channel_avatar_path: "poster.jpg"
channel_banner_path: "fanart.jpg"
# Define media file output options using variables # Use the `date_range` plugin to specify ytdl-sub to only
# download videos after today MINUS {download_range}, which
# is an override variable that we can alter per channel.
date_range:
after: "today-{download_range}"
# Any yt-dlp argument can be passed via ytdl-sub. Let us set
# yt-dlp's `break_on_reject` to True to stop downloading after
# any video is rejected. Videos will be rejected if they are
# uploaded after our {download_range}.
ytdl_options:
break_on_reject: True
# Deletes any videos uploaded after {download_range}.
output_options: output_options:
output_directory: "{youtube_tv_shows_directory}/{tv_show_name_sanitized}" keep_files_after: "today-{download_range}"
file_name: "{episode_name}.{ext}"
thumbnail_name: "{episode_name}-thumb.jpg"
# Define 'override' variables, which can contain a mix of hardcoded strings # Set the override variable {download_range} to 2months.
# and 'source' variables that are derived from the video itself. # This will serve as our default value. We can override
# this per channel or in a child preset.
overrides: overrides:
youtube_tv_shows_directory: "/path/to/youtube_tv_shows" download_range: "2months"
episode_name: "Season {upload_year}/s{upload_year}.e{upload_month_padded}{upload_day_padded} - {title_sanitized}"
####################################################################
# Now let us create a preset that downloads videos and formats
# as TV shows.
tv_show:
# Presets can inherit all attributes from other presets. Our
# `tv_show` preset will inherit these presets built into ytdl-sub.
preset:
# Let us specify all the TV show by date presets to support all
# players. You only need to specify one, but this ensures
# compatibility with all players.
- "kodi_tv_show_by_date"
- "jellyfin_tv_show_by_date"
- "plex_tv_show_by_date"
# Now we choose a preset that defines how our seasons and
# episode numbers look.
- "season_by_year__episode_by_month_day"
# Set override variables that will be applicable to all downloads
# in main presets.
overrides:
tv_show_directory: "/tv_shows" # Replace with desired directory
# 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 ### Subscriptions
The `subscriptions.yaml` file is where we define content to download using The `subscriptions.yaml` file is where we define content to download using
presets in the `config.yaml`. presets in the `config.yaml`. Each subscription can overwrite any field used
in a preset.
```yaml ```yaml
# The name of our subscription # The name of our subscription. Let us create one to download
john_smith_channel: # ALL of Rick A's videos
# Inherit all fields in the 'yt_channel_as_tv' preset rick_a:
preset: "yt_channel_as_tv" # Inherit our `tv_show` preset we made above
preset:
- "tv_show"
# Add the `channel_url` parameter here since it's unique for each subscription # Set override variables to set the channel URL and the
youtube: # name we want to give the TV show.
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: "Rick A"
url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
# Let us make another subscription that will only download Rick A's
# video's in the last 2 weeks.
rick_a_recent:
# Inherit our `tv_show` AND `only_recent_videos` preset
# Bottom-most presets take precedence.
preset:
- "tv_show"
- "only_recent_videos"
# Set override variables for this subscription. Modify the
# `download_range` to only download and keep 2 weeks' worth
# of videos.
overrides:
tv_show_name: "Rick A"
url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
download_range: "2weeks"
``` ```
The download can now be performed using: The download can now be performed using:
```shell ```shell
ytdl-sub sub subscriptions.yaml ytdl-sub sub subscriptions.yaml
``` ```
This method makes it easy to pull new videos from channels or playlists, or To preview what your output files before doing any downloads, you can dry run using:
experiment with new configurations. ```shell
ytdl-sub --dry-run sub subscriptions.yaml
```
### 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
@ -110,34 +167,35 @@ you can define in a subscription can be defined using CLI arguments. This
example is equivalent to the subscription example above: example is equivalent to the subscription example above:
```shell ```shell
ytdl-sub dl \ ytdl-sub dl \
--preset "yt_channel_as_tv" \ --preset "tv_show" \
--youtube.channel_url "https://youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg" \ --overrides.tv_show_name "Rick A" \
--overrides.tv_show_name "John Smith Vlogs" --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
``` ```
#### Download Aliases #### Download Aliases
In the `config.yaml`, we can define alias to make `dl` commands shorter. In the `config.yaml`, we can define aliases to make `dl` commands shorter.
```yaml ```yaml
configuration: configuration:
dl_aliases: dl_aliases:
tv: "--preset yt_channel_as_tv" tv: "--preset tv_show"
channel: "--youtube.channel_url"
name: "--overrides.tv_show_name" name: "--overrides.tv_show_name"
url: "--overrides.url"
``` ```
The above command can now be shortened to The above command can now be shortened to
```shell ```shell
ytdl-sub dl \ ytdl-sub dl \
--tv \ --tv \
--channel "https://youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg" \ --name "Rick A" \
--name "John Smith Vlogs" --url "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
``` ```
### 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
server. The `--dry-run` flag can be used to view file output before any downloading occurs. server.
``` ```
/path/to/youtube_tv_shows/John Smith Vlogs /path/to/tv_shows/Rick Aß
/Season 2021 /Season 2021
s2021.e0317 - Pattys Day Video-thumb.jpg s2021.e0317 - Pattys Day Video-thumb.jpg
s2021.e0317 - Pattys Day Video.mp4 s2021.e0317 - Pattys Day Video.mp4
@ -151,6 +209,23 @@ server. The `--dry-run` flag can be used to view file output before any download
tvshow.nfo tvshow.nfo
``` ```
### Beyond TV Shows
The above example made heavy-use of `ytdl-sub` prebuilt presets and hides many
features that are offered. `ytdl-sub` strives to support _any_ use case that first requires
a download via yt-dlp. Use `ytdl-sub` to download, format, and convert media for your media
player to recognize downloads as:
- Movies
- TV shows
- From a single channel or playlist
- From multiple channels or playlists
- From individual videos
- Extracted audio as podcasts
- Music videos
- Music, including:
- Individual songs
- Albums
- Discographies
## Installation ## Installation
The ytdl-sub docker image uses The ytdl-sub docker image uses