### Full Configuration Example

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/first_config.md

This example demonstrates a complete configuration file structure, including application settings and custom preset definitions for TV shows.

```yaml
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"

```

--------------------------------

### Install Local Dependencies

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/development/index.md

Install the project in editable mode with test, lint, and documentation dependencies.

```shell
pip install -e .[test,lint,docs]
```

```zsh
pip install -e .\[test,lint,docs\]
```

--------------------------------

### Download Single Subscription Example

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/usage.md

Example of how to specify subscription details as CLI arguments for the 'dl' command, using dot notation for nested properties.

```bash
ytdl-sub dl \
    --preset "tv_show" \
    --overrides.tv_show_name "Rick A" \
    --overrides.url: "https://www.youtube.com/channel/UCuAXFkgsw1L7xaCfnd5JJOw"
```

--------------------------------

### Install ytdl-sub and dependencies on Windows

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/windows.md

Downloads FFmpeg and ytdl-sub binaries, extracts the required executables, and verifies the installation.

```powershell
# Download ffmpeg/ffprobe dependencies from yt-dlp
curl.exe -L -o ffmpeg.zip https://github.com/yt-dlp/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-win64-gpl.zip
tar -xf ffmpeg.zip
move "ffmpeg-master-latest-win64-gpl\bin\ffmpeg.exe" "ffmpeg.exe"
move "ffmpeg-master-latest-win64-gpl\bin\ffprobe.exe" "ffprobe.exe"

# Download ytdl-sub
curl.exe -L -o ytdl-sub.exe https://github.com/jmbannon/ytdl-sub/releases/latest/download/ytdl-sub.exe
ytdl-sub.exe -h
```

--------------------------------

### Local Install ytdl-sub for Development

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/agnostic.md

Clone the repository and install ytdl-sub in editable mode within a Python 3.10 virtual environment for local development.

```bash
git clone https://github.com/jmbannon/ytdl-sub.git
cd ytdl-sub

pip install -e .
```

--------------------------------

### Install ffmpeg on Linux

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/linux.md

Download and install the latest ffmpeg build from yt-dlp to ensure compatibility.

```bash
curl -L -o ffmpeg.tar.gz https://github.com/yt-dlp/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linux64-gpl.tar.xz
tar -xf ffmpeg.tar.gz
chmod +x ffmpeg-master-latest-linux64-gpl/bin/ffmpeg
chmod +x ffmpeg-master-latest-linux64-gpl/bin/ffprobe

# May need sudo / root permissions to perform
mv ffmpeg-master-latest-linux64-gpl/bin/ffmpeg /usr/bin/ffmpeg
mv ffmpeg-master-latest-linux64-gpl/bin/ffprobe /usr/bin/ffprobe
```

--------------------------------

### Install ytdl-sub via PIP

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/agnostic.md

Use this command to install the latest version of ytdl-sub from PyPI. Ensure Python 3.10+ and ffmpeg are installed.

```bash
python3 -m pip install -U ytdl-sub
```

--------------------------------

### Install ffmpeg on Linux ARM

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/linux.md

Download and install the latest ARM-compatible ffmpeg build from yt-dlp.

```bash
curl -L -o ffmpeg.tar.gz https://github.com/yt-dlp/FFmpeg-Builds/releases/download/latest/ffmpeg-master-latest-linuxarm64-gpl.tar.xz
tar -xf ffmpeg.tar.gz
chmod +x ffmpeg-master-latest-linuxarm64-gpl/bin/ffmpeg
chmod +x ffmpeg-master-latest-linuxarm64-gpl/bin/ffprobe

# May need sudo / root permissions to perform
mv ffmpeg-master-latest-linuxarm64-gpl/bin/ffmpeg /usr/bin/ffmpeg
mv ffmpeg-master-latest-linuxarm64-gpl/bin/ffprobe /usr/bin/ffprobe
```

--------------------------------

### Install ytdl-sub on Linux

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/linux.md

Download and execute the ytdl-sub binary for standard Linux systems.

