Apple PlatformIssue Guide
#003 HLS Open

AVPlayer remains on SDR when HDR variants exist only at higher bitrates

AvfoundationHlsPlaybackApple forumInferredIosInvestigatingAbrGuideline
GitHub source

Inferred. This page is generated from GitHub Issue #3; GitHub remains the canonical authoring and discussion source.

Source#

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

Problem#

An HLS ladder advertises low-bitrate SDR variants and higher-bitrate Dolby Vision/PQ variants. On an HDR-capable device, AVPlayer can start on SDR and never switch to the PQ branch even when measured throughput is sufficient for the HDR rendition.

Example shape:

#EXT-X-STREAM-INF:BANDWIDTH=1200000,RESOLUTION=854x480,CODECS="hvc1.2.4.L93.B0",VIDEO-RANGE=SDR,FRAME-RATE=30.000
sdr_480p.m3u8

#EXT-X-STREAM-INF:BANDWIDTH=3500000,RESOLUTION=1280x720,CODECS="dvh1.05.03",VIDEO-RANGE=PQ,FRAME-RATE=30.000
hdr_720p.m3u8

Apple replied that providing complete PQ and SDR ladders of the same codecs would likely resolve the issue.

Evidence level#

Apple forum guidance + inferred selection behavior.

The public contract does not state that AVPlayer permanently locks an item to the initially selected VIDEO-RANGE. The safer conclusion is that the mixed ladder topology can constrain or destabilize the eligible switching set.

Explanation#

Do not model ABR as a pure bandwidth comparison.

A more useful model is:

all advertised variants
        ↓
compatibility / eligibility filtering
        ↓
eligible variant set
        ↓
ABR bandwidth selection

Therefore:

observedBitrate > HDR BANDWIDTH

only proves that the network can sustain the HDR rendition. It does not prove that AVPlayer currently considers that rendition eligible for switching.

The mixed ladder couples two dimensions:

bitrate transition
+
dynamic-range transition

Instead of a normal in-family adaptation such as:

SDR 480p → SDR 720p

the player must cross into a different dynamic-range / codec-output state:

SDR state
    ↓
PQ / Dolby Vision state

Solution / Guideline#

Author complete, independent ladders rather than using SDR only at the low end and PQ only at the high end.

Prefer:

SDR: 480p → 720p → 1080p
PQ:  480p → 720p → 1080p

instead of:

SDR: 480p
PQ:         720p → 1080p

This allows AVPlayer to adapt bitrate without requiring every bandwidth transition to also cross a dynamic-range boundary.

AVPlayer.eligibleForHDRPlayback should not be treated as an ABR control. It indicates whether the current device/display path can present HDR; it does not select the HDR branch of the HLS ladder.

Verification#

Test the same content and device with four manifests:

A. Mixed ladder
   SDR low / PQ high

B. Complete SDR ladder only

C. Complete PQ ladder only

D. Parallel complete SDR + PQ ladders

Capture for each run:

initial indicated bitrate
observed bitrate
indicated average bitrate
variant switch events
VIDEO-RANGE of selected variant
current route / HDR display capability
stall events

Interpretation:

A stuck, B/C/D adapt
→ authoring topology is the main differentiator

C adapts through PQ rungs
→ PQ decoding itself is not the problem

D remains SDR despite high bandwidth
→ investigate variant eligibility, display route,
  codec/profile compatibility, and AVFoundation behavior

Engineering rule#

Throughput determines what the network can sustain; it does not define the complete set of variants AVPlayer is willing to switch between.

When ABR appears to ignore available bandwidth, inspect the candidate set before blaming the bandwidth estimator:

manifest
→ compatibility
→ VIDEO-RANGE
→ codec/profile
→ display capability
→ media-selection constraints
→ ABR

The same method applies to HDR/SDR, codec-family, frame-rate, audio-group, and HDCP-related switching problems.

References#