feat(tracks): add subtitle.group_by to keep a language with its variants

sort_subtitles applied the language sort before the type sort. Python sorts
are stable, so the last pass wins and type became the major key: every forced
track, then every normal, then every SDH, each block ordered by language. In a
title with many languages this put a track far from its own SDH version, for
example Finnish at track 5 and Finnish SDH at track 42.

Add a group_by parameter that selects the major key. "type" is the default and
keeps the current order byte for byte. "language" swaps the two passes so each
language stays next to its own variants. Read it from the new subtitle.group_by
config key.

Also correct the docs: type_priority was described as sorting the variants
within each language, which was never true. It ranks the types across all
languages.
This commit is contained in:
imSp4rky
2026-08-02 10:45:28 -06:00
parent bf85c948b4
commit 8baf064750
5 changed files with 141 additions and 24 deletions
+69
View File
@@ -66,3 +66,72 @@ def test_cc_counts_as_sdh() -> None:
t.add([sub("en", cc=True), sub("en")])
t.sort_subtitles(by_language=["en"], type_priority=["normal", "sdh"])
assert shape(t) == [("en", "normal"), ("en", "sdh")]
@pytest.fixture
def unprioritised() -> Tracks:
"""Languages that no by_language argument floats to the top."""
t = Tracks()
t.add([sub("fi", sdh=True), sub("fi"), sub("de", sdh=True), sub("de")])
return t
def test_type_grouping_separates_a_language_from_its_sdh(unprioritised: Tracks) -> None:
unprioritised.sort_subtitles()
assert shape(unprioritised) == [
("de", "normal"),
("fi", "normal"),
("de", "sdh"),
("fi", "sdh"),
]
def test_language_grouping_keeps_a_language_with_its_sdh(unprioritised: Tracks) -> None:
unprioritised.sort_subtitles(group_by="language")
assert shape(unprioritised) == [
("de", "normal"),
("de", "sdh"),
("fi", "normal"),
("fi", "sdh"),
]
def test_language_grouping_still_honours_type_priority_and_sections(tracks: Tracks) -> None:
# de sits outside by_language, where type-major sorting would interleave it with en
tracks.add([sub("de"), sub("de", sdh=True)])
tracks.sort_subtitles(by_language=["it"], type_priority=["normal", "sdh", "forced"], group_by="language")
assert shape(tracks) == [
("it", "normal"),
("it", "forced"),
("de", "normal"),
("de", "sdh"),
("en", "normal"),
("en", "sdh"),
("en", "forced"),
]
def test_language_grouping_keeps_regional_variants_adjacent_through_sections() -> None:
# "en" floats en-GB and en-US as one block, so each exact tag keeps its variants
t = Tracks()
t.add(
[
sub("en-US", sdh=True),
sub("fi"),
sub("en-GB"),
sub("en-US"),
sub("fi", sdh=True),
sub("en-GB", forced=True),
sub("en-GB", sdh=True),
]
)
t.sort_subtitles(by_language=["en"], group_by="language")
assert shape(t) == [
("en-GB", "forced"),
("en-GB", "normal"),
("en-GB", "sdh"),
("en-US", "normal"),
("en-US", "sdh"),
("fi", "normal"),
("fi", "sdh"),
]