Skip to content

3.13.0 — Native subtitle tracks for PiP, AirPlay & external display

Choose a tag to compare

View all tags
@superuser404notfound superuser404notfound released this 22 Jun 11:28
3.13.0
3ebfca1

Native subtitle tracks (PiP, AirPlay, external display)

Text subtitles can now be muxed into the fragmented-MP4 stream as native tx3g (mov_text) tracks, so AVPlayer renders them itself and they survive Picture-in-Picture, AirPlay, and external-display playback, where a host-drawn overlay is never composited. This rides the existing media.m3u8 path: no master playlist is introduced, so SDR / HDR / Dolby Vision routing (including Profile 5) is byte-identical to before.

What lands

  • All text subtitle tracks (embedded and sidecar) are carried as separate language-tagged tx3g tracks, so AVPlayer's native legible menu enumerates every language and the user can switch language from the stock player UI, including in PiP / AirPlay / external display.
  • Works uniformly across SDR, HDR10, HLG, and Dolby Vision, because it never depends on master-level variant selection.

Public API (additive, minor bump)

  • LoadOptions.prepareNativeSubtitles (opt-in; default false). When off, the muxer output is byte-identical to before and no native subtitle menu appears.
  • @Published nativeSubtitleRenditionAvailable: Bool and @Published nativeSubtitleTracks: [NativeSubtitleTrack] (ordinal, language, display name).
  • setNativeSubtitleSelected(track ordinal: Int?) for host-driven selection (nil deselects); a pure-native host can ignore it and let the menu drive.

Behavior and scope

  • All native subtitle tracks are disposition:default=0, so nothing auto-displays: the native menu or the host selects. (ffmpeg's movenc force-enables the first subtitle track regardless of disposition, so the engine clears the tkhd enabled bit on the subtitle traks in the init segment.)
  • Text codecs only (SRT / ASS / SSA / VTT / mov_text), carried as plain text. Full ASS styling stays inline via the host renderer; bitmap subtitles (PGS / DVB) remain host-only.
  • VOD. Live-source native subtitles are a follow-up.
  • One side-demuxer pass decodes all text streams into per-track bounded cue stores; memory stays bounded by cue count.

Closes the engine side of #55. Host integration (PiP/AirPlay detection plus overlay/menu coordination) is a separate consumer-side task.

Assets 3
Loading