```bash
curl -L -o ytdl-sub https://github.com/jmbannon/ytdl-sub/releases/latest/download/ytdl-sub
chmod +x ytdl-sub
./ytdl-sub -h
```

--------------------------------

### NFO XML Structure Examples

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Examples of the generated XML structure for NFO files based on the provided configuration.

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

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<season>
  <title>My custom season name!</title>
</season>
```

--------------------------------

### Example of Simplified Download Command

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/config_yaml.md

Demonstrates how defined aliases can be used to shorten a complex download command, making it more concise and easier to type.

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

--------------------------------

### Install ytdl-sub on Linux ARM

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/install/linux.md

Download and execute the aarch64 binary for Linux ARM systems.

```bash
curl -L -o ytdl-sub https://github.com/jmbannon/ytdl-sub/releases/latest/download/ytdl-sub_aarch64
chmod +x ytdl-sub
./ytdl-sub -h
```

--------------------------------

### Subscription File with Custom Presets

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/first_config.md

This example demonstrates a subscription file that utilizes custom presets. It defines different categories of subscriptions (Documentaries, Kids, News) and links them to YouTube channels, leveraging custom presets for configuration like 'tv_show_directory'.

```yaml
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"
```

--------------------------------

### Configure Output Options in YAML

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Define output directory, file naming conventions, and archive management for downloaded content. This example shows required and optional settings.

```yaml
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}"
      info_json_name: "{title_sanitized}.{info_json_ext}"
      download_archive_name: ".ytdl-sub-{subscription_name}-download-archive.json"
      migrated_download_archive_name: ".ytdl-sub-{subscription_name_sanitized}-download-archive.json"
      maintain_download_archive: True
      keep_files_before: now
      keep_files_after: 19000101
      keep_max_files: 1000
      keep_files_date_eval: "{upload_date_standardized}"
```

--------------------------------

### YAML Path Formatting Example

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/config_yaml.md

Illustrates how to specify Windows paths in the YAML configuration, using either forward slashes or double backslashes to escape the backslash character.

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

  experimental:
    enable_update_with_info_json: True

  ffmpeg_path: "/usr/bin/ffmpeg"
  ffprobe_path: "/usr/bin/ffprobe"

  file_name_max_bytes: 255
  lock_directory: "/tmp"

  persist_logs:
    keep_successful_logs: True
    logs_directory: "/var/log/ytdl-sub-logs"

  umask: "022"
  working_directory: ".ytdl-sub-working-directory"
```

--------------------------------

### Convert video_tags tags

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/deprecation_notices.md

This example shows the simplification of `video_tags`. The `tags` key is removed, and its contents are now directly under `video_tags`.

```yaml
my_example_preset:
  video_tags:
    tags:
      title: "Elvis Presley Documentary"
```

```yaml
my_example_preset:
  video_tags:
    title: "Elvis Presley Documentary"
```

--------------------------------

### Convert music_tags embed_thumbnail and tags

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/deprecation_notices.md

This example demonstrates the conversion of the `music_tags` configuration. The `embed_thumbnail` option is moved to the top level, and `tags` are now directly under `music_tags`.

```yaml
my_example_preset:
  music_tags:
    embed_thumbnail: True
    tags:
      artist: "Elvis Presley"
```

```yaml
my_example_preset:
  embed_thumbnail: True
  music_tags:
    artist: "Elvis Presley"
```

--------------------------------

### Define Same-Line String

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a string variable on the same line.

```yaml
string_variable: "{ %string('This is a String variable') }"
```

--------------------------------

### Inheriting Presets

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/first_config.md

Example of a custom preset inheriting properties from multiple prebuilt or other custom presets. Order matters, with lower presets overriding higher ones.

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

```

--------------------------------

### Define subscription_array

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/static_variables.md

Example YAML structure for populating the subscription_array variable.

```yaml
"Subscription Name":
  - "https://url1.com/..."
  - "https://url2.com/..."
