Unify handling of dynamic range checks

[DrHurt]

What should the engine do?

All macOS 26+ devices and all iOS 26+ devices run in HDR mode by default on built in displays. Native apps & OS UI are all mastered in HDR.

The OS transparently tone maps SDR-only apps and if needed, system can also physically switch displays to SDR which is instant and seamless as there is no HDMI handshake like TVs.

Intel Macs are SDR-only on internal displays and do the reverse with HDR apps.

Sodalite on iOS devices currently runs in SDR mode.


The better alternative in my opinion would be to enable high EDR headroom in Sodalite (or the engine) via .allowedDynamicRange(.high) in the appropriate views before checking currentEDRHeadroom which should then return > 1 on HDR displays & == 1 on SDR displays.

This would create a simpler, unified dynamic-range detection algorithm across all supported devices and displays (including external ones)

Ideally this should be engine-side so it makes it to all host apps but will need testing.

Thanks again and good luck

Motivating media or use case

Unified & simplified cross platform approach

Area

HDR / Dolby Vision

Host app / integration context

No response

Would you be willing to open a PR?

No

[superuser404notfound]

Thanks for the detailed writeup, this prompted a proper look at all three detection paths.

Some context on where the engine already landed: since 4.10.0 the master-vs-media routing decision is a pure, tested function, and on iOS AVPlayer.eligibleForHDRPlayback counts as panel readiness (f9b6d55). HDR and DV sources on HDR-capable iPhones and iPads route through the master playlist since that release, so the SDR behavior you describe should be gone with a host build carrying 4.10.0 or newer. If you still see SDR playback on such a build, that is a bug and logs would be very welcome.

On the currentEDRHeadroom approach: we prototyped exactly that during the AE#88 retest before settling on eligibility, and reverted it for three reasons.

1. Ramp race. currentEDRHeadroom is a momentary value the system ramps while EDR content is on screen. Measured on an iPhone on iOS 26, it read 1.0 when launching playback from the SDR browsing UI. .allowedDynamicRange(.high) on views showing SDR artwork (which is all a Jellyfin browsing UI has) does not engage EDR by itself, so a load-time read races the ramp.
2. Stability. Headroom drops toward 1.0 under Low Power Mode and thermal pressure. A load-time headroom gate would route an HDR film media-direct in that state, and the media playlist carries no SUBTITLES renditions, which would silently re-introduce the PiP subtitle bug the eligibility routing fixed. Serving the HDR master and letting the OS tone-map is strictly better there.
3. tvOS cannot join a unified check anyway. The -11848 failure mode (master claims PQ while the panel is parked in SDR) lives behind the HDMI mode switch, so tvOS keeps the handshake plus post-settle headroom read regardless, as you already noted yourself.

The part of your proposal that was genuinely missing is macOS: the gate treated Mac like tvOS and required a host-passed panel state for which macOS has no clean standard source. That is fixed on main now (1d02e20). macOS built-in panels count as engage-on-demand with the same eligibility signal as iOS, and SDR-only Macs (Intel internal panels) read ineligible and stay media-direct. Detection is now unified across iOS and macOS on one stable signal, with tvOS as the single documented exception.

If iOS 26 turns out to keep app-wide headroom raised once a view opts in via .allowedDynamicRange(.high), that could still be useful as a secondary confirmation signal, but it needs device data first. If you get around to measuring that on your hardware, happy to revisit.

[DrHurt]

Your approach is very sensible & should cover most use cases (including my setup).

My only concern is whether AVPlayer.eligibleForHDRPlayback reports correctly for HDR-capable-Macs (Apple-silicon) connected to SDR monitors. I don’t have the hardware to test that scenario. Master would fail here.

Have you already specifically tested .allowedDynamicRange(.high) + SDR UI content on screen + query currentEDRHeadroom?

To the best of my understanding, currentEDRHeadroom measures headroom, not on screen content. On windowed systems, manually allowing high EDR is required to allow EDR headroom > 1

Both APIs supports OS 14+ (fits aether perfectly)

Allowing high dynamic range via above API is probably useful regardless of playlist routing as it would allow displaying HDR user assets (HDR cover photos from home libraries)

As always, no strong feelings! Current setup works for my use case.

[DrHurt]

There is also the case of Intel Macs that do not support HDR on internal displays but DO support it on external display (at least some models).

[superuser404notfound]

Took another look at the SDK contract to answer both questions precisely.

