feat(tracks)!: match a language tag to the variant it means

A tag with a region (en-US, es-419) matches only that variant and reports a miss instead of taking another region. A bare tag takes the variant it means (pt -> pt-BR, es -> es-ES) and falls back to any variant only when that one is missing. `orig` prefers the title's own tag, `-sl orig` resolves, forced and SDH subtitles are picked from their own pools, and the track name no longer strips the region from the cached language.

BREAKING CHANGE: -l es-419 no longer selects es-ES, and language_priority, language_tags and muxing.default_language treat a regional tag as exact.
This commit is contained in:
imSp4rky
2026-10-15 12:26:39 -06:00
parent c231114cda
commit a4ce70a53c
26 changed files with 584 additions and 253 deletions
+26
View File
@@ -0,0 +1,26 @@
from __future__ import annotations
from typing import Optional
import pytest
from unshackle.core.tracks import Audio, Tracks
@pytest.mark.parametrize(
("languages", "preferred", "expected"),
[
(["en-GB", "en-US"], "en-US", 1),
# matched against every track at once, so the string-equal tag wins over a bare en
(["en", "en-US"], "en-US", 1),
(["en-GB", "fr"], "en-US", None),
(["fr", "en-GB"], "en", 1),
(["en-US"], None, None),
],
)
def test_first_match_index(languages: list[str], preferred: Optional[str], expected: Optional[int]) -> None:
tracks = [
Audio(id_=f"a{i}", url=f"https://x/{i}", language=lang, codec=Audio.Codec.AAC, bitrate=1)
for i, lang in enumerate(languages)
]
assert Tracks.first_match_index(tracks, preferred) == expected
+47 -4
View File
@@ -114,7 +114,7 @@ def test_language_grouping_still_honours_type_priority_and_sections(tracks: Trac
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
# "en" floats en-US (the variant it means) and then en-GB, and each tag keeps its variants
t = Tracks()
t.add(
[
@@ -129,11 +129,11 @@ def test_language_grouping_keeps_regional_variants_adjacent_through_sections() -
)
t.sort_subtitles(by_language=["en"], group_by="language")
assert shape(t) == [
("en-US", "normal"),
("en-US", "sdh"),
("en-GB", "forced"),
("en-GB", "normal"),
("en-GB", "sdh"),
("en-US", "normal"),
("en-US", "sdh"),
("fi", "normal"),
("fi", "sdh"),
]
@@ -172,7 +172,15 @@ def test_priority_overlapping_entries_are_harmless() -> None:
t = Tracks()
t.add([sub("ar"), sub("en-GB"), sub("en-US"), sub("es"), sub("ja")])
t.sort_subtitles(by_language=["en", "en-US", "es"], group_by="language")
assert langs(t) == ["en-GB", "en-US", "es", "ar", "ja"]
assert langs(t) == ["en-US", "en-GB", "es", "ar", "ja"]
@pytest.mark.parametrize("group_by", ["language", "type"])
def test_a_regional_priority_outranks_its_sibling(group_by: str) -> None:
t = Tracks()
t.add([sub("en-GB"), sub("en-US"), sub("fr")])
t.sort_subtitles(by_language=["en-US"], group_by=group_by)
assert langs(t) == ["en-US", "en-GB", "fr"]
def test_no_priority_leaves_order_unchanged(many: Tracks) -> None:
@@ -223,3 +231,38 @@ def test_unparseable_priority_entry_is_ignored(many: Tracks, exact: bool) -> Non
# a config typo in language_priority must not crash the sort
many.sort_subtitles(by_language=["en", "engrish", "f", ""], group_by="language", exact_match=exact)
assert langs(many) == ["en", "ar", "bg", "es", "fr", "ja"]
def test_a_bare_audio_priority_sorts_the_meant_variant_then_its_other_forms() -> None:
from unshackle.core.tracks import Audio
t = Tracks()
t.add(
[
Audio(id_=lang, url=f"https://x/{lang}", language=lang, codec=Audio.Codec.AAC, bitrate=bitrate)
for lang, bitrate in (("en", 3), ("es-419", 2), ("es-ES", 1))
]
)
t.sort_audio(by_language=["es"])
assert [str(a.language) for a in t.audio] == ["es-ES", "es-419", "en"]
def test_all_sorts_the_original_track_then_its_other_regional_forms() -> None:
from unshackle.core.tracks import Audio
t = Tracks()
t.add(
[
Audio(
id_=lang,
url=f"https://x/{lang}",
language=lang,
codec=Audio.Codec.AAC,
bitrate=bitrate,
is_original_lang=orig,
)
for lang, bitrate, orig in (("en", 3, False), ("fr-FR", 2, False), ("fr-CA", 1, True))
]
)
t.sort_audio(by_language=["all"])
assert [str(a.language) for a in t.audio] == ["fr-CA", "fr-FR", "en"]
+19
View File
@@ -0,0 +1,19 @@
from langcodes import Language
from unshackle.core.tracks import Audio, Tracks
def audio(lang: str, bitrate: int, id_: str) -> Audio:
return Audio(url=f"http://x/{id_}", id_=id_, language=lang, codec=Audio.Codec.AAC, bitrate=bitrate, channels=2.0)
def test_naming_a_track_keeps_its_region() -> None:
track = audio("fr-FR", 128000, "a1")
assert track.name is None
assert track.language.territory == "FR"
assert Language.get("fr-FR").territory == "FR"
def test_a_regional_request_picks_its_own_variant_over_a_higher_bitrate_sibling() -> None:
tracks = [audio("fr-FR", 128000, "a1"), audio("fr-CA", 192000, "a2")]
assert [str(t.language) for t in Tracks.by_language(tracks, ["fr-FR"])] == ["fr-FR"]