How Subscription Files and Presets Work in ytdl-sub

ytdl-sub separates what to download from how to store it. A subscription file lists the sources you want (channels, playlists, or individual URLs), and a preset supplies the configuration that decides where files land, how they are named, and what metadata is written. You point a subscription at one or more presets, and ytdl-sub applies that configuration to every entry in the file. The ytdl-sub User Guide documents both pieces under Configuration File, Presets, and Subscription File, with ready-made presets collected in the Prebuilt Preset Reference.

Subscription files: the "what"

A subscription file is a YAML document whose top-level keys are subscription names. Each entry describes a source and the presets to apply. The guide's Subscription File reference covers the available fields; the essential shape is a source URL plus a preset reference:

__preset__:
  overrides:
    tv_show_directory: "/media/TV Shows"

my_show:
  preset: "TV Show"
  source:
    - "https://www.youtube.com/@SomeChannel"

Key behaviors to know:

• One file, many subscriptions. Each top-level key is independent, so a single file can mix a TV channel, a music playlist, and a one-off video.
• Sources are lists. Listing multiple URLs under one subscription treats them as the same logical show or album, which matters for episode and track numbering.
• __preset__ is shared configuration. Anything placed here applies to every subscription in the file unless a subscription overrides it — useful for setting a common output directory once.

Presets: the "how"

A preset is a named bundle of settings: output paths, file naming, metadata/NFO generation, quality selection, and download behavior. Presets can build on other presets, so a specific one like a TV show preset inherits from a general media-quality preset and only changes what it needs.

The guide organizes prebuilt presets into four families:

Helper Presets are smaller building blocks (for example, naming or metadata fragments) that the larger presets compose together. You normally use the family presets directly and only reach for helpers when customizing.

How the two combine

The merge order is the mechanism worth understanding: prebuilt preset → your preset overrides → subscription-level settings → __preset__ defaults. Later layers win. That means you can adopt a prebuilt TV preset wholesale, then change only the output directory, without copying the entire preset definition.

A practical pattern is to define a custom preset that inherits from a prebuilt one:

__preset__:
  preset:
    - "TV Show"
    - "1080p"

my_show:
  overrides:
    tv_show_directory: "/media/TV Shows/My Show"
  source:
    - "https://www.youtube.com/@SomeChannel"

Here the subscription inherits the TV Show structure and the 1080p quality preset, and overrides only the destination folder.

Choosing an approach

• Use prebuilt presets as-is if your library matches a standard shape (TV seasons, artist/album music). This is the fastest path and the one the Getting Started guide walks through.
• Override individual fields when only paths or quality differ — no need to write a full preset.
• Write a custom preset when you need naming or metadata rules the prebuilt families don't cover; inherit from a prebuilt preset so you keep its structure and change only the parts you care about.

Common sticking points

• Preset names are exact. A typo in a preset reference fails silently or errors at run time; check names against the Prebuilt Preset Reference.
• Overrides belong at the right level. A setting under __preset__ affects every subscription in the file; put per-show settings under that subscription's overrides.
• Numbering depends on grouping. Splitting one channel across multiple subscriptions can break episode ordering — keep a single logical show in one subscription.
• Verify before a full run. The guide's Debugging section covers inspecting the resolved configuration, which is the quickest way to confirm your preset merge produced the paths and names you expected.