```

--------------------------------

### ytdl-sub Inspect Command Usage

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/usage.md

Example of how to use the 'inspect' command to examine a subscription's preset representation, with options to match subscriptions and mock variable values.

```bash
ytdl-sub inspect --match "Game Chops" --mock 'title=Lets Play' examples/music_subscriptions.yaml
```

--------------------------------

### Defining Custom Presets

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/first_config.md

Structure for defining custom presets under the 'presets' key in the configuration file. This example shows placeholders for preset names.

```yaml
presets:
  TV Show:
    ...
  TV Show Only Recent:
    ...

```

--------------------------------

### Define Same-Line Integer

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining an integer variable on the same line.

```yaml
int_variable: "{ %int(2022) }"
```

--------------------------------

### Define subscription_value

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/static_variables.md

Example YAML structure for setting the subscription_value variable.

```yaml
"Subscription Name": "https://..."
```

--------------------------------

### Define Multi-Line Integer

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a multi-line integer variable.

```yaml
int_variable: >-
  {
    %int(2022)
  }
```

--------------------------------

### Define subscription_map

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/static_variables.md

Example YAML structure and corresponding Python map representation for subscription_map.

```yaml
+ Subscription Name:
  Music Videos:
    - "https://url1.com/..."
  Concerts:
    - "https://url2.com/..."
```

```python
{
  "Music Videos": [
    "https://url1.com/..."
  ],
  "Concerts: [
    "https://url2.com/..."
  ]
}
```

--------------------------------

### Defining Plugins and Overrides in a Preset

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/first_config.md

Shows how to define plugins like 'embed_thumbnail' and 'throttle_protection' within a custom preset. It also includes an example of overriding specific variables like 'tv_show_directory'.

```yaml
    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

```

```yaml
    overrides:
      tv_show_directory: "/tv_shows"

```

--------------------------------

### NFO file structure with custom tags and attributes

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

This example demonstrates how to define NFO tags with attributes and handle duplicate keys, such as multiple genre entries. The output XML will reflect these definitions.

```yaml
tags:
  named_season:
    - tag: "{source_title}"
      attributes:
        number: "{collection_index}"
  genre:
    - "Comedy"
    - "Drama"
```

--------------------------------

### Configure Windows Task Scheduler

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/automating_downloads.md

Instructions for setting up a basic task in Windows Task Scheduler to run ytdl-sub. This involves specifying the program path, arguments, and starting directory.

```powershell
# Example CLI arguments for Task Scheduler:
# --dry-run sub -o '--ytdl_options.max_downloads 3'
```

--------------------------------

### Convert Regex Plugin to Scripting

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/deprecation_notices.md

This example shows how to convert from the old regex plugin to the new scripting function `regex_capture_many`. The original configuration captures a track title using a regex pattern.

```yaml
  regex:
    from:
      title:
        match:
          - ".*? - (.*)"  # Captures 'Some - Song' from 'Emily Hopkins - Some - Song'
        capture_group_names:
          - "captured_track_title"
        capture_group_defaults:
          - "{title}"
  overrides:
    track_title: "{captured_track_title}"
```

```yaml
  overrides:
    # Captures 'Some - Song' from 'Emily Hopkins - Some - Song'
    captured_track_title: >-
      {
        %regex_capture_many(
          title,
          [ ".*? - (.*)" ],
          [ title ]
        )
      }
    track_title: "{%array_at(captured_track_title, 1)}"
```

--------------------------------

### Configure Chunk Downloads Preset

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/prebuilt_presets/helpers.md

The `Chunk Downloads` preset is useful for archiving large channels by downloading videos starting from the oldest. The `chunk_max_downloads` override variable controls how many videos are downloaded per chunk.

```yaml
__preset__:
  overrides:
    chunk_max_downloads: 20

Plex TV Show by Date:

  # Chunk these ones
  = Documentaries | Chunk Downloads:
    "NOVA PBS": "https://www.youtube.com/@novapbs"
    "National Geographic": "https://www.youtube.com/@NatGeo"

  # But not these ones
  = Documentaries:
    "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"

