Configuration File#

config.yaml#

ytdl-sub is configured using a config.yaml file.

The config.yaml is made up of two sections:

configuration:
presets:

You can jump to any section and subsection of the config using the navigation section to the left.

Note for Windows users, paths can be represented with C:/forward/slashes/like/linux. If you wish to represent paths like Windows, you will need to C:\\double\\bashslash\\paths in order to escape the backslash character.

configuration#

The configuration section contains app-wide configs applied to all presets and subscriptions.

class ytdl_sub.config.config_validator.ConfigOptions#

property working_directory: str#: The directory to temporarily store downloaded files before moving them into their final directory. Defaults to .ytdl-sub-working-directory

property umask: str | None#: Umask (octal format) to apply to every created file. Defaults to “022”.

property dl_aliases: Dict[str, str] | None#

Alias definitions to shorten ytdl-sub dl arguments. For example,

configuration:
  dl_aliases:
    mv: "--preset music_video"
    u: "--download.url"

Simplifies

ytdl-sub dl --preset "Jellyfin Music Videos" --download.url "youtube.com/watch?v=a1b2c3"

ytdl-sub dl --mv --u "youtube.com/watch?v=a1b2c3"

property file_name_max_bytes: int#: Max file name size in bytes. Most OS’s typically default to 255 bytes.

property lock_directory: str#: The directory to temporarily store file locks, which prevents multiple instances of ytdl-sub from running. Note that file locks do not work on network-mounted directories. Ensure that this directory resides on the host machine. Defaults to /tmp.

property ffmpeg_path: str#: Path to ffmpeg executable. Defaults to /usr/bin/ffmpeg for Linux, and ffmpeg.exe for Windows (in the same directory as ytdl-sub).

property ffprobe_path: str#: Path to ffprobe executable. Defaults to /usr/bin/ffprobe for Linux, and ffprobe.exe for Windows (in the same directory as ytdl-sub).

persist_logs#

Within configuration, define whether logs from subscription downloads should be persisted.

configuration:
  persist_logs:
    logs_directory: "/path/to/log/directory"

Log files are stored as YYYY-mm-dd-HHMMSS.subscription_name.(success|error).log.

class ytdl_sub.config.config_validator.PersistLogsValidator#

property logs_directory: str#: Required. The directory to store the logs in.

property keep_successful_logs: bool#: Optional. Whether to store logs when downloading is successful. Defaults to True.

presets#

presets define a formula for how to format downloaded media and metadata.

This section is work-in-progress!

preset#

Presets support inheritance by defining a parent preset:

presets:
  custom_preset:
    ...
  parent_preset:
    ...
  child_preset:
    preset: "parent_preset"

In the example above, child_preset inherits all fields defined in parent_preset. It is advantageous to use parent presets where possible to reduce duplicate yaml definitions.

Presets also support inheritance from multiple presets:

child_preset:
  preset:
    - "custom_preset"
    - "parent_preset"

In this example, child_preset will inherit all fields from custom_preset and parent_preset in that order. The bottom-most preset has the highest priority.

If you are only inheriting from one preset, the syntax preset: "parent_preset" is valid YAML. Inheriting from multiple presets require use of a list.

Configuration File

Contents