Apple silicon plus SDR external monitor. The AVFoundation header is explicit that eligibleForHDRPlayback is display-configuration aware, not a static device capability: "This property is YES if an HDR display is available and the device is capable of playing HDR content from an appropriate AVAsset", and AVPlayerEligibleForHDRPlaybackDidChangeNotification fires on "display connection/disconnection or resource changes". A clamshell Apple silicon Mac driving only an SDR monitor should therefore read ineligible and route media-direct. The engine reads the value fresh on every load, so connecting or disconnecting a display is picked up on the next start.

The mixed case (lid open with the internal HDR panel plus an SDR external display, player window on the external) can read eligible device-wide and put the master on an SDR screen. That is benign on macOS: there is no analog of the tvOS -11848 failure because nothing requests a display mode switch. The window server composites EDR per window and tone-maps to what the target display can do. So "master would fail here" does not apply to macOS; the worst case is tone-mapped playback with DV signaling and subtitle renditions intact, which is the degradation direction we want (same argument as Low Power Mode).

Intel Macs with HDR only on external displays. Same contract: eligibility should flip to true when the HDR display connects, which is exactly the case the connection/disconnection notification documents, and the per-load read picks it up. If a specific model misreports in that configuration, the cost is media-direct routing on that setup, not a playback failure. Since neither of us has that hardware, logs from anyone who does would be welcome.

Your direct question: no. The exact combination (a view opted in via .allowedDynamicRange(.high) in the hierarchy, SDR content on screen, then reading currentEDRHeadroom) has not been measured. The 1.0 reading came from the plain SDR browsing UI with no EDR opt-in anywhere, so your reading of the API (opt-in raises reported headroom regardless of content) is untested rather than contradicted. The routing decision would not change either way though: a capability-shaped headroom probe was actually the first thing we shipped host-side (UIScreen.potentialEDRHeadroom) and we replaced it with the eligibility gate, because for routing it encodes the same information as eligibleForHDRPlayback while knowing less about the media pipeline and the current route. And currentEDRHeadroom specifically keeps the Low Power Mode and thermal clamp problem regardless of the opt-in behavior.

Fully agree on the side point: .allowedDynamicRange(.high) is worth adopting in host UIs for HDR stills like cover art from photo libraries, independent of playlist routing. That lives host-side rather than in the engine, and it is a good catch.

[DrHurt]

I’m learning as we go!

I’ll wait until 0.13 arrives on my iPhone and will test on SDR and HDR external monitors and will let you know how that goes.

Ps. Another interesting finding today:

• DV P5 -> Jellyfin server remux -> master.m3u8 -> iPhone Safari -> HDMI (HDR10-adapter) -> DV TV.

TV shows HDR10 BT2020 and plays. So that’s P5 via master playlist on HDR-locked panel. (iPhone cannot see TV’s DV compatibility via this adapter)

• same test with same adapter on SDR monitor -> Safari shows stop sign (presumably master playlist rejected). This confirms AVPlayer accepts P5 master on HDR10-only panel (on iPhone at least) and reacts it on SDR-only monitor.

More testing is needed before I can draw any conclusions. I suggest you wait until I do more testing.

This does reopen the question of whether P5 can play via master and P8.1 can play without stripping on HDR10-only non-DV panels.

[superuser404notfound]

That P5 finding is a genuinely useful data point, thanks. Agreed on holding off, nothing changes in the routing until you have more results.

Some context so the next round hits the most useful spots: the engine's P5 guard (always media-direct on non-DV routes) and the P8.1 dvvC strip on non-DV panels both trace to the same evidence, tvOS 26 testing on 2026-05-26, where a bare dvh1.05 master and hvc1 plus dvvC both failed with -11868. Your result does not contradict that; both observations fit a platform split where the tvOS codec filter is stricter than iOS. Your SDR stop sign also matches what the SDR gate does on every platform.

Two things worth ruling out while you test:

1. The Jellyfin remux master is a different playlist writer than the engine. If you can capture the working master (curl the master.m3u8 URL), we would know exactly which CODECS / SUPPLEMENTAL-CODECS string iOS accepted. It may not be a bare dvh1.05.xx.
2. Safari's HLS stack is not necessarily identical to in-app AVPlayer, so an in-app repro would carry more weight for the routing decision.

If it holds up, the change would be to relax the P5 media-direct guard on iOS/macOS from "any non-DV route" to "SDR route only", and likewise make the P8.1 dvvC strip tvOS-only. That restores master-playlist benefits (SUBTITLES renditions, so PiP subtitles) for P5 and P8.1 over HDR10 adapters. tvOS keeps both guards as the evidence stands.

