Config

ytdl-sub is configured using a config.yaml file. You can view our examples and read detailed documentation for every configurable field below.

config.yaml

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.

configuration

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

class ConfigOptions

property working_directory: str: The directory to temporarily store downloaded files before moving them into their final directory.

property umask: Optional[str]: Umask (octal format) to apply to every created file. Defaults to “022”.

property dl_aliases: Optional[Dict[str, str]]

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

configuration:
  dl_aliases:
    mv: "--preset yt_music_video"
    v: "--youtube.video_url"

Simplifies

ytdl-sub dl --preset "yt_music_video" --youtube.video_url "youtube.com/watch?v=a1b2c3"

to

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

presets

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

download_strategy

Download strategies dictate what is getting downloaded from a source. Each download strategy has its own set of parameters.

youtube

Download strategies for downloading videos (or audio if you configure ytdl_options correctly) from Youtube. See Download strategies for downloading music from Soundcloud. See Youtube Variables for available source variables to use.

channel

class YoutubeChannelDownloaderOptions

Downloads all videos from a youtube channel.

Usage:

presets:
  my_example_preset:
    youtube:
      # required
      download_strategy: "channel"
      channel_url: "UCsvn_Po0SmunchJYtttWpOxMg"
      # optional
      channel_avatar_path: "poster.jpg"
      channel_banner_path: "fanart.jpg"
      before: "now"
      after: "today-2weeks"

property channel_url: str: Required. The channel’s url, i.e. https://www.youtube.com/channel/UCsvn_Po0SmunchJYOWpOxMg. URLs with /username or /c are valid to use.

property channel_avatar_path: Optional[ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator]: Optional. Path to store the channel’s avatar thumbnail image to.

property channel_banner_path: Optional[ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator]: Optional. Path to store the channel’s banner image to.

property after: Optional[ytdl_sub.validators.string_datetime.StringDatetimeValidator]: Optional. Only download videos after this datetime.

property before: Optional[ytdl_sub.validators.string_datetime.StringDatetimeValidator]: Optional. Only download videos before this datetime.

ytdl_option_defaults()

Default ytdl_options for channel

ytdl_options:
  ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
  break_on_existing: True  # stop downloads (newest to oldest) if a video is already downloaded
  break_on_reject: True  # stops downloads if the video's upload date is out of the specified 'before'/'after' range

playlist

class YoutubePlaylistDownloaderOptions

Downloads all videos from a youtube playlist.

Usage:

presets:
  my_example_preset:
    youtube:
      # required
      download_strategy: "playlist"
      playlist_url: "https://www.youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"

property playlist_url: str: Required. The playlist’s url, i.e. https://www.youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg.

ytdl_option_defaults()

Default ytdl_options for playlist

ytdl_options:
  ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
  break_on_existing: True  # stop downloads (newest to oldest) if a video is already downloaded

video

class YoutubeVideoDownloaderOptions

Downloads a single youtube video. This download strategy is intended for CLI usage performing a one-time download of a video, not a subscription.

Usage:

presets:
  example_preset:
    youtube:
      # required
      download_strategy: "video"
      video_url: "youtube.com/watch?v=VMAPTo7RVDo"

CLI usage:

ytdl-sub dl --preset "example_preset" --youtube.video_url "youtube.com/watch?v=VMAPTo7RVDo"

property video_url: str: Required. The url of the video, i.e. youtube.com/watch?v=VMAPTo7RVDo.

ytdl_option_defaults()

Default ytdl_options for video

ytdl_options:
  ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc

split_video

class YoutubeSplitVideoDownloaderOptions

Downloads a single youtube video, then splits in to separate videos using a file containing timestamps. Each separate video will be formatted as if it was downloaded from a playlist. This download strategy is intended for CLI usage performing a one-time download of a video, not a subscription.

Usage:

presets:
  example_preset:
    youtube:
      # required
      download_strategy: "split_video"
      video_url: "youtube.com/watch?v=VMAPTo7RVDo"
      split_timestamps: path/to/timestamps.txt

CLI usage:

ytdl-sub dl \
  --preset "example_preset" \
  --youtube.video_url "youtube.com/watch?v=VMAPTo7RVDo" \
  --youtube.split_timestamps "path/to/timestamps.txt"

split_timestamps file format:

00 Intro
24 Blackwater Park
23 Bleak
39 Jokes
02:23 Ending

The above will create 5 videos in total. The last timestamp, in this example, would create a video starting at 1:02:23 and end at Youtube video’s ending.

property split_timestamps: str: Required. The path to the file containing the split timestamps.

property video_url: str: Required. The url of the video, i.e. youtube.com/watch?v=VMAPTo7RVDo.

