Ctrl+K

Scripting

Scripting#

ytdl-sub fields (file-names, tags, etc) are defined using variables and scripts. The links below contain reference documentation for each built-in variable and scripting function.

How it Works#

Fields in the config that support formatters mean they support scripting, and will format the field using its defined script.

In its most basic form, a script is a string comprised of variables and/or functions.

Static String#

The following example sets ytdl-sub’s output directory. It is considered static because it does not depend on anything from an entry.

output_options:
  output_directory: "/path/to/tv_shows/Custom YTDL-SUB TV Show"

Static Variables#

ytdl-sub offers a few built-in static variables, including subscription_name. We can use this instead of hard-coding it above:

output_options:
  output_directory: "/path/to/tv_shows/{subscription_name}"

The syntax for variable usage is curly-braces with the variable name within it. Assuming our subscription is actually named “Custom YTDL-SUB TV Show”, then ytdl-sub will actually write to that directory.

Entry Variables#

For context, an entry is a video or audio file downloaded from yt-dlp. Entry variables are variables that are derived from an entry’s info.json file. This file comes from yt-dlp and contains every piece of metadata that it scraped.

These variables are not considered static since they change per entry download. There are a few fields in ytdl-sub (i.e. output_directory) that must be static. For others, we are free to use values that derive from an entry.

Suppose we want to customize the name of an entry’s output file and thumbnail to include its title in its name. We can do that using entry variables:

output_options:
  output_directory: "/path/to/tv_shows/{subscription_name}"
  file_name: "{title}.{ext}"
  thumbnail_name: "{title}.{thumbnail_ext}"

Creating Custom Variables#

Suppose we want to include the date in our file names. This means we’d need to update both the file_name and thumbnail_name fields to include it.

Instead, we can create a custom override variable. This is ytdl-sub’s method for creating and overriding custom variables.

These are created in the overrides section. Let’s take our above example and create a custom_file_name variable to use for the entry file and thumbnail fields:

output_options:
  output_directory: "/path/to/tv_shows/{subscription_name}"
  file_name: "{custom_file_name}.{ext}"
  thumbnail_name: "{custom_file_name}.{thumbnail_ext}"

overrides:
  custom_file_name: "{upload_date_standardized} {title}"

Sanitizing Variables#

For experienced yt-dlp scrapers, you may be thinking:

  • What if the title has characters that do not play nice with my operating system?

ytdl-sub is able to sanitize any variable, meaning it replaces any problematic characters with safe alternatives that can be used in file names. We can ensure our file names and directories are safe by using:

output_options:
  output_directory: "/path/to/tv_shows/{subscription_name_sanitized}"
  file_name: "{custom_file_name}.{ext}"
  thumbnail_name: "{custom_file_name}.{thumbnail_ext}"

overrides:
  custom_file_name: "{upload_date_standardized} {title_sanitized}"

Simply add a _sanitized suffix to any variable name to make it sanitized.

Note

Make sure you do not sanitize custom variables that intentionally create directories, (i.e. sanitizing /path/to/tv_shows/) otherwise they will… be sanitized and not resolve to directories!

Using Scripting Functions#

Let’s suppose you are an avid command-line user, and like all of your file names to be snake_cased_with_no_spaces. We can use the replace scripting function to create and use a snake-cased title.

output_options:
  output_directory: "/path/to/tv_shows/{subscription_name_sanitized}"
  file_name: "{custom_file_name}.{ext}"
  thumbnail_name: "{custom_file_name}.{thumbnail_ext}"

overrides:
  snake_cased_title: >-
    {
      %replace( title, ' ', '_' )
    }
  custom_file_name: "{upload_date_standardized}_{snake_cased_title_sanitized}"

Scripting functions are similar to variables - they must be used within curly-braces. It is good practice to use >- when defining variables that use functions. It is YAML’s way of saying:

  • Allow a string to be multi-lined, and do not include newlines before or after it.

See for yourself here. Any whitespace within curly-braces is okay since it will be parsed out. This is needed to make scripting function usage readable.

Important

It is important to use >- over other YAML new-line directives like > because they add newlines before or after curly-braces, and will be included in your variable’s output string.

Advanced Scripting#

Accessing info.json Fields#

The entirety of an entry’s info.json file resides in the Map variable entry_metadata.

Any field can be accessed by using the map_get function like so:

Fetches the ‘artist’ value from the .info.json, returns null if it does not exist.#
 artist: >-
   { %map_get( entry_metadata, "artist", null ) }

Creating Custom Functions#

Custom functions can be created in the overrides section using the following syntax:

overrides:
  "%get_entry_metadata_field": >-
    { %map_get( entry_metadata, $0, null ) }

Custom function definitions must have % as a prefix to the function name, be surrounded by quotes to make YAML parsing happy, and can support arguments using $0, $1, … to indicate their first argument, second argument, etc.

Using our new custom function, we can simply the artist variable definition above to:

overrides:
  "%get_entry_metadata_field": >-
    { %map_get( entry_metadata, $0, null ) }
  artist: >-
    { get_entry_metadata_field("artist") }
Contents