```

--------------------------------

### Executing Full Downloads

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/downloading.md

Run the sub-command without restrictions to process all configured subscriptions.

```console
ytdl-sub sub
```

--------------------------------

### String Strip Example

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_functions.md

Removes leading and trailing whitespace from a string.

```python
{%trim(" delete the outer! ")%}

# "delete the outer!"
```

--------------------------------

### Define Multi-Line Boolean

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a multi-line boolean variable.

```yaml
bool_variable: >-
  {
    %bool(True)
  }
```

--------------------------------

### Define Same-Line Float

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a float variable on the same line.

```yaml
float_variable: "{ %float(3.14) }"
```

--------------------------------

### Define Multi-Line Float

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a multi-line float variable.

```yaml
float_variable: >-
  {
    %float(3.14)
  }
```

--------------------------------

### Build Documentation

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/development/index.md

Rebuild the project documentation, including content derived from Python docstrings.

```shell
make docs
```

--------------------------------

### Previewing Subscriptions with Dry Run

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/downloading.md

Use the --dry-run flag to simulate downloads and verify configuration without fetching media files. The --match and --ytdl_options.max_downloads flags help restrict the scope to minimize external requests.

```console
cd "/config/ytdl-sub-configs/"
ytdl-sub --dry-run --match="NOVA PBS" sub -o '--ytdl_options.max_downloads 3'
```

--------------------------------

### Run ytdl-sub subscription on Unix and Windows

Source: https://github.com/jmbannon/ytdl-sub/blob/master/examples/README.md

Execute a subscription configuration file using the ytdl-sub CLI. Ensure the configuration file is present in the working directory.

```commandline
ytdl-sub sub tv_show_subscriptions.yaml
```

```commandline
./ytdl-sub.exe sub tv_show_subscriptions.yaml
```

--------------------------------

### Reviewing Real Downloads

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/downloading.md

Execute a limited real download to verify file placement and library integration before running a full sync.

```console
ytdl-sub --match="NOVA PBS" sub -o '--ytdl_options.max_downloads 3'
```

--------------------------------

### Define and use custom scripting functions

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/index.md

Demonstrates creating a custom function with a % prefix and positional arguments, then invoking it within the overrides section.

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

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

--------------------------------

### Apply Multiple Presets with Pipes

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/prebuilt_presets/index.md

Demonstrates how to combine multiple presets, such as 'Plex TV Show by Date' and 'Max Video Quality', using pipes. This configuration applies to all nested subscriptions below the pipe.

```yaml
Plex TV Show by Date | Max Video Quality:

  = Documentaries | Chunk Downloads:
    "NOVA PBS": "https://www.youtube.com/@novapbs"
    "National Geographic": "https://www.youtube.com/@NatGeo"

  = Documentaries:
    "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"

```

--------------------------------

### String Unescape Example

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_functions.md

Converts escaped symbols like newlines and tabs into their actual characters.

```python
{%unescape( "Hello\nWorld" )%}

# Hello
# World
```

--------------------------------

### String Join Example

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_functions.md

Joins elements of an array into a single string, separated by a specified separator.

```python
{%join( ", ", ["item1", "item2"] )%}

# "item1, item2"
```

--------------------------------

### Define Media Library Paths

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/subscriptions.md

Specify custom directories for TV shows, music, and music videos using overrides.

```yaml
__preset__:
  overrides:
    tv_show_directory: "/tv_shows"
    music_directory: "/music"
    music_video_directory: "/music_videos"
```

--------------------------------

### Define Same-Line Boolean

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a boolean variable on the same line. Boolean values are case-insensitive.

```yaml
bool_variable: "{ %bool(FALSE) }"
```

--------------------------------

### Define subscription_indent_i

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/static_variables.md

Example YAML structure demonstrating how ancestor keys populate subscription_indent variables.

```yaml
Preset 1 | = Indent Value 1 | Preset 2:
  Preset 3 | = Indent Value 2 | Preset 4:
    "Subscription Name": "https://..."
```

--------------------------------

### Define New-Line Null

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a null variable using the %string(null) function on a new line.

```yaml
null_variable: >-
  { %string(null) }
