Preferred audio/subtitle language matching does not normalize BCP-47 region and script tags

[alsoeoe]

What should the engine do?

Normalize BCP-47 region and script tags when resolving preferredAudioLanguages,
preferredSubtitleLanguages, and nativeSubtitlePreferredLanguages, while preserving the
distinctions that matter to each track kind.

This should stay entirely on the structured language field. The engine should not infer a
language from a track title or sidecar filename.

Current behaviour

The public external-subtitle descriptor documents ExternalSubtitleTrack.language as accepting
“BCP-47 / ISO 639”, but the preference path ultimately reaches languageMatches, which currently
does case-insensitive exact comparison plus fixed ISO/name synonym sets.

That leaves common structured tags unmatched:

preference   track language   current result
en           en-US            no match
en-US        eng              no match
ar-SA        ara              no match
zh-Hant      zh-TW            no match
zh-Hans      zh-CN            no match

The same matcher is shared by the first-frame audio pick and post-load subtitle pick. The native
subtitle DEFAULT ordinal also calls it directly, so the host-overlay and native/PiP paths can make
the same miss independently.

This is a follow-up to #73 rather than a request for host-side compensation. main at
b1b3c2add9d535739a1e450db05d2979906ff3c9 still has this behaviour; the downstream integration is
pinned to 7.10.0 (ca8512cd579b770d96dec8cea23507a5bb81128a).

Proposed matching semantics

Keep preference-array order as the outer priority, but rank matches within one preference:

Common normalization

• Treat ISO 639-1, ISO 639-2/B, ISO 639-2/T and a well-formed BCP-47 primary subtag as the same
  language identity where they are equivalents.
• Exact normalized BCP-47 identity wins over a same-language fallback.
• Nil, empty, und, free-form names and unrecognized labels remain non-matches.
• Do not parse TrackInfo.name, ExternalSubtitleTrack.name, or filenames.

Audio

• Prefer an exact full tag, then fall back to the same canonical language when only the region
  differs or one side carries no region (en-GB > en/eng > another en-* candidate for an
  en-GB preference).
• Do not collapse distinct language identities merely because they are related: for example yue
  and nan must not become generic zh. A generic macrolanguage fallback, if supported, should be
  weaker than an exact language match.

Subtitles

• Prefer an exact tag/script, then the same explicit script, then an unspecified-script track of
  the same language.
• A track with an explicitly opposite script is not a fallback.
• For Chinese subtitle tags, explicit region can carry the script distinction used by media
  servers and sidecar naming: zh-CN / zh-SG are Simplified and zh-TW / zh-HK / zh-MO are
  Traditional, equivalent to zh-Hans and zh-Hant respectively.
• Bare zh / chi / zho is script-unspecified. It may be a weaker fallback for either preference,
  but must not be treated as explicitly Simplified.
• Language specificity should rank before the existing subtitlePickRank; the existing
  full > SDH > forced > commentary and text > bitmap ranking then resolves tracks at equal language
  specificity.

One implementation trap: Locale.Language(identifier: "zh").script currently infers Hans on
Apple platforms. Using that inferred script directly would turn an unspecified zh track into an
explicit Simplified track. Script specificity therefore needs to come from an explicit script
subtag or an agreed explicit-region mapping, not from likely-subtags expansion of a bare language.

Reproduction / acceptance examples

Pure selection tests should be sufficient; no media fixture or decoder path is involved.

// Audio: exact region beats a generic/same-language fallback even when it is later in track order.
preferredAudioLanguages = ["en-GB"]
tracks = ["en-US", "eng", "en-GB"]
// expected: en-GB

// Subtitle: explicit matching script wins; generic is fallback; opposite script is rejected.
preferredSubtitleLanguages = ["zh-Hant"]
tracks = ["zh-CN", "zho", "zh-TW"]
// expected: zh-TW

preferredSubtitleLanguages = ["zh-Hant"]
tracks = ["zh-CN", "zho"]
// expected: zho

preferredSubtitleLanguages = ["zh-Hant"]
tracks = ["zh-CN"]
// expected: nil (subtitles stay off)

