========= 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. .. toctree:: :maxdepth: 1 entry_variables static_variables scripting_functions scripting_types 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. .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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: .. code-block:: yaml 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. .. code-block:: yaml 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: .. code-block:: yaml :caption: 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: .. code-block:: yaml 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: .. code-block:: yaml overrides: "%get_entry_metadata_field": >- { %map_get( entry_metadata, $0, null ) } artist: >- { get_entry_metadata_field("artist") }