```

--------------------------------

### Define Same-Line Array

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining an array variable on the same line, including nested arrays and accessing an element.

```yaml
array_variable: "{ ['element with index 0', 1, 2.0, ['Nested Array 3' ]] }"
element_0: "{ %array_at(array_variable, 0) }"
```

--------------------------------

### Define a Subscription File Preset

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/subscription_yaml.md

Use the __preset__ key to apply global overrides and plugin options to all subscriptions within the file.

```yaml
__preset__:
  # Variables that override defaults from `overrides:` for presets in YAML keys:
  overrides:
    tv_show_directory: "/tv_shows"

  # Directly set plugin options:
  ytdl_options:
    cookiefile: "/config/ytdl-sub-configs/cookie.txt"
```

--------------------------------

### Visualize Subscription in Preset Form

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/first_config.md

This command uses the 'inspect' sub-command to unpack a subscription and view its preset format. It's useful for verifying custom preset application and understanding how subscription syntax translates to presets.

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

--------------------------------

### NFO XML with a single tag

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

This example illustrates the XML structure of an NFO file containing a single tag, such as a title.

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

--------------------------------

### Define New-Line Single Quote String

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a string variable on a new line using single quotes.

```yaml
string_variable: >-
  { %string('This is a String variable') }
```

--------------------------------

### Structure Subscriptions with Presets and Overrides

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/subscription_yaml.md

Organize subscriptions by nesting them under preset and override keys. Subscription names should be quoted to distinguish them from configuration keys.

```yaml
Jellyfin TV Show by Date:
  = News:
    "Breaking News": "https://www.youtube.com/@SomeBreakingNews"
    "BBC News": "https://www.youtube.com/@BBCNews"
```

--------------------------------

### Defining Download Aliases

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/config_yaml.md

Shows how to define custom aliases for download arguments to shorten command-line usage. These aliases simplify repetitive commands.

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

--------------------------------

### Map Get with Empty Map

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Demonstrates the behavior of map_get when called with an empty map and a key that does not exist, which will result in an error.

```yaml
will_throw_key_does_not_exist_error: "{ %map_get( {}, 'key' ) }"
```

--------------------------------

### Define Same-Line Map

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Example of defining a map variable on the same line with various key and value types, and accessing a value by key.

```yaml
map_variable: "{ {'string_key': 'string_value', 1: 'int_key', 'list_value': [ 'elem0', 1, 2.0 ]} }"
string_value: "{ %map_get(map_variable, 'string_key') }"
```

--------------------------------

### Enable Thumbnail Embedding

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Set to 'True' to embed thumbnails directly into the audio/video file.

```yaml
embed_thumbnail: True
```

--------------------------------

### Map Get with Optional Default Value

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_types.md

Retrieves a value from a map using a key. If the key is not found, it returns the specified default value.

```yaml
will_return_default: "{ %map_get( {}, 'key', 'default value' ) }"
```

--------------------------------

### ytdl-sub Subscriptions Command

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/usage.md

Command to download all subscriptions defined in specified subscription files. Defaults to './subscriptions.yaml' if no path is provided.

```default
ytdl-sub [GENERAL OPTIONS] sub [SUBPATH ...]
```

--------------------------------

### Define Static Output Directory

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/index.md

Sets a static output directory for downloaded files. This does not depend on any entry-specific information.

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

--------------------------------

### ytdl-sub View Command

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/usage.md

Command to preview source variables for a given URL, useful for creating new subscriptions. Use '-sc' to view variables after splitting by chapters.

```default
ytdl-sub view [-sc] [URL]
```

--------------------------------

### Conditional Logic with Elif

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/scripting/scripting_functions.md

Use elif for chained conditional statements, similar to else-if in other languages. Requires an odd number of arguments, starting with a condition.

```python
%elif(
   condition1,
   return1,
   condition2,
   return2,
   ...
   else_return
)
```

--------------------------------

### Basic Subscription Configuration

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/subscriptions.md

Define subscriptions for archiving downloads from YouTube channels and Bandcamp pages, grouped by media library software.

```yaml
Jellyfin TV Show by Date:
  "NOVA PBS": "https://www.youtube.com/@novapbs"