The same BCP-47 resolution should choose the DEFAULT rendition for
nativeSubtitlePreferredLanguages, so inline and PiP/AirPlay do not disagree.

Why this belongs in the engine

The engine already owns preference-order resolution, subtitle descriptor ranking, external-track
registration, and native rendition default selection. Reproducing ISO aliases and match ranking in
each host makes those paths drift, especially when external subtitles are added by media servers or
future download providers.

There is already robust BCP-47/ISO normalization work in AudioLanguageMap for emitted HLS/fMP4
metadata, but that helper intentionally collapses region/script to an ISO 639-2/T code. The selection
path needs to retain enough explicit-tag information to rank region/script before falling back.

Area

Public API behaviour / audio / subtitles

Host app / integration context

Custom iOS media client using structured Emby sidecar metadata today, with provider-neutral
downloaded subtitle tracks planned. The host wants to pass metadata into Aether and rely on the
engine's existing selection APIs rather than maintain a second matcher.

Would you be willing to open a PR?

Maybe, with guidance on the generic-language fallback and whether audio and subtitle matching should
share one ranked representation or two policies over a common parser.

[superuser404notfound]

Thanks, this is an unusually precise report: the five unmatched rows, the right layer, the implementation trap, and acceptance examples that are pure selection. Built and pushed as #593 (a0a139d).

Answering the two questions that were open, since they shaped the implementation.

One ranked representation, not two policies. Audio and subtitles turned out to differ in exactly one place, so a shared parser with a kind parameter carries the whole difference: a subtitle track whose script is explicitly opposite is no answer at all, while for audio the same mismatch only ranks last, because nothing about audio fails to be readable. Everything else, canonical identity and the script/region scoring, is one code path. Two policies would have put the identity and region axes in two places, which is the drift the report describes for hosts.

No generic macrolanguage fallback. It turned out not to be needed for the case it was proposed for. Identity resolves through the engine's existing AudioLanguageMap, which canonicalizes CLDR's macrolanguage aliases, so cmn folds onto zh as an identity rather than a fallback, while yue and nan stay their own languages because CLDR does not alias them. That is exactly the line the report drew. A weak tier below that would only ever fire where the answer is genuinely ambiguous, and serving Cantonese audio to a Mandarin preference is worse than serving the container default. It can be added later if a real library turns up that needs it; it cannot be removed later.

That same helper also decides what counts as a language at all. It fails closed on free text, which is what keeps und, a track title and a label like dub out of the language axis without a second gate.

On the ICU trap: confirmed, and it is broader than zh. Locale.Language.script is likely-subtags expansion for every language ICU knows, measured on macOS 27:

tag	.script
zh	Hans
en	Latn
ara	Arab
nan	Hans
yue	Hant

So it is unusable as a specificity signal anywhere, not only for the Chinese pair, and nan would have become explicitly Simplified. Script is read from the tag's own subtags by shape instead, with the zh-CN/zh-SG and zh-TW/zh-HK/zh-MO region mapping applied only to Chinese.

Two side findings worth naming, because they confirm the diagnosis from inside the engine. nativeOptionIndex and the audible-selection readback each split the primary subtag off by hand before calling the matcher, precisely because the matcher could not see past one. That is the same gap compensated for twice, and both now pass the full tag. And the gap reached a shipping host: a pt-BR track missed a bare pt preference, since the old table had pt-br and pt in different synonym sets.

The four acceptance examples are in as tests verbatim, alongside a regression asserting every pair the old table matched still matches. The native DEFAULT=YES ordinal and the overlay pick now run through the same ranked resolution, so inline and PiP/AirPlay resolve identically.

Leaving this open for confirmation against the real Emby sidecar metadata rather than closing it on my own tests. The matching internals are module-internal for now; if a second matcher is wanted host-side after all, say so and the rank function can be made public with the ranking documented as API.

[superuser404notfound]

Released in 7.11.0 (c829c62).

Both consumers are on it. Leaving the thread open until this is confirmed against the real sidecar metadata rather than closing it on my own tests.

https://github.com/superuser404notfound/AetherEngine/releases/tag/7.11.0