Skip to content

4.4.0 — first-frame subtitle by language preference (#73)

Choose a tag to compare

View all tags
@superuser404notfound superuser404notfound released this 26 Jun 10:05
4.4.0
56ffc7c

Added

First-frame subtitle selection by language preference (#73)

A host with a saved subtitle-language preference had to read the post-load subtitleTracks and language-match selectSubtitleTrack itself. New LoadOptions.preferredSubtitleLanguages (ordered; ISO 639-1 / 639-2 codes or English names, e.g. ["en", "de"]; default empty) lets the engine activate the first subtitle track whose language matches a preference at the end of a successful load, mirroring the audio twin (preferredAudioLanguages, #72).

  • Resolution. Preferences are scanned in order, case-insensitive, across ISO 639-1 / 639-2 (B and T) codes and English names ("en" == "eng" == "english"). The first matching track wins; no match leaves subtitles off (the default).
  • Surface. The host-overlay path is used (equivalent to a selectSubtitleTrack call). The resolved track is published via the new activeSubtitleTrackIndex (Int?), parity with activeAudioTrackIndex, so a picker reflects the auto-selected track as well as host selectSubtitleTrack calls.
  • Resume-safe. The side demuxer is anchored at the load's resume position (clamped to the probe duration), not byte 0, so a mid-file resume seeks to the playhead instead of burst-reading from the start.
  • Convenience, not a redundant-open fix. Unlike preferredAudioLanguages (whose track is muxed into the loopback HLS at the first frame, so a late pick forces a pre-probe or reload), subtitles are activated post-load by a side demuxer at no reload or pre-probe cost. This option only spares a host from language-matching subtitleTracks itself.
  • Independent of prepareNativeSubtitles (#55), whose default selection stays host-driven via setNativeSubtitleSelected.

Empty preferences is a behavioral no-op, so nothing changes until a host opts in. The audio half of #73 already shipped in 4.3.0 (preferredAudioLanguages).

Internals: the shared language matcher is generalized (audioLanguageMatches to languageMatches, now driving both audio and subtitle selection); pure selectSubtitleIndex with 7 new unit tests (188 total, all green).

Thanks to reckloon for the request.

Full diff: 4.3.0...4.4.0

Assets 3
Loading