Bandcamp:
  "Emily Hopkins": "https://emilyharpist.bandcamp.com/"
```

--------------------------------

### Generated NFO XML with custom tags and attributes

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

This is an example of the resulting XML structure for an NFO file when using custom tags with attributes and duplicate keys.

```xml
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<tvshow>
  <title year="2022">Sweet youtube TV show</season>
  <genre>Comedy</genre>
  <genre>Drama</genre>
</tvshow>
```

--------------------------------

### ytdl-sub Subscriptions Options

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/usage.md

Options specific to the 'sub' command for managing subscription downloads. Use '-u' to update subscriptions with info.json or '-o' to override download configurations.

```text
-u, --update-with-info-json
                      update all subscriptions with the current config using info.json files
-o DL_OVERRIDE, --dl-override DL_OVERRIDE
                      override all subscription config values using `dl` syntax, i.e. --dl-override='--ytdl_options.max_downloads 3'
```

--------------------------------

### Define Subscriptions with Presets

Source: https://github.com/jmbannon/ytdl-sub/blob/master/README.md

This YAML file defines subscriptions for downloading media. It uses presets to configure download and organization settings, including directory paths and yt-dlp options.

```yaml
# subscriptions.yaml:
# Everything in here can be downloaded using the command:
#   ytdl-sub sub subscriptions.yaml

# __preset__ is a place to define global overrides for all subscriptions
__preset__:
  overrides:
    # Root folder of all ytdl-sub TV Shows
    tv_show_directory: "/tv_shows"
    
    # Root folder of all ytdl-sub Music
    music_directory: "/music"
    
    # Root folder of all ytdl-sub Music Videos
    music_video_directory: "/music_videos"
    
    # For 'Only Recent' preset, only keep vids within this range and limit
    only_recent_date_range: "2months"
    only_recent_max_files: 30
    
  # Pass any arg directly to yt-dlp's Python API
  ytdl_options:
    cookiefile: "/config/ytdl-sub-configs/cookie.txt"

###################################################################
# TV Show Presets. Can replace Plex with Plex/Jellyfin/Emby/Kodi

Plex TV Show by Date:

  # Sets genre tag to "Documentaries"
  = Documentaries:
    "NOVA PBS": "https://www.youtube.com/@novapbs"
    "National Geographic": "https://www.youtube.com/@NatGeo"
    "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"

  # Sets genre tag to "Kids", "TV-Y" for content rating
  = Kids | = TV-Y:
    "Jake Trains": "https://www.youtube.com/@JakeTrains"
    "Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel"

  = Music:
    # TV show subscriptions can support multiple urls and store in the same TV Show
    "Rick Beato":
      - "https://www.youtube.com/@RickBeato"
      - "https://www.youtube.com/@rickbeato240"

  # Set genre tag to "News", use `Only Recent` preset to only store videos uploaded recently
  = News | Only Recent:
    "BBC News": "https://www.youtube.com/@BBCNews"

Plex TV Show Collection:
  = Music:
    # Prefix with ~ to set specific override variables
    "~Beyond the Guitar":
      s01_name: "Videos"
      s01_url: "https://www.youtube.com/c/BeyondTheGuitar"
      s02_name: "Covers"
      s02_url: "https://www.youtube.com/playlist?list=PLE62gWlWZk5NWVAVuf0Lm9jdv_-_KXs0W"

###################################################################

```

--------------------------------

### Configure Download URLs with Variables and Thumbnails

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Define download URLs with associated variables and playlist thumbnails. Variables can be overwritten or default to the top-most URL's values. If an entry is returned from multiple URLs, the bottom-most URL's variables are used.

```yaml
download:
  # required
  urls:
    - url: "youtube.com/channel/UCsvn_Po0SmunchJYtttWpOxMg"
      variables:
        season_index: "1"
        season_name: "Uploads"
      playlist_thumbnails:
        - name: "poster.jpg"
          uid: "avatar_uncropped"
        - name: "fanart.jpg"
          uid: "banner_uncropped"
        - name: "season{season_index}-poster.jpg"
          uid: "latest_entry"
    - url: "https://www.youtube.com/playlist?list=UCsvn_Po0SmunchJYtttWpOxMg"
      variables:
        season_index: "2"
        season_name: "Playlist as Season"
      ytdl_options:
        break_on_existing: False
      playlist_thumbnails:
        - name: "season{season_index}-poster.jpg"
          uid: "latest_entry"