[DrHurt]

Interesting findings:

Environment:

• iPhone 15 + iOS 26.5 + Sodalite 0.13
• Jellyfin 12 + DV P5 MKV
• HDR10 USB C to HDMI cable
• SDR Monitor
• DV TV

Results:

iPhone built in display:

• P5 Movie plays
• PIP subtitles work so master used

iPhone to SDR monitor:

• Sodalite says cannot open file
• Jellyfin Client in Safari cannot open file

iPhone to TV:

• Movie plays & TV says HDR10 BT2020
• Subtitle PIP work so master is being used
• Jellyfin Client in Safari works

Summary of findings:

• DV P5 works via master playlist on HDR10 non-DV device
• Sodalite cannot tell when SDR monitor is connected so playback fails.

Next Steps:
Can you try a DV P5 via master playlist on your non-DV Samsung?

This opens the path to P5 via master & P8.1 without stripping on non-DV HDR panels

[superuser404notfound]

Ran it on the non-DV Samsung on tvOS 26.5, and it plays. A bare dvh1.05.06 master, no SUPPLEMENTAL-CODECS and no db1p/db4h backward-compat brand, served to a panel reading dvModeAvailable=false and HDR10-only (EDR headroom 1.20): the item reached readyToPlay and started at t+0.87s, the video track came up as dvh1 / PQ / BT.2020, and there was no -11868 or -11848. So tvOS accepts the P5 master here too.

That reframes your last round. It is not an iOS-versus-tvOS split after all, it is a tvOS-version story: the -11868 that grounded the P5 media-direct guard was tvOS testing on 2026-05-26, and it no longer reproduces on 26.5. iOS 26.5 and tvOS 26.5 now behave the same on this route.

So the P5 guard looks relaxable on both platforms, not just iOS. Two things keep me from just flipping it:

1. This is one panel on 26.5. If the codec filter only relaxed in a recent point release, an unconditional change could regress anyone still on an earlier build back to -11868. So the open question is unconditional versus OS-version-gated, and I want to know when the filter changed before deciding.
2. The P8.1 dvvC strip is a separate guard, and this was a pure P5 test. Before relaxing that one I want the same check: a P8.1 master with dvvC intact on a non-DV panel, to see whether hvc1 + dvvC still trips -11868 on 26.5.

Separately, the SDR-monitor failure you hit stays the real defect, and it is independent of all of this: the engine reads eligibility device-wide on iOS, so it never learns an SDR external display is the active route and ships a master the SDR pipeline rejects. The fix is route-aware capability (probe the external screen's EDR ceiling, media-direct when it reads SDR), which I still need to confirm is separately readable under mirroring.

If you can capture a P8.1 title over the HDR10 adapter the same way you did the P5, that closes the second guard question.

[superuser404notfound]

Correction to my own open question above: the version framing was wrong. Digging in, the -11868 from 2026-05-26 traces to how the engine was emitting the P5 master at that time, not to a platform codec filter that later relaxed. The engine emits a well-formed bare dvh1.05 master now, and that is what both tvOS 26.5 and iOS 26.5 accept.

So there is no OS threshold to gate on. I dropped the P5 always-media-direct guard unconditionally (shipped in 3670b9b). P5 now follows the standard HDR routing: it masters on a ready HDR panel and stays media-direct on an SDR route, which also makes your external SDR monitor degrade gracefully for P5 instead of failing.

Still open, unchanged: the P8.1 dvvC strip is a separate guard and needs its own retest (a P8.1 master with dvvC intact on a non-DV panel), and the iOS device-wide-eligibility gap that hard-fails other HDR sources on an SDR external monitor.

[DrHurt]

Test Results:
DV8.1 also works perfectly fine via Sodalite & Safari on HDR10-only path.

Further thoughts:

• I think now is a good time to default to master routing for everything by default (SDR/HDR/DV/HLG)
• Only fall back to media when SDR tone mapping is required (SDR-locked TV)
• This also allows revisiting CC subtitles and enabling the native implementation

iOS/macOS to SDR display: low priority & 2 thoughts:

• manual API & toggle to force media playlist
• engine try master & if fails, automatically re-try using media playlist with a LOUD log entry saying falling back to SDR tone mapping!

Or leave it for now and add it to limitations list until we do more testing and see if we can reliably detect SDR monitors.