feat(dl): add tag_rules to conditionally swap the group tag

docs/reference/configuration.md

@@ -35,7 +35,7 @@ This page assumes you already know the basics and want precise details.
 | [Directories](#directories) | `directories`, `filenames` |
 | [Services & authentication](#services-auth) | `services`, `credentials`, `firefox_cookies`, `remote_services`, `serve` |
 | [Download & processing](#download-processing) | `dl`, `subtitle`, `audio`, `muxing`, `language_tags`, `dual_multi_mode` |
-| [Output & naming](#output-naming) | `output_template`, `tag`, `tag_group_name`, `tag_imdb_tmdb`, `chapter_fallback_name`, `unicode_filenames` |
+| [Output & naming](#output-naming) | `output_template`, `tag`, `tag_rules`, `tag_group_name`, `tag_imdb_tmdb`, `chapter_fallback_name`, `unicode_filenames` |
 | [DRM & CDM](#drm-cdm) | `cdm`, `remote_cdm`, `decryption` |
 | [Network & proxy](#network-proxy) | `network`, `headers`, `proxy_providers` |
 | [Key vaults](#key-vaults) | `key_vaults`, `vault_timeout` |
@@ -584,7 +584,8 @@ folder-kind keys.
     `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`.
+    `multi`, `dubbed`, `video`, `hdr`, `hfr`, `edition`, `repack`, `lang_tag`,
+    `title_type`.
 
 ### Tagging & naming keys
 
@@ -596,6 +597,103 @@ folder-kind keys.
 | `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`  ·  **Default:** `[]`
+
+Conditionally replaces [`tag`](#output-naming) 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`](#output-naming).
+
+!!! note "`--tag` wins"
+    An explicit `dl --tag` on the command line disables the rules completely and uses the
+    given tag.
+
 ---
 
 ## DRM & CDM { #drm-cdm }