```

--------------------------------

### Specify Multiple Download URLs

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Provide a list of URLs for downloading multiple videos or playlists.

```yaml
download:
  - "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  - "https://www.youtube.com/watch?v=3BFTio5296w"
```

--------------------------------

### Configure ytdl_options in YAML

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Define downloader behavior by mapping ytdl-sub keys to yt-dlp arguments within a preset configuration.

```yaml
presets:
  my_example_preset:
    ytdl_options:
      # Ignore any download related errors and continue
      ignoreerrors: True
      # Stop downloading additional metadata/videos if it
      # exists in your download archive
      break_on_existing: True
      # Path to your YouTube cookies file to download 18+ restricted content
      cookiefile: "/path/to/cookies/file.txt"
      # Only download this number of videos/audio
      max_downloads: 10
      # Download and use English title/description/etc YouTube metadata
      extractor_args:
        youtube:
          lang:
            - "en"
```

--------------------------------

### Define Music Base Preset and Single Track Download

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/prebuilt_presets/music.md

The _music_base preset provides default audio extraction and tagging configurations. The Single preset demonstrates how to inherit from this base to download individual tracks.

```yaml
presets:

  
  _music_base:

    output_options:
      output_directory: "{music_directory}"
      file_name: "{track_full_path}"
      thumbnail_name: "{album_cover_path}"
      maintain_download_archive: True

    ytdl_options:
      break_on_existing: True

    format: "ba[ext=webm]/ba"

    audio_extract:
      codec: "best"

    music_tags:
      artist: "{track_artist}"
      albumartist: "{track_album_artist}"
      title: "{track_title}"
      album: "{track_album}"
      track: "{track_number}"
      tracktotal: "{track_total}"
      year: "{track_year}"
      date: "{track_date}"
      original_date: "{track_original_date}"
      # multi-tags
      artists:
        - "{track_artist}"
      albumartists:
        - "{track_album_artist}"
      genres:
        - "{track_genre}"

    overrides:
#   MUST DEFINE:
#     music_directory

      # Defaults
      track_genre_default: "Unset"

      # Subscription overrides
      subscription_indent_1: "{track_genre_default}"
      subscription_value: ""
      url: "{subscription_value}"

      # Track Overrides
      track_title: "{title}"
      track_album: "{title}"
      track_artist: "{subscription_name}"
      track_album_artist: "{track_artist}"
      track_number: "1"
      track_number_padded: "01"
      track_total: "1"
      track_year: "{upload_year}"
      track_date: "{upload_date_standardized}"
      track_original_date: "{track_date}"
      track_genre: "{subscription_indent_1}"

      # Directory Overrides
      artist_dir: "{track_artist_sanitized}"
      album_dir: "[{track_year}] {track_album_sanitized}"
      track_file_name: "{track_number_padded} - {track_title_sanitized}.{ext}"
      track_full_path: "{artist_dir}/{album_dir}/{track_file_name}"
      album_cover_path: "{artist_dir}/{album_dir}/folder.{thumbnail_ext}"


  "Single":
    preset:
      - "_music_base"

    download:
      - url: "{url}"
        include_sibling_metadata: False
```

--------------------------------

### file_convert Configuration

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Configures video and audio file format conversion settings, including custom ffmpeg arguments.

```APIDOC
## file_convert

### Description
Converts video or audio files from one extension to another using yt-dlp or ffmpeg.