ytdl_option_defaults()

Default ytdl_options for split_video

ytdl_options:
  ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc

merge_playlist

class YoutubeMergePlaylistDownloaderOptions

Downloads all videos in a playlist and merges them into a single video.

Usage:

presets:
  example_preset:
    youtube:
      # required
      download_strategy: "merge_playlist"
      playlist_url: "https://www.youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
      # optional
      add_chapters: False

CLI usage:

ytdl-sub dl \
  --preset "example_preset" \
  --youtube.playlist_url "https://www.youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg" \
  --youtube.add_chapters True

property add_chapters: Optional[bool]: Optional. Whether to add chapters using each video’s title in the merged playlist. Defaults to False.

property playlist_url: str: Required. The playlist’s url, i.e. https://www.youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg.

ytdl_option_defaults()

Default ytdl_options for merge_playlist

ytdl_options:
  ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
  playlistreverse: True  # Sort the playlist so it begins with the first entry
  postprocessors:
    # Convert the videos to mkv format
    - key: "FFmpegVideoConvertor"
      when: "post_process"
      preferedformat: "mkv"
    # Concatenate all the playlist videos into a single file
    - key: "FFmpegConcat"
      when: "playlist"

soundcloud

Download strategies for downloading music from Soundcloud. See Soundcloud Variables for available source variables to use.

albums_and_singles

class SoundcloudAlbumsAndSinglesDownloadOptions

Downloads a soundcloud user’s entire discography. Groups together album tracks and considers any track not in an album as a single. Also includes any collaboration tracks.

Usage:

presets:
  my_example_preset:
    soundcloud:
      # required
      download_strategy: "albums_and_singles"
      url: "soundcloud.com/username"
      # optional
      skip_premiere_tracks: True

property url: str: Required. The Soundcloud user’s url, i.e. soundcloud.com/the_username

property skip_premiere_tracks: bool: Optional. True to skip tracks that require purchasing. False otherwise. Defaults to True.

ytdl_option_defaults()

Default ytdl_options for albums_and_singles

ytdl_options:
  ignoreerrors: True  # ignore errors like hidden videos, age restriction, etc
  format: "bestaudio[ext=mp3]"  # download format the best possible mp3

output_options

class OutputOptions

Defines where to output files and thumbnails after all post-processing has completed.

Usage:

presets:
  my_example_preset:
    output_options:
      # required
      output_directory: "/path/to/videos_or_music"
      file_name: "{title_sanitized}.{ext}"
      # optional
      thumbnail_name: "{title_sanitized}.{thumbnail_ext}"
      maintain_download_archive: True
      keep_files_before: now
      keep_files_after: 19000101

property output_directory: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator: Required. The output directory to store all media files downloaded.

property file_name: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator: Required. The file name for the media file. This can include directories such as "Season {upload_year}/{title}.{ext}", and will be placed in the output directory.

property thumbnail_name: Optional[ytdl_sub.validators.string_formatter_validators.StringFormatterValidator]: Optional. The file name for the media’s thumbnail image. This can include directories such as "Season {upload_year}/{title}.{thumbnail_ext}", and will be placed in the output directory.

property maintain_download_archive: bool

Optional. Maintains a download archive file in the output directory for a subscription. It is named .ytdl-sub-{subscription_name}-download-archive.json, stored in the output directory.

The download archive contains a mapping of ytdl IDs to downloaded files. This is used to create a ytdl download-archive file when invoking a download on a subscription. This will prevent ytdl from redownloading media already downloaded.

Defaults to False.

property keep_files_before: Optional[ytdl_sub.validators.string_datetime.StringDatetimeValidator]

Optional. Requires maintain_download_archive set to True.

Only keeps files that are uploaded before this datetime. By default, ytdl-sub will keep files before now, which implies all files.

property keep_files_after: Optional[ytdl_sub.validators.string_datetime.StringDatetimeValidator]

Optional. Requires maintain_download_archive set to True.

Only keeps files that are uploaded after this datetime. By default, ytdl-sub will keep files after 19000101, which implies all files.

ytdl_options

class YTDLOptions

Optional. This section allows you to add any ytdl argument to ytdl-sub’s downloader. The argument names can differ slightly from the command-line argument names. See this docstring for more details.

ytdl_options should be formatted like:

presets:
  my_example_preset:
    ytdl_options:
      ignoreerrors: True

where each key is a ytdl argument.

overrides

class Overrides

Optional. This section allows you to define variables that can be used in any string formatter. For example, if you want your file and thumbnail files to match without copy-pasting a large format string, you can define something like:

presets:
  my_example_preset:
    overrides:
      output_directory: "/path/to/media"
      custom_file_name: "{upload_year}.{upload_month_padded}.{upload_day_padded}.{title_sanitized}"

    # Then use the override variables in the output options
    output_options:
      output_directory: "{output_directory}"
      file_name: "{custom_file_name}.{ext}"
      thumbnail_name: "{custom_file_name}.{thumbnail_ext}"

Override variables can contain explicit values and other variables, including both override and source variables.

preset

Presets support inheritance by defining a parent preset:

presets:
  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.

Plugins

Plugins are used to perform any type of post-processing to the already downloaded files.

music_tags

class MusicTagsOptions

Adds tags to every download audio file using MediaFile, the same audio file tagging package used by beets. It supports basic tags like title, album, artist and albumartist. You can find a full list of tags for various file types in MediaFile’s source code.

Usage:

presets:
  my_example_preset:
    music_tags:
      tags:
        artist: "{artist}"
        album: "{album}"
        genre: "ytdl downloaded music"

property tags: ytdl_sub.validators.string_formatter_validators.DictFormatterValidator: Key/values of tag names/tag values. Supports source and override variables.

nfo

class NfoTagsOptions

Adds an NFO file for every download file. An NFO file is simply an XML file with a .nfo extension. You can add any values into the NFO.

Usage:

presets:
  my_example_preset:
    nfo:
     nfo_name: "{title_sanitized}.nfo"
     nfo_root: "episodedetails"
     tags:
       title: "{title}"
       season: "{upload_year}"
       episode: "{upload_month}{upload_day_padded}"

property nfo_name: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator: The NFO file name.

property nfo_root: ytdl_sub.validators.string_formatter_validators.StringFormatterValidator

The root tag of the NFO’s XML. In the usage above, it would look like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<episodedetails>
</episodedetails>

property tags: ytdl_sub.validators.string_formatter_validators.DictFormatterValidator

Tags within the nfo_root tag. In the usage above, it would look like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<episodedetails>
  <title>Awesome Youtube Video</title>
  <season>2022</season>
  <episode>502</episode>
</episodedetails>

nfo_output_directory

class OutputDirectoryNfoTagsOptions

Adds a single NFO file in the output directory. An NFO file is simply an XML file with a .nfo extension. You can add any values into the NFO.

Usage:

presets:
  my_example_preset:
    output_directory_nfo_tags:
      nfo_name: "tvshow.nfo"
      nfo_root: "tvshow"
      tags:
        title: "Sweet youtube TV show"

property nfo_name: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator: The NFO file name.

property nfo_root: ytdl_sub.validators.string_formatter_validators.OverridesStringFormatterValidator

The root tag of the NFO’s XML. In the usage above, it would look like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tvshow>
</tvshow>

property tags: ytdl_sub.validators.string_formatter_validators.OverridesDictFormatterValidator

Tags within the nfo_root tag. In the usage above, it would look like

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tvshow>
  <title>Sweet youtube TV show</title>
</tvshow>

subscription.yaml

The subscription.yaml file is where we use our presets in the config.yaml to define a subscription: something we want to recurrently download such as a specific channel or playlist.

The only difference between a subscription and preset is that the subscription must have all required fields and {variables} defined so it can perform a download.

Below is an example that downloads YouTube videos:

config.yaml

 presets:
   playlist_preset_ex:
     youtube:
       download_strategy: "playlist"
     output_options:
       output_directory: "{output_directory}/{playlist_name}"
       file_name: "{playlist_name}.{title}.{ext}"
     overrides:
       output_directory: "/path/to/ytdl-sub-videos"

subscription.yaml

 my_subscription_name:
   preset: "playlist_preset_ex"
   youtube:
     playlist_url: "https://youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
   overrides:
     playlist_name: "diy-playlist"

Our preset playlist_preset_ex uses the YouTube Playlist download strategy, and defines two custom variables: {output_directory} and {playlist_name}. The subscription sets the parent preset to playlist_preset_ex, and must define the playlist_url field and the {playlist_name} variable since the preset did not.

Source Variables

class SourceVariables: Source variables are {variables} that contain metadata from downloaded media. These variables can be used with fields that expect StringFormatterValidator, but not OverridesStringFormatterValidator.

Youtube Variables

class YoutubeVideoVariables

property artist: str: returns: * The artist of a music video if it is available, otherwise it falls back to the channel. * NOTE (Even if a video has music metadata, this variable does not always get pulled via) * yt-dlp. Use with caution.

property artist_sanitized: str: returns: The sanitized artist name.

property channel: str: returns: The channel name.

property channel_sanitized: str: returns: The channel name, sanitized.

