feat(decode): Dolby Vision IPT→HDR10 on the GPU, and hardware decode for MV-HEVC

[bilipp]

Summary

Dolby Vision profile 20 (DVprofile20.mp4, MV-HEVC 4K) had two user-visible problems. Both are fixed here, one commit each.

1. Pink/green picture — feat(decode): convert IPT-base-layer Dolby Vision to HDR10 on the GPU

Profiles 5, 10.0 and 20 (base-layer compatibility ID 0) carry IPTPQc2, not YCbCr. The renderer displayed it as YCbCr, which produces the tint. No colour tag can fix this:

• FFmpeg drops the matrix attachment, because CoreVideo has no IPT matrix for decoded buffers.
• The RPU reshaping changes per scene.
• Apple's decoders don't apply it either: AVAssetReader and AVAssetImageGenerator return raw IPT even from a correctly signalled dvh1 track.

VideoDecoder.deliver now passes these frames to DolbyVisionConverter, a Metal compute pass. Using the frame's RPU (AV_FRAME_DATA_DOVI_METADATA), it:

• applies the polynomial and MMR reshaping,
• converts IPT to PQ-coded LMS,
• linearizes, then goes LMS → BT.2020 through the RPU matrix and a crosstalk-free Hunt-Pointer-Estevez transform,
• writes HDR10 into a tagged 10-bit video-range buffer.

The renderer tone-maps the result like any HDR10 stream. Hardware frames stay on the GPU (texture cache, zero-copy).

Detection is the stream's DV configuration record or a frame tagged IPT_C2, because many profile-5 encodes leave the VUI matrix unspecified. HDR10-compatible profiles (8.1 etc.) stay on the zero-copy path.

2. Heavy stutter on Apple TV — fix(decode): keep MV-HEVC's second view away from VideoToolbox

The stream never decoded on hardware. FFmpeg's VideoToolbox glue puts the second view's SPS/PPS (nuh_layer_id 1) into the same hvcC as the base layer's; Apple expects them in a separate lhvC. VideoToolbox rejects the session, and FFmpeg falls back to software without returning an error: 4K 10-bit HEVC on the CPU, about 20 fps on an M1 Pro.

HEVCBaseLayerFilter removes every nuh_layer_id > 0 NAL unit before the codec sees it, in both packets and extradata (FFmpeg's MP4 demuxer merges lhvC into the extradata). The engine only ever shows the base view, so nothing visible is lost. Pipeline throughput on the sample went from 19.6 to ~101 fps, on VideoToolbox.

This stayed hidden because isHardwareActive meant "a VT device is attached", not "frames come from VT". It now reads the frames' pixel format, and a silent fallback emits .downgradedToSoftware. That also exposes an existing case: VideoToolbox here refuses the field-coded H.264 fixture, so interlaced.ts was always decoded in software. The deinterlace tests now wait past that informational event instead of expecting .endOfStream first.

Overlap: #33 also covers DV IPT reshaping. This PR was built independently of it.

Type of change

• fix — bug fix
• feat — new capability
• perf — performance improvement
• refactor — neither fixes a bug nor adds a feature
• docs — documentation only (PLAN.md §6/§7 decision and spike result, AGENTS.md invariants)
• test — adding or fixing tests
• build / chore — build pipeline, tooling, or maintenance

Invariants

Data-plane changes, all inside the decode stage. Both the conversion and the filtering run on the video decoder's own thread, which is allowed to block (PLAN.md D1); the GPU wait happens there, never on an actor.

• No blocking FFmpeg call was added to an actor, and no stage bypasses Channel.
• No rebuild-in-place: a new URL is still a new session object.
• Raw container timestamps still stop at TimestampUnwrapper.
• A/V sync is still owned by AVSampleBufferRenderSynchronizer (no new heuristics or clocks).
• No force unwraps, as!, fatalError, or assertionFailure in engine paths; failures are typed. If Metal is missing, the session plays unconverted (tinted) rather than stopping. A GPU refusal (iOS, backgrounded app) skips conversion for that frame only.
• No new global mutable state; configuration still flows through PlayerConfiguration. The derived HPE matrix is an immutable static let.
• No control flow derived from av_log strings.

Verification

• swift build is warning-free. Nothing from this branch warns. Render/SystemRenderer.swift:63-64 has two main-actor isolation warnings that are not touched here.
• swift test is green:

Test run with 101 tests in 16 suites passed after 18.759 seconds.

• I added or updated tests for this change.
  • DolbyVisionTests:
    • metadata extraction from a synthetic AVDOVIMetadata
    • GPU output against an independent Double reference (polynomial + MMR, odd sizes, two chroma sitings): within 1 code
    • HPE matrix against libplacebo's published constant
    • real-stream cases: profile 20 converted with natural colour on both the VT and software paths, and asserted to decode on VT; profile 8 left alone
  • HEVCBaseLayerFilterTests: both packet framings, the hvcC rewrite, malformed input passing through untouched.
  • Negative controls: with conversion disabled, the profile-20 test fails on every frame; with the layer filter disabled, it fails on the hardware-decode assertion.
• New media fixtures: none. The DV samples can't be redistributed, so the real-stream tests use the gitignored TestStreams/DolbyVision/ and skip where it's absent, CI included. The tests that run everywhere are the synthetic ones.

Platforms verified

• macOS: tests, plus the rendered engine frame inspected
• iOS / iPadOS: compiles (xcodebuild -destination generic/platform=iOS), not run on a device
• tvOS: Apple TV 4K through Lume. Correct colour, and smooth after the MV-HEVC fix.
• visionOS: compiles, not run

Real-world content

• MP4, HEVC Main 10 MV-HEVC (stereo), Dolby Vision profile 20 (compatibility ID 0, dvwC), 4K24, ~34 Mbps, local VOD. Before: pink/green, and stuttering on Apple TV (software decode). After: correct colour, VideoToolbox decode.
• MP4, HEVC, Dolby Vision profile 8.1, 4K: unchanged (not converted, zero-copy).

Known limits: the output is static HDR10 (no DV L1/L2/L8 trims and no MDCV/CLL attached yet). Enhancement-layer profiles (7 FEL, 4) aren't handled, and only the base view of MV-HEVC is shown.