Basic Configuration

A configuration file serves two purposes:

1. Set application-level functionality that is not specifiable in a subscription file.

Note

ytdl-sub does not require a configuration file. However, certain application settings may be desirable for tweak, such as setting working_directory to make ytdl-sub perform the initial download to an SSD drive.

2. Create custom presets.

Note

In the prior Initial Subscription examples, we leveraged the prebuilt preset Jellyfin TV Show by Date. This preset is entirely built using the same YAML configuration system offered to users by using a configuration file.

The following section attempts to demystify and explain how to…

• Set an application setting

• Know whether or not custom presets are actually needed

• How to create a custom preset

• How to use a custom preset on subscriptions

---

how this works, and show-case how

configuration:
  working_directory: ".ytdl-sub-working-directory"

presets:
  TV Show:
    preset:
      - "Jellyfin TV Show by Date"
      - "Max 1080p"

    embed_thumbnail: True

    throttle_protection:
       sleep_per_download_s:
         min: 2.2
         max: 10.8
       sleep_per_subscription_s:
         min: 9.0
         max: 14.1
       max_downloads_per_subscription:
         min: 10
         max: 36

    overrides:
      tv_show_directory: "/tv_shows"

  TV Show Only Recent:
    preset:
      - "TV Show"
      - "Only Recent"

Configuration Section

The configuration section sets options for ytdl-sub execution. Most users should set the path where ytdl-sub temporarily stores downloaded data before assembling it and moving it into your library. To avoid unnecessarily long large file renames, use a path on the same filesystem as your library in the overrides: / *_directory: paths:

configuration:
  working_directory: ".ytdl-sub-working-directory"

Preset Section

Underneath presets, we define two custom presets with the names TV Show and TV Show Only Recent.

presets:
  TV Show:
    ...
  TV Show Only Recent:
    ...

The indentation example above shows how to define multiple presets.

Custom Preset Definition

Before we break down the above TV Show preset, lets first outline a preset layout:

Preset Name:
  preset:
    ...

  plugin(s):
    ...

  overrides:
    ...

Presets can contain three important things:

1. preset section, which can inherit prebuilt presets or other presets defined in your config.

2. Plugin definitions

3. overrides, which can override inherited preset variables

Presets do not have to define all of these, as we’ll see in the TV Show Only Recent preset.

Inheriting Presets

  TV Show:
    preset:
      - "Jellyfin TV Show by Date"
      - "Max 1080p"

The following snippet shows that the TV Show preset will inherit all properties of the prebuilt presets Jellyfin TV Show by Date and Max 1080p in that order.

Order matters for preset inheritance. Bottom-most presets will override ones above them.

It is highly advisable to use prebuilt presets as a starting point for custom preset building, as they do the work of preset building to ensure things show as expected in their respective media players. Read on to see how to override prebuilt preset specifics such as title.

Defining Plugins

    embed_thumbnail: True

    throttle_protection:
       sleep_per_download_s:
         min: 2.2
         max: 10.8
       sleep_per_subscription_s:
         min: 9.0
         max: 14.1
       max_downloads_per_subscription:
         min: 10
         max: 36

Our TV Show sets two plugins, throttle_protection and embed_thumbnail. Each plugin’s documentation shows the respective fields that they support.

If an inherited preset defines the same plugin, the custom preset will use ‘merge-and-append’ strategy to combine their definitions. What this means is:

1. If the field is a map (i.e. has sub-params like sleep_per_download_s above) or array, it will try to merge them

2. If both the inherited preset and custom preset set the same exact field and value (i.e. embed_thumbnail) the custom preset will overwrite it

Setting Override Variables

    overrides:
      tv_show_directory: "/ytdl_sub_tv_shows"

All override variables reside underneath the overrides section.

It is important to remember that individual subscriptions can override specific override variables. When defining variables in a preset, it is best practice to define them with the intention that

1. All subscriptions will use its value them

2. Use them as placeholders to perform other logic, then have subscriptions or child presets define their specific value

For simplicity, we’ll focus on (1) for now. The above snippet sets the tv_show_directory variable to a file path. This variable name is specific to the prebuilt TV show presets.

See the prebuilt preset reference to see all available variables that are overridable.

Using Custom Presets in Subscriptions

Subscription files can use custom presets just like any other prebuilt preset. Below shows a complete subscription file using the above two custom presets.

TV Show:
  = Documentaries:
    "NOVA PBS": "https://www.youtube.com/@novapbs"

  = Kids | = TV-Y:
    "Jake Trains": "https://www.youtube.com/@JakeTrains"

TV Show Only Recent:
  = News:
    "BBC News": "https://www.youtube.com/@BBCNews"

Notice how we do not need to define tv_show_directory in the __preset__ section like in prior examples. This is because our custom presets do the work of defining it.

Reference Custom Config in the CLI

Be sure to tell ytdl-sub to use your config by using the argument --config /path/to/config.yaml.

If you run ytdl-sub in the same directory, and the config file is named config.yaml, it will use it by default.

Visualizing a subscription in Preset form

Subscription file syntax is designed to minimize boiler-plate when authoring new subscriptions. You can unpack any subscription using the inspect sub-command to see its boiler-plate preset format.

ytdl-sub inspect --match "BBC News" /path/to/subscriptions.yaml

This can be utilized for numerous purposes including:

• Ensuring your custom preset is getting applied correctly.

• Figuring out which variables set things like file names, metadata, etc.

• Understanding how subscription syntax translates to preset representation.

The default --level of inspect will fill in defined variables. Using --level original will present the subscription’s raw layout with no fill.