Subscriptions#
Once you understand how ytdl-sub works, it’s time to start writing your Subscription File.
Media library paths#
Everyone’s media library may use different paths so ytdl-sub can’t provide
defaults. Tell ytdl-sub where to put your media using overrides:
__preset__:
overrides:
tv_show_directory: "/tv_shows"
music_directory: "/music"
music_video_directory: "/music_videos"
See the reference documentation for details about the ‘__preset__:’ special key.
Media library software and media types#
Different media library software, such as Jellyfin, Kodi, Plex, or Emby, have
different requirements for where media files are placed, how those files are named, how
metadata is formatted, and more. Those software also have different requirements for
different types of media, such as shows/series, music, music videos, etc.. Use
prebuilt presets in YAML keys to tell
ytdl-sub which media library software and media type to process downloaded files
for.
The actual subscription is defined in the lowest indentation level YAML keys. The
example below defines a subscription named NOVA PBS to archive downloads from the
entries in the https://www.youtube.com/@novapbs URL.
Jellyfin TV Show by Date:
"NOVA PBS": "https://www.youtube.com/@novapbs"
Bandcamp:
"Emily Hopkins": "https://emilyharpist.bandcamp.com/"
Which entries#
The helper presets also provide support for controlling which entries are downloaded and archived. These presets are intended to be combined with the library software and media type presets.
Combine presets using the ‘.. | …’ special character in the YAML keys:
# Only download entries whose upload date is within the past 2 months:
Kodi TV Show by Date | Only Recent:
"NOVA PBS": "https://www.youtube.com/@novapbs"
# Only download 20 entries per run:
Soundcloud Discography | Chunk Downloads:
"UKNOWY": "https://soundcloud.com/uknowymunich"
What format, quality, or resolution#
The media quality presets provide support
for controlling which yt-dlp media “format” to download, such as 1080p video
resolution or 320k audio bitrate.
Users may also group and combine presets using the YAML hierarchy. Subscriptions merge all the presets from their ancestor YAML keys. The hierarchy indentation depth may be as deep as needed to group your subscriptions for easy maintenance:
Jellyfin TV Show by Date | Only Recent:
# Download the highest resolution available:
Max Video Quality:
"NOVA PBS": "https://www.youtube.com/@novapbs"
"National Geographic": "https://www.youtube.com/@NatGeo"
# Download the highest resolution available that is 720p or less:
Max 720p:
"Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"
Soundcloud Discography | Chunk Downloads:
# Only download audio using the Opus codec, not MP3 or other codecs:
Max Opus Quality:
"UKNOWY": "https://soundcloud.com/uknowymunich"
Genre and rating metadata#
Presets may also support using arbitrary values from YAML keys prefixed with ‘=
…’. The =
... prefix may be used at any indentation depth and may also be combined with presets
and other = ... values using the ... | ... special character to best group your
subscriptions.
By convention
in the built-in library software and media type presets, the first = ... value
specifies the genre for all descendant subscriptions. For the TV Show ... presets,
the second = ... value specifies the rating for all descendant subscriptions:
= Kids:
Jellyfin TV Show by Date | = TV-Y:
"Jake Trains": "https://www.youtube.com/@JakeTrains"
"Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel"
Soundcloud Discography:
"Foo Kids Band": "https://soundcloud.com/foo-kids-band"
Override variables for one subscription#
Most variable overrides aren’t actually specific to just one subscription and should be set in your own custom presets. But use the override mode ‘~…’ prefix when an override is specific to only one subscription and will never be shared with another:
Jellyfin TV Show by Date:
"~NOVA PBS":
url: "https://www.youtube.com/@novapbs"
tv_show_directory: "/media/Unique/Series/Path"
Next Steps#
Once you’ve defined your subscriptions, it’s time to test your configuration and try your first download.