unshackle/docs/reference/configuration/output.md

# Output & naming { #output-naming }

Keys that control the output filename, the per-title subfolder, release-group tagging, and
filename character handling. For template cookbook material and worked naming examples, see
the [Output & naming guide](../../guide/output-and-naming.md).

## `output_template`

- **Type:** `dict`  ·  **Required** (no usable default; `dl` exits with an error if this is missing)

Filename templates keyed by media kind, using `{variable}` placeholders. Recognised kinds are
`movies`, `series`, and `songs` (and `albums` for folder templates). A trailing `?` on a
variable (e.g. `{quality?}`) marks it optional: if empty, it and one adjacent separator are
dropped.

```yaml title="unshackle.yaml"
output_template:
  movies: "{title}.{year}.{quality?}.{source}-{tag}"
  series: "{title}.{season_episode}.{episode_name?}.{quality?}.{source}-{tag}"
  songs: "{track_number}. {title}"
  folder:                       # special nested key, see below
    movies: "{title} ({year})"
    series: "{title} ({year})"
```

**The nested `folder` sub-key** controls output subfolders and is popped out of
`output_template`:

- A **dict** sets per-kind folder templates (kinds: `movies`, `series`, `songs`, `albums`).
- A **str** sets a single folder template for everything.

unshackle validates templates on load and emits warnings for unknown variables, non-string
values, filesystem-unsafe characters (`< > : " / \ | ? *`), empty templates, and unknown
folder-kind keys.

??? example "All valid template variables"
    `title`, `year`, `season`, `episode`, `season_episode`, `episode_name`, `date`,
    `quality`, `resolution`, `source`, `tag`, `track_number`, `artist`, `album_artist`,
    `album`, `disc`, `track_total`, `disc_total`, `release_type`, `genre`, `explicit`,
    `isrc`, `upc`, `label`, `audio`, `audio_channels`, `audio_full`, `atmos`, `dual`,
    `multi`, `dubbed`, `video`, `hdr`, `hfr`, `edition`, `repack`, `lang_tag`,
    `title_type`.

## Tagging & naming keys

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `tag` | str | `""` | Release-group tag. Fills the `{tag}` template variable and is written into MKV/audio tags. |
| `tag_group_name` | bool | `true` | Include the group name (`tag`) in the MKV `Group` tag. |
| `tag_imdb_tmdb` | bool | `true` | Write IMDb/TMDB/TVDB external-ID tags into the MKV (needs metadata providers). |
| `chapter_fallback_name` | str | `""` | Fallback chapter-name template, e.g. `"Chapter {i:02}"`. |
| `unicode_filenames` | bool | `false` | Allow Unicode in filenames; when `false`, names are ASCII-sanitised. |

## `tag_rules`

- **Type:** `list` &nbsp;·&nbsp; **Default:** `[]`

Conditionally replaces [`tag`](#tagging-naming-keys) for a given download. Each rule pairs a `when`
dict of conditions with the `tag` to use when they hold. Rules are evaluated in order and the
first match wins; if no rule matches, the global `tag` is kept.

```yaml title="unshackle.yaml"
tag_rules:
  - when: { title_type: movie, lang_tag: SUBBED }
    tag: SUBMOVIES
  - when: { quality: 2160p, hdr: [DV, DV.HDR, DV.HDR10P, HDR, HDR10P] }
    tag: UHDGROUP
```

Rule semantics:

- Every condition in `when` must hold (they are AND-ed).
- A value may be a scalar or a list; a list matches if **any** entry matches.
- Comparison is case-insensitive string equality.
- The keys of `when` are the filename template variables that describe the release itself:
  `title_type`, `quality`, `resolution`, `source`, `video`, `hdr`, `hfr`, `audio`,
  `audio_channels`, `audio_full`, `atmos`, `dual`, `multi`, `dubbed`, `edition`, `repack`,
  and `lang_tag`. Only these are available. The title's own fields (`title`, `year`, `season`,
  `episode`, and so on) are added after the rules run and cannot be matched.
- An unknown key in `when` is a mistake: unshackle logs a warning that names the key and skips
  that rule. A rule without conditions or without a `tag` is also warned about and skipped.

Put the more specific rules first, because the first match ends the search.

!!! warning "Match `hdr` on the exact value"
    Matching is exact, and `hdr` is a composite label for Dolby Vision titles: a DV title with
    an HDR10 base layer gives `DV.HDR`, and with an HDR10+ base layer `DV.HDR10P`. Plain `DV`
    does **not** match those. List every variant you want, as the example above does. Note
    also that HDR10 gives `HDR`, not `HDR10`. The full set of values is `HDR`, `HDR10P`, `DV`,
    `DV.HDR`, `DV.HDR10P`, and `HLG`, as listed in the
    [variable table](../../guide/output-and-naming.md#template-variables).

### Operators

A condition value may start with a comparison operator, which is applied to the rest of the
value:

```yaml title="unshackle.yaml"
tag_rules:
  - when: { resolution: "<1080" }
    tag: SDGROUP
  - when: { quality: ">=2160" }
    tag: UHDGROUP
  - when: { video: "!=H.265" }
    tag: AVCGROUP
```

- `>`, `<`, `>=`, `<=` compare numbers. unshackle reads the first number out of the actual
  value, so `">=2160"` matches a quality of `2160p`. If the actual value has no number, the
  condition fails.
- `=`, `==`, and `!=` compare text, case-insensitively, when the operand is not a number.
  With a numeric operand they compare numbers like the operators above. A value with no number
  in it is never equal to a number, so `"!=2160"` holds for it and `"==2160"` does not.
- An ordering operator with a text operand (for example `">DV"`) is a mistake: unshackle logs
  a warning and the condition fails. So does an operator with nothing after it (`">="`).
- A value with no operator keeps the plain equality behaviour described above.

!!! warning "Quote operator values in YAML"
    Two of these operators break an unquoted YAML value, and both stop the config from
    loading:

    - `>` opens a folded block scalar, so `quality: >=2160` fails with a "while scanning a
      block scalar" error.
    - `!` starts a tag, so `hdr: !=DV` fails with a "could not determine a constructor"
      error.

    Quote every operator value: `quality: ">=2160"`, `resolution: "<1080"`, `video: "!=H.265"`.

!!! note "Keep a negation out of lists"
    A list matches if any entry matches, so two or more `!=` entries in one list are always
    true. Give a negation as a single value, not as a list entry.

`title_type` is the media kind of the title: `movie`, `series`, or `music`. It is useful to
give each kind its own group:

```yaml
tag_rules:
  - when: { title_type: movie }
    tag: MOVIEGRP
  - when: { title_type: series }
    tag: TVGRP
```

The resolved tag applies to the `{tag}` filename variable only. The `Group` metadata tag
written into MKV and music files always uses [`tag`](#tagging-naming-keys).

!!! note "`--tag` wins"
    An explicit `dl --tag` on the command line disables the rules completely and uses the
    given tag.