### Parameters
#### Request Body
- **convert_to** (String) - Required - Desired file type (e.g., mp4, mkv, mp3).
- **convert_with** (Optional[String]) - Optional - Tool to use: `yt-dlp` or `ffmpeg`. Defaults to `yt-dlp`.
- **enable** (Optional[OverridesFormatter]) - Optional - Toggle whether this plugin is enabled.
- **ffmpeg_post_process_args** (Optional[OverridesFormatter]) - Optional - Custom ffmpeg arguments for post-processing.

### Request Example
```yaml
file_convert:
  convert_to: "mkv"
  convert_with: "ffmpeg"
  ffmpeg_post_process_args: "-bitexact -vcodec copy"
```
```

--------------------------------

### Set match_filters

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Configures yt-dlp match-filters to determine which entries are downloaded. Use '&' for logical AND operations.

```yaml
match_filters:
  filters:
    - "age_limit<?18 & like_count>?100"
    # Other common match-filters
    # - "original_url!*=/shorts/ & !is_live"
    # - "availability=?public"
```

--------------------------------

### Configure Basic File Conversion

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Specify the desired output file type for conversion.

```yaml
file_convert:
  convert_to: "mp4"
```

--------------------------------

### Configure Media Quality and Resolution

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/guides/getting_started/subscriptions.md

Use media quality presets to control the format, quality, or resolution of downloaded media, such as highest available or specific resolutions like 720p.

```yaml
Jellyfin TV Show by Date | Only Recent:
  # Download the highest resolution available:
  Max Video Quality:
    "NOVA PBS": "https://www.youtube.com/@novapbs"
    "National Geographic": "https://www.youtube.com/@NatGeo"
  # Download the highest resolution available that is 720p or less:
  Max 720p:
    "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"

Soundcloud Discography | Chunk Downloads:
  # Only download audio using the Opus codec, not MP3 or other codecs:
  Max Opus Quality:
    "UKNOWY": "https://soundcloud.com/uknowymunich"
```

--------------------------------

### Configure ytdl-sub to Skip Existing Videos

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/faq/index.md

Set `break_on_existing` to `False` in your `ytdl_options` to prevent downloading from stopping when a video already exists. Re-enable it after the download to improve successive download speeds.

```yaml
ytdl_options:
  break_on_existing: False
```

--------------------------------

### Configure music_tags

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Adds audio metadata tags using the MediaFile package. Date fields require YYYY-MM-DD format.

```yaml
presets:
  my_example_preset:
    music_tags:
      artist: "{artist}"
      album: "{album}"
      # Supports id3v2.4 multi-tags
      genres:
        - "{genre}"
        - "ytdl-sub"
      albumartists:
        - "{artist}"
        - "ytdl-sub"
      date: "{upload_date_standardized}"
```

--------------------------------

### Configure TV Show by Date Preset

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/prebuilt_presets/tv_shows.md

Defines the base directory and organizes specific YouTube channels or playlists into a TV show structure using the Plex preset.

```yaml
__preset__:
  overrides:
    tv_show_directory: "/tv_shows"

Plex TV Show by Date:

  # Sets genre tag to "Documentaries"
  = Documentaries:
    "NOVA PBS": "https://www.youtube.com/@novapbs"
    "National Geographic": "https://www.youtube.com/@NatGeo"
    "Cosmos - What If": "https://www.youtube.com/playlist?list=PLZdXRHYAVxTJno6oFF9nLGuwXNGYHmE8U"

  # Sets genre tag to "Kids", "TV-Y" for content rating
  = Kids | = TV-Y:
    "Jake Trains": "https://www.youtube.com/@JakeTrains"
    "Kids Toys Play": "https://www.youtube.com/@KidsToysPlayChannel"

  = Music:
    # TV show subscriptions can support multiple urls and store in the same TV Show
    "Rick Beato":
      - "https://www.youtube.com/@RickBeato"
      - "https://www.youtube.com/@rickbeato240"
```

--------------------------------

### Configure Video Tags

Source: https://github.com/jmbannon/ytdl-sub/blob/master/docs/source/config_reference/plugins.md

Adds metadata tags to downloaded video files using ffmpeg.

```yaml
video_tags:
  title: "{title}"
  date: "{upload_date}"
  description: "{description}"
```