feat(engine): rank subtitle-language pick by disposition, surface forced/SDH/commentary on TrackInfo (#73)

LoadOptions.preferredSubtitleLanguages (4.4.0) picked the first track in a matching language. It now picks
the best track within the first matching preference: full subtitles rank over SDH / forced / commentary
(from container dispositions) and text over bitmap. New TrackInfo.isForced / isHearingImpaired /
isCommentary surface those dispositions (read alongside the existing isDefault) so hosts can rank or filter
subtitleTracks the same way; pure selectSubtitleIndex + subtitlePickRank + isBitmapSubtitleCodec are exposed
and unit-tested.

Also fixes a pre-existing bitmap-classification bug in the native-subtitle rendition (#55): two sites
matched TrackInfo.codec (the libavcodec DECODER name, e.g. pgssub) against an exact-match Set of DESCRIPTOR
names (hdmv_pgs_subtitle, ...), so PGS / DVB / DVD bitmap tracks leaked into the mov_text trak table and the
store-attach set (only xsub matched by luck), producing phantom native-menu entries and a store/reader index
mismatch when prepareNativeSubtitles was set. Both sites now use the shared decoder-name isBitmapSubtitleCodec
classifier, matching the reader's enum classifier.

193 tests green.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01B4hBXf5yHPUNxQsDavBKGk

Author: superuser404notfound

Sources/AetherEngine/AetherEngine+Loading.swift

@@ -249,12 +249,10 @@ extension AetherEngine {
             }
         }
         // prepareNativeSubtitles + non-bitmap text tracks: flag gates allocateMuxer SubtitleConfig; must be set before start() (#55).
-        // TrackInfo.codec is the lower-case libavcodec name (e.g. "subrip", "ass"). Bitmap codecs excluded:
-        let bitmapCodecNames: Set<String> = [
-            "hdmv_pgs_subtitle", "dvb_subtitle", "dvd_subtitle", "xsub"
-        ]
         // Each text track becomes one mov_text track in the init moov (#55, all-tracks). Sidecar entries append at runtime; this table is embedded-only.
-        let textTracks = subtitleTracks.filter { !bitmapCodecNames.contains($0.codec) }
+        // Bitmap codecs excluded via the shared decoder-name classifier (a prior exact-match Set used descriptor
+        // names that never matched TrackInfo.codec's decoder names, so PGS/DVB/DVD leaked in as mov_text).
+        let textTracks = subtitleTracks.filter { !Self.isBitmapSubtitleCodec($0.codec) }
         nativeSubtitleTrackTable = textTracks.map { track in
             NativeSubtitleTrackEntry(sourceStreamIndex: track.id, language: track.language)
         }

Sources/AetherEngine/AetherEngine+Probe.swift

@@ -258,23 +258,55 @@ extension AetherEngine {
         return nil
     }
 
-    /// Resolve the subtitle track to auto-activate from `LoadOptions.preferredSubtitleLanguages`: the first
-    /// track whose language matches a preference (preferences scanned in order), else nil. Unlike audio there
-    /// is no explicit index override and no default fallback: nil means "keep subtitles off" (the default).
-    /// Pure and nonisolated; the engine calls this at the end of a successful load and, on a hit, activates
-    /// the track via the host-overlay path so the host need not language-match `subtitleTracks` itself (#73).
+    /// Resolve the subtitle track to auto-activate from `LoadOptions.preferredSubtitleLanguages`: within the
+    /// first preference (scanned in order) that has any language match, the best-ranked track by
+    /// `subtitlePickRank`; else nil. Preference order dominates rank, so an earlier preference always beats a
+    /// later one. Unlike audio there is no explicit index override and no default fallback: nil means "keep
+    /// subtitles off" (the default). Pure and nonisolated; the engine calls this at the end of a successful
+    /// load and, on a hit, activates the track via the host-overlay path so a host without container metadata
+    /// of its own need not language-match and rank `subtitleTracks` itself (#73).
     nonisolated static func selectSubtitleIndex(
         tracks: [TrackInfo],
         preferredLanguages: [String]
     ) -> Int32? {
         for preferred in preferredLanguages {
-            if let match = tracks.first(where: { languageMatches($0.language, preferred) }) {
-                return Int32(match.id)
+            let matches = tracks.filter { languageMatches($0.language, preferred) }
+            // min(by:) is stable, so equal-rank ties keep container order.
+            if let best = matches.min(by: { subtitlePickRank($0) < subtitlePickRank($1) }) {
+                return Int32(best.id)
             }
         }
         return nil
     }
 
+    /// Lower rank wins. The descriptor axis (full > SDH > forced > commentary, from container dispositions)
+    /// dominates; text-vs-bitmap is a tiebreaker (text preferred, since host styling only applies to text
+    /// cues). Sourced from `TrackInfo` disposition flags rather than title strings, so it is locale-robust.
+    /// Used by `selectSubtitleIndex` and exposed so a host can rank `subtitleTracks` the same way (#73).
+    nonisolated static func subtitlePickRank(_ track: TrackInfo) -> Int {
+        let descriptorRank: Int
+        if track.isCommentary {
+            descriptorRank = 3
+        } else if track.isForced {
+            descriptorRank = 2
+        } else if track.isHearingImpaired {
+            descriptorRank = 1
+        } else {
+            descriptorRank = 0
+        }
+        return descriptorRank * 2 + (isBitmapSubtitleCodec(track.codec) ? 1 : 0)
+    }
+
+    /// True when the codec is a bitmap (image) subtitle. `TrackInfo.codec` is the libavcodec DECODER name
+    /// (pgssub / dvdsub / dvbsub / xsub), not the descriptor name (hdmv_pgs_subtitle / dvb_subtitle / ...);
+    /// matched case-insensitively by substring so either form is tolerated. Bitmap subs cannot mux into
+    /// mov_text, so the native-subtitle rendition (#55) excludes them and only the host overlay renders them.
+    nonisolated static func isBitmapSubtitleCodec(_ codec: String) -> Bool {
+        let c = codec.lowercased()
+        return ["pgs", "hdmv", "dvb_sub", "dvbsub", "dvd_sub", "dvdsub", "vobsub", "xsub"]
+            .contains(where: { c.contains($0) })
+    }
+
     /// Case-insensitive language match across ISO 639-1 / 639-2 (B and T) / English name, e.g.
     /// `"en" == "eng" == "english"`, `"de" == "deu" == "ger"`. Empty / nil track language never matches.
     /// Shared by audio (#72) and subtitle (#73) language selection. Pure and unit-tested.

Sources/AetherEngine/AetherEngine+Subtitles.swift

@@ -74,9 +74,10 @@ extension AetherEngine {
         startEmbeddedSubtitleTask(url: url, reader: customClone, formatHint: customFormatHint, streamIndex: Int32(index), startAt: startAt)
     }
 
-    /// Apply `LoadOptions.preferredSubtitleLanguages` at the end of a successful load: activate the first
-    /// subtitle track whose language matches a preference (scanned in order), else leave subtitles off (the
-    /// default). Uses the host-overlay path (equivalent to a `selectSubtitleTrack` call); `startAnchor` is the
+    /// Apply `LoadOptions.preferredSubtitleLanguages` at the end of a successful load: activate the best-ranked
+    /// subtitle track whose language matches a preference (scanned in order; see `selectSubtitleIndex`), else
+    /// leave subtitles off (the default). Uses the host-overlay path (equivalent to a `selectSubtitleTrack`
+    /// call); `startAnchor` is the
     /// load's resume position so a mid-file resume seeks the side demuxer to the playhead instead of byte 0.
     /// A no-op when the list is empty, no track matches, or the host already activated a subtitle. The resolved
     /// index is published via `activeSubtitleTrackIndex`. Independent of `prepareNativeSubtitles`. (#73)

Sources/AetherEngine/Demuxer/Demuxer.swift

@@ -416,7 +416,11 @@ public final class Demuxer: @unchecked Sendable {
             name = "Track \(index) (\(codecName))"
         }
 
-        let isDefault = (stream.pointee.disposition & AV_DISPOSITION_DEFAULT) != 0
+        let disposition = stream.pointee.disposition
+        let isDefault = (disposition & AV_DISPOSITION_DEFAULT) != 0
+        let isForced = (disposition & AV_DISPOSITION_FORCED) != 0
+        let isHearingImpaired = (disposition & AV_DISPOSITION_HEARING_IMPAIRED) != 0
+        let isCommentary = (disposition & AV_DISPOSITION_COMMENT) != 0
         let channels = Int(codecpar.pointee.ch_layout.nb_channels)
 
         // EAC3 profile 30 = JOC (Dolby Atmos on streaming). Lets UI label "Atmos".
@@ -444,6 +448,9 @@ public final class Demuxer: @unchecked Sendable {
             language: language,
             channels: channels,
             isDefault: isDefault,
+            isForced: isForced,
+            isHearingImpaired: isHearingImpaired,
+            isCommentary: isCommentary,
             isAtmos: isAtmos,
             assHeader: assHeader
         )

Sources/AetherEngine/PlayerState.swift

@@ -98,9 +98,11 @@ public struct LoadOptions: Sendable, Equatable {
     public var preferredAudioLanguages: [String]
 
     /// Ordered subtitle-language preference (ISO 639-1 / 639-2 codes or English names, e.g. `["en", "de"]`).
-    /// When non-empty, at the end of a successful load the engine activates the first subtitle track whose
+    /// When non-empty, at the end of a successful load the engine activates the best subtitle track whose
     /// language matches a preference (preferences scanned in order, case-insensitive, ISO 639-1/2 B+T and
-    /// English-name synonyms); no match leaves subtitles OFF (the default). This drives the host-overlay
+    /// English-name synonyms; within the matched preference, full subtitles rank over SDH / forced /
+    /// commentary and text over bitmap, from container dispositions); no match leaves subtitles OFF (the
+    /// default). This drives the host-overlay
     /// path (`subtitleCues`, equivalent to a `selectSubtitleTrack` call) and publishes the resolved track
     /// via `activeSubtitleTrackIndex`. Where `preferredAudioLanguages` saves a real cost (its track is muxed
     /// into the loopback HLS at the first frame, so a late pick forces a pre-probe or reload), this is pure
@@ -276,19 +278,29 @@ public struct TrackInfo: Identifiable, Sendable, Equatable {
     /// 2=stereo, 6=5.1, 8=7.1. 0 for non-audio.
     public let channels: Int
     public let isDefault: Bool
+    /// Container disposition `FORCED` (subtitles meant to show without the user enabling subtitles, e.g.
+    /// foreign-dialogue or signs tracks). Drives the subtitle-language ranking in `selectSubtitleIndex`.
+    public let isForced: Bool
+    /// Container disposition `HEARING_IMPAIRED` (SDH / closed-caption tracks with sound descriptions).
+    public let isHearingImpaired: Bool
+    /// Container disposition `COMMENT` (director / cast commentary tracks). Applies to audio and subtitle.
+    public let isCommentary: Bool
     /// EAC3 with JOC profile (Dolby Atmos). Lets the UI surface "Atmos" instead of the bed channel count (typically 5.1).
     public let isAtmos: Bool
 
     /// ASS / SSA tracks only: `[Script Info]` + `[V4+ Styles]` + `[Events]` format line from codec extradata. Hosts rendering ASS styling themselves (see `LoadOptions.preserveASSMarkup`) need it to resolve style references. nil for all other track kinds.
     public let assHeader: String?
 
-    public init(id: Int, name: String, codec: String, language: String?, channels: Int = 0, isDefault: Bool, isAtmos: Bool = false, assHeader: String? = nil) {
+    public init(id: Int, name: String, codec: String, language: String?, channels: Int = 0, isDefault: Bool, isForced: Bool = false, isHearingImpaired: Bool = false, isCommentary: Bool = false, isAtmos: Bool = false, assHeader: String? = nil) {
         self.id = id
         self.name = name
         self.codec = codec
         self.language = language
         self.channels = channels
         self.isDefault = isDefault
+        self.isForced = isForced
+        self.isHearingImpaired = isHearingImpaired
+        self.isCommentary = isCommentary
         self.isAtmos = isAtmos
         self.assHeader = assHeader
     }

Sources/AetherEngine/Video/HLSVideoEngine.swift

@@ -132,8 +132,9 @@ public final class HLSVideoEngine: @unchecked Sendable {
     /// Call after `start()`. Returns per-track languages for logging.
     @discardableResult
     public func attachAllNativeSubtitleStores() -> [String?] {
-        let bitmap: Set<String> = ["hdmv_pgs_subtitle", "dvb_subtitle", "dvd_subtitle", "xsub"]
-        let text = (demuxer?.subtitleTrackInfos() ?? []).filter { !bitmap.contains($0.codec) }
+        // Decoder-name classifier: an exact-match Set of descriptor names here never matched TrackInfo.codec
+        // (the libavcodec decoder name), so bitmap tracks leaked into the native mov_text store set.
+        let text = (demuxer?.subtitleTrackInfos() ?? []).filter { !AetherEngine.isBitmapSubtitleCodec($0.codec) }
         let languages = text.map { $0.language }
         attachNativeSubtitleStores(count: text.count, languages: languages)
         return languages

Tests/AetherEngineTests/SubtitleLanguageSelectionTests.swift

@@ -9,8 +9,10 @@ import Foundation
 /// resolution in isolation.
 struct SubtitleLanguageSelectionTests {
 
-    private func track(_ id: Int, _ lang: String?) -> TrackInfo {
-        TrackInfo(id: id, name: "s\(id)", codec: "subrip", language: lang, channels: 0, isDefault: false)
+    private func track(_ id: Int, _ lang: String?, codec: String = "subrip",
+                       forced: Bool = false, sdh: Bool = false, commentary: Bool = false) -> TrackInfo {
+        TrackInfo(id: id, name: "s\(id)", codec: codec, language: lang, channels: 0,
+                  isDefault: false, isForced: forced, isHearingImpaired: sdh, isCommentary: commentary)
     }
 
     @Test("first matching preference selects its track")
@@ -67,4 +69,59 @@ struct SubtitleLanguageSelectionTests {
         #expect(AetherEngine.selectSubtitleIndex(
             tracks: tracks, preferredLanguages: ["en"]) == nil)
     }
+
+    @Test("within a language, a full track beats forced / SDH / commentary")
+    func fullBeatsDescriptors() {
+        // Full track is last, so this also proves rank beats container order within the matched language.
+        let forced = [track(0, "en", forced: true), track(1, "en")]
+        #expect(AetherEngine.selectSubtitleIndex(tracks: forced, preferredLanguages: ["en"]) == 1)
+        let sdh = [track(0, "en", sdh: true), track(1, "en")]
+        #expect(AetherEngine.selectSubtitleIndex(tracks: sdh, preferredLanguages: ["en"]) == 1)
+        let commentary = [track(0, "en", commentary: true), track(1, "en")]
+        #expect(AetherEngine.selectSubtitleIndex(tracks: commentary, preferredLanguages: ["en"]) == 1)
+    }
+
+    @Test("descriptor ranking is full > SDH > forced > commentary")
+    func descriptorOrdering() {
+        #expect(AetherEngine.subtitlePickRank(track(0, "en")) <
+                AetherEngine.subtitlePickRank(track(1, "en", sdh: true)))
+        #expect(AetherEngine.subtitlePickRank(track(0, "en", sdh: true)) <
+                AetherEngine.subtitlePickRank(track(1, "en", forced: true)))
+        #expect(AetherEngine.subtitlePickRank(track(0, "en", forced: true)) <
+                AetherEngine.subtitlePickRank(track(1, "en", commentary: true)))
+    }
+
+    @Test("at equal descriptor rank, text beats bitmap")
+    func textBeatsBitmap() {
+        let tracks = [track(0, "en", codec: "hdmv_pgs_subtitle"), track(1, "en", codec: "subrip")]
+        #expect(AetherEngine.selectSubtitleIndex(tracks: tracks, preferredLanguages: ["en"]) == 1)
+        // But a full bitmap still beats a forced text track (descriptor dominates the codec tiebreaker).
+        let mixed = [track(0, "en", codec: "subrip", forced: true), track(1, "en", codec: "hdmv_pgs_subtitle")]
+        #expect(AetherEngine.selectSubtitleIndex(tracks: mixed, preferredLanguages: ["en"]) == 1)
+    }
+
+    @Test("preference order dominates rank")
+    func preferenceOrderDominatesRank() {
+        // en is only available forced; de is a full track. en is the earlier preference, so en wins
+        // despite ranking lower, because preference order is the outer loop.
+        let tracks = [track(0, "en", forced: true), track(1, "de")]
+        #expect(AetherEngine.selectSubtitleIndex(
+            tracks: tracks, preferredLanguages: ["en", "de"]) == 0)
+    }
+
+    @Test("bitmap classification matches libavcodec DECODER names, not descriptor names")
+    func bitmapCodecClassification() {
+        // TrackInfo.codec carries the decoder name; these are what the demuxer actually emits.
+        for c in ["pgssub", "dvdsub", "dvbsub", "xsub", "PGSSUB"] {
+            #expect(AetherEngine.isBitmapSubtitleCodec(c), "\(c) should be bitmap")
+        }
+        // Descriptor-style names are tolerated defensively.
+        for c in ["hdmv_pgs_subtitle", "dvb_subtitle", "dvd_subtitle"] {
+            #expect(AetherEngine.isBitmapSubtitleCodec(c), "\(c) should be bitmap")
+        }
+        // Text codecs are never bitmap.
+        for c in ["subrip", "srt", "ass", "ssa", "mov_text", "webvtt", "text"] {
+            #expect(!AetherEngine.isBitmapSubtitleCodec(c), "\(c) should not be bitmap")
+        }
+    }
 }

docs/formats.md

@@ -70,6 +70,15 @@ Subtitle packets are routed through the same demux loop as audio and video. No s
 - **Bitmap codecs** (PGS / HDMV PGS / DVB / DVD) → `.image(SubtitleImage)`. The indexed pixel plane is walked through its palette, premultiplied against alpha, and wrapped as a `CGImage`. Position is normalised in `[0..1]` against the source video frame so the host scales to any on-screen rect.
 - **Sidecar files** (a separate `.srt` / `.ass` / `.vtt` URL) → `selectSidecarSubtitle(url:httpHeaders:)` opens its own short-lived `AVFormatContext`, decodes the whole file once, atomically swaps the result into `subtitleCues`. The fetch forwards the session's `LoadOptions.httpHeaders` by default (WebDAV auth and friends); pass the call's own `httpHeaders` to override per fetch.
 
+### Track selection by language preference
+
+`LoadOptions` can seed the initial audio and subtitle tracks from an ordered language preference, resolved from the engine's single probe so a host honors a saved preference without a separate pre-probe or a post-load reload:
+
+- **`preferredAudioLanguages`** (ordered ISO 639-1 / 639-2 codes or English names, e.g. `["en", "de"]`) picks the first-frame audio track: an explicit `audioSourceStreamIndex` wins, else the first track matching a preference in order, else the container default. The pick is muxed into the loopback HLS, so it is correct on the first frame with no `selectAudioTrack` reload.
+- **`preferredSubtitleLanguages`** activates a subtitle at the end of load. Within the first preference that has a match, it picks the *best* track by container disposition: full subtitles rank over SDH (`HEARING_IMPAIRED`), forced, and commentary (`COMMENT`), and text over bitmap. No match leaves subtitles off. It drives the host-overlay path, so unlike audio it needs no reload regardless; it only spares a host from language-matching `subtitleTracks` itself. The native menu (below) keeps its own host-driven default selection via `setNativeSubtitleSelected(track:)`.
+
+Matching is case-insensitive across ISO 639-1, 639-2/B, 639-2/T, and English names (`en` == `eng` == `english`); preference order dominates, so an earlier preference on a later track still wins. The resolved tracks are published on `player.activeAudioTrackIndex` / `player.activeSubtitleTrackIndex` (both match `TrackInfo.id`), and every `TrackInfo` carries `isDefault` / `isForced` / `isHearingImpaired` / `isCommentary` (from container dispositions) so a host can rank or filter the track lists the same way.
+
 ### Second simultaneous subtitle track (bilingual)
 
 A second subtitle channel can run alongside the primary for bilingual playback / language learning: `selectSecondarySubtitleTrack(index:)` for an embedded track and `selectSecondarySidecarSubtitle(url:httpHeaders:)` for a sidecar file, mirroring the primary API. Its cues land in a separate `@Published secondarySubtitleCues` list (so the host can render the two channels independently, e.g. top vs bottom), with `isSecondarySubtitleActive` and `isLoadingSecondarySubtitles` for UI state; `clearSecondarySubtitle()` tears it down. The secondary channel decodes through the same demux loop and PTS rules as the primary.