property description: str: returns: The description of the entry.

property ext: str: returns: The downloaded entry’s file extension

property extractor: str: returns: The ytdl extractor name

property playlist_index: int: returns: * The index of the video in the playlist. For non-playlist download strategies, this will * always return 1.

property playlist_size: int: returns: The size of the playlist. For non-playlist download strategies, this will always return 1.

classmethod source_variables() → List[str]

Returns: List of all source variables

property thumbnail_ext: str: returns: * The download entry’s thumbnail extension. Will always return ‘jpg’. Until there is a need * to support other image types, we always convert to jpg.

property title: str: returns: The title of the entry

property title_sanitized: str: returns: The sanitized title of the entry, which is safe to use for Unix and Windows file names.

property track_title: str: returns: * The track title of a music video if it is available, otherwise it falls back to the title. * NOTE (Even if a video has music metadata, this variable does not always get pulled via) * yt-dlp. Use with caution.

property track_title_sanitized: str: returns: The sanitized track title.

property uid: str: returns: The entry’s unique ID

property upload_date: str: returns: The entry’s uploaded date, in YYYYMMDD format.

property upload_date_standardized: str: returns: The uploaded date formatted as YYYY-MM-DD

property upload_day: int: returns: The upload day as an integer (no padding).

property upload_day_padded: str: returns: The entry’s upload day padded to two digits, i.e. the fifth returns “05”

property upload_month: int: returns: The upload month as an integer (no padding).

property upload_month_padded: str: returns: The entry’s upload month padded to two digits, i.e. March returns “03”

property upload_year: int: returns: The entry’s upload year

property upload_year_truncated: int: returns: The last two digits of the upload year, i.e. 22 in 2022

Soundcloud Variables

class SoundcloudVariables

property album: str: returns: The entry’s album name. For singles, it will be the same as the title.

property album_sanitized: str: returns: The entry’s sanitized album name, which is safe to use for Unix and Windows file names.

property album_year: int: returns: * The entry’s album year, which is determined by the latest year amongst all tracks in the * album.

property description: str: returns: The description of the entry.

property ext: str: returns: The downloaded entry’s file extension

property extractor: str: returns: The ytdl extractor name

classmethod source_variables() → List[str]

Returns: List of all source variables

property thumbnail_ext: str: returns: * The download entry’s thumbnail extension. Will always return ‘jpg’. Until there is a need * to support other image types, we always convert to jpg.

property title: str: returns: The title of the entry

property title_sanitized: str: returns: The sanitized title of the entry, which is safe to use for Unix and Windows file names.

property track_count: int: returns: The total tracks in album. For singles, it will always be 1.

property track_number: int: returns: The entry’s track number within an album. For singles, it will always be 1.

property track_number_padded: str: returns: The entry’s track number, padded two digits.

property uid: str: returns: The entry’s unique ID

property upload_date: str: returns: The entry’s uploaded date, in YYYYMMDD format.

property upload_date_standardized: str: returns: The uploaded date formatted as YYYY-MM-DD

property upload_day: int: returns: The upload day as an integer (no padding).

property upload_day_padded: str: returns: The entry’s upload day padded to two digits, i.e. the fifth returns “05”

property upload_month: int: returns: The upload month as an integer (no padding).

property upload_month_padded: str: returns: The entry’s upload month padded to two digits, i.e. March returns “03”

property upload_year: int: returns: The entry’s upload year

property upload_year_truncated: int: returns: The last two digits of the upload year, i.e. 22 in 2022

Config Types

The config.yaml uses various types for its configurable fields. Below is a definition for each type.

class StringFormatterValidator

String that can use source variables and overrides for populating things like file paths and metadata.

"{tv_show_file_name}.s{upload_year}.e{upload_month}{upload_day_padded}.{ext}"

is valid when using youtube variables with the following overrides:

presets:
  my_example_preset:
    overrides:
      tv_show_file_name: "sweet_tv_show"

and would resolve to something like sweet_tv_show.s2022.e502.mp4.

class OverridesStringFormatterValidator

String that can only use overrides.

Used in fields that do not touch the downloaded files themselves, but instead, single things like output_directory or the fields in nfo_output_directory

class StringDatetimeValidator

String that contains a yt-dlp datetime. From their docs:

A string in the format YYYYMMDD or
(now|today|yesterday|date)[+-][0-9](microsecond|second|minute|hour|day|week|month|year)(s)

Valid examples are now-2weeks or 20200101.

class DictFormatterValidator: A dict made up of StringFormatterValidator.

class OverridesDictFormatterValidator: A dict made up of OverridesStringFormatterValidator.