merge: subtitle.group_by track option

docs/guide/subtitles.md

@@ -134,9 +134,16 @@ flags drive selection, sort order, output filenames, and the Matroska track flag
   often uppercase with `>>>` speaker markers and sound cues.
 
 !!! note "SDH and CC are treated together for sorting and stripping"
-    Within a language, unshackle orders subtitles from fewest to most captions:
-    **Forced → Normal → SDH/CC**. For the purposes of hearing-impaired handling, SDH and
-    CC tracks are grouped as the "most captions" variant.
+    unshackle orders subtitles from fewest to most captions: **Forced → Normal → SDH/CC**.
+    For the purposes of hearing-impaired handling, SDH and CC tracks are grouped as the
+    "most captions" variant.
+
+    By default this type order is the primary sort, so all forced tracks come first, then
+    all normal tracks, then all SDH/CC tracks, each block sorted by language. To keep each
+    language next to its own variants instead, set
+    [`subtitle.group_by`](../reference/configuration.md#subtitle) to `language`. Use
+    [`subtitle.type_priority`](../reference/configuration.md#subtitle) to change the
+    Forced → Normal → SDH/CC order itself.
 
 A single track cannot be both CC and SDH, and a forced track cannot also be flagged
 CC or SDH. These combinations are rejected as invalid.

docs/reference/configuration.md

@@ -375,7 +375,8 @@ written as sidecar files. See [Subtitles](../guide/subtitles.md) for the full gu
 | `preferred_conversion_method` | str | *(unset)* | Preferred converter when several are available. |
 | `output_mode` | str | `"mux"` | `mux` embeds subtitles in the MKV; `sidecar` writes separate files; `both` writes sidecars and still muxes. |
 | `sidecar_format` | str | `"srt"` | Format for sidecar files when `output_mode: sidecar`. |
-| `type_priority` | list | *(unset)* | Ordered ranking of subtitle types (`forced`, `normal`, `sdh`; CC counts as SDH) that sorts the variants within each language. Types you leave out fall to the end. |
+| `type_priority` | list | *(unset)* | Ordered ranking of subtitle types (`forced`, `normal`, `sdh`; CC counts as SDH). Types you leave out fall to the end. |
+| `group_by` | str | `"type"` | Which key groups the subtitle tracks. `type` puts all forced tracks together, then all normal, then all SDH. `language` keeps each language next to its own variants. |
 
 ```yaml
 subtitle:
@@ -384,11 +385,30 @@ subtitle:
   sidecar_format: srt
 ```
 
+!!! note "`group_by` puts a language next to its own SDH track"
+    The default `type` order groups by subtitle type first, so every normal track comes
+    before every SDH track. In a title with many languages, a track ends up far from its
+    own SDH version, for example Finnish at track 5 and Finnish SDH at track 42. Set
+    `group_by: language` to keep them together:
+
+    ```yaml
+    subtitle:
+      group_by: language
+    ```
+
+    | `group_by` | Result |
+    |---|---|
+    | `type` | Danish, Finnish, French, … Danish SDH, Finnish SDH, French SDH |
+    | `language` | Danish, Danish SDH, Finnish, Finnish SDH, French, French SDH |
+
+    `type_priority` still sets the order of the variants, so with `group_by: language` it
+    controls the order inside each language.
+
 !!! note "`type_priority` also picks the default subtitle"
-    `type_priority` sorts the tracks within each language, and at mux time the first track
-    in the default subtitle language gets the `default` flag. The built-in order is `forced`,
-    `normal`, `sdh`, which means a forced track becomes default whenever one exists. If you
-    want the full dialogue track as default instead, set:
+    At mux time the first track in the default subtitle language gets the `default` flag.
+    The built-in order is `forced`, `normal`, `sdh`, which means a forced track becomes
+    default whenever one exists. If you want the full dialogue track as default instead,
+    set:
 
     ```yaml
     subtitle: