Apple PlatformIssue Guide
#004 AVFoundation Open

Manual subtitle selection reverts to Off during live LL-HLS playback

AvfoundationHlsPlaybackBugApple forumIosInvestigatingLl hlsApple confirmed
GitHub source

Apple confirmed. This page is generated from GitHub Issue #4; GitHub remains the canonical authoring and discussion source.

Source#

Apple Developer Forums: https://developer.apple.com/forums/thread/838684

Problem#

On live LL-HLS, an app explicitly selects a non-forced WebVTT subtitle option using:

playerItem.select(option, in: legibleGroup)

Immediately after the call, currentMediaSelection.selectedMediaOption(in:) reports the requested option. In affected real-world sessions, however, the selection can revert to Off within a few seconds or remain stuck on the previous language. The issue correlates with long-running live playback/reconnect conditions and does not reproduce reliably in short clean sessions.

A tempting explanation is that live playlist reloads trigger automatic media selection and override the manual choice. Apple explicitly stated that this is not the expected contract.

Apple-confirmed behavior#

Apple AVFoundation engineering stated:

  • Normal HLS playlist refetching does not cause automatic media selection to run.
  • A manual media selection should not be changed by automatic media selection unless selectMediaOptionAutomatically(in:) is explicitly invoked.
  • Manual selection disables automatic media selection for that group.
  • Media-selection criteria do not override a group while it is in manual selection mode.

Therefore this state transition is unexpected:

select(French)
      ↓
currentMediaSelection = French
      ↓
normal live playlist reload
      ↓
currentMediaSelection = Off      ← unexpected

Important distinction#

Do not conflate these three mechanisms:

manual selection
playerItem.select(option, in: group)

            ≠

automatic selection
playerItem.selectMediaOptionAutomatically(in: group)

            ≠

selection criteria
player.setMediaSelectionCriteria(...)

Once a specific option is manually selected, automatic media-selection criteria are suspended for that group. This is also documented by mediaSelectionCriteriaCanBeAppliedAutomatically(to:).

Investigation#

Build a state timeline around the first unexpected selection change, not merely subtitle-rendering failure.

Record:

timestamp
requested subtitle language
selectedMediaOption before select
selectedMediaOption immediately after select
selectedMediaOption periodically afterwards
AVPlayerItem identity
AVMediaSelectionGroup identity/options
playlist/reconnect events
AVPlayerItem status
access/error log events
route/interruption changes
any call to selectMediaOptionAutomatically

A useful invariant is:

manual selection established
+
no subsequent application selection call
=
selection should remain manual

If the selected option changes despite that invariant, capture the exact timestamp for Media Playback logging and sysdiagnose.

Verification#

Run at least these controls:

A. Live LL-HLS + manual subtitle selection
B. Regular live HLS + same subtitles
C. LL-HLS + explicit subtitles Off
D. LL-HLS + automatic selection intentionally invoked

For each test, distinguish:

selection state changed?
        ↓
subtitle playlist requests changed?
        ↓
legible output disappeared?

This separates a true media-selection state mutation from a WebVTT delivery/rendering failure.

Also verify that the selected option still belongs to the current legible group after any player-item replacement. Re-resolving options is useful when the app creates a new AVPlayerItem, but normal playlist reload alone should not require a new manual selection.

Caption appearance caveat#

For automatic subtitle behavior, Apple notes that global MACaptionAppearanceDisplayType affects how subtitles are chosen. If the product intentionally uses automatic language criteria, caption appearance state must be included in the test matrix.

This does not explain an already-established manual selection being silently reverted during normal playlist reloads.

Solution / Guideline#

For a user-owned subtitle picker:

  1. Use explicit select(_:in:).
  2. Treat the resulting selection as manual state.
  3. Do not repeatedly apply automatic criteria as a workaround.
  4. Observe currentMediaSelection to detect unexpected mutations.
  5. If the state reverts without an app-issued selection command, collect Media Playback logging + sysdiagnose and file Feedback Assistant with the precise timestamp.

Do not implement a timer that continuously re-selects the subtitle. That may hide the platform failure, race with genuine player state transitions, and destroy the evidence needed to diagnose the first divergence.

Engineering rule#

Separate desired media selection from delivered media. First prove whether AVFoundation changed the selection state; only then debug HLS/WebVTT delivery.

Use this chain:

user intent
   ↓
manual AVMediaSelection state
   ↓
subtitle rendition request
   ↓
WebVTT delivery
   ↓
legible rendering

The first divergence is the debugging boundary.

Evidence level#

Apple Confirmed for the manual-vs-automatic selection contract.

Investigating / platform bug candidate for spontaneous selection reversion under long-running live/LL-HLS conditions.

References#