[orut34iop]

Summary

The public secondary-subtitle comments still promise text-only decoding and a second demuxer, although the current packet-store drainer creates independent decoders, cursors and PGS admission state for both channels. Correct that contract and cover the existing bitmap behavior through the actual engine drainer.

This branch also includes the original HLS admission fix from #832, preserving its commit ancestry. Merging #832 first is preferred so this PR’s remaining diff focuses on the subtitle contract and regression.

What changed

• Generated PGS display sets reuse palette/object ID zero across two streams with different colors and positions. Real shipped FFmpeg decoders feed the engine's two cue lists.
• Assertions cover independent palettes, an authored secondary clear, secondary off/reselection, and reconstruction from retained packets after a seek. Composition-only packets verify decoder state survives independently.
• Clarify supported bitmap codecs, the shipped XSUB limitation, and the host's responsibility for rendering both channels. The subtitle portion makes no production playback algorithm or default changes.

This updates the historical contract discussed in #47; it does not introduce a second bitmap pipeline. It is independent of the secondary identity/lifecycle API in #824, although adjacent comments may require a small textual reconciliation.

Initial subtitle-only validation

• Host: Mac17,3, macOS 26.7.1 (25G241), Swift 6.4 / Xcode toolchain; native SwiftPM default traits.
• Media: synthetic 1920×1080 PGS compositions with 8×8 opaque objects; no private film assets. This is automated decoder/drainer coverage, not physical playback acceptance.
• Focused strict cooperative-pool Swift Testing: 11 tests passed, including the existing off-main PGS decode suite.
• Full parallel run: XCTest passed; Swift Testing 4615 tests / one failure in the existing SubtitlePacketStoreScalingTests 2-second wall-time assertion (5.6 seconds under load). No assertions were changed. Full serial rerun passed: 795 XCTest (one existing skip), 4615 Swift Testing tests / 634 suites.
• Documentation link/anchor checker and git diff --check passed. Test executables signed and verified with a valid Apple Development identity; no ad-hoc signing.

Checklist

• CHANGELOG.md updated
• Conventional commit
• Existing engine behavior tested directly
• Public contract documentation corrected

Combined-branch validation and CI repair

The original macOS failure came from the pre-existing HLS segment-admission gap. This branch now merges #832 at 1e5353a8debf52e0177a569c24fe8d2f87d5ed3b, preserving that original commit. HLS production code and its regressions are identical to #832; the original bitmap regression is unchanged. The merge required no conflict resolution.

At combined head 87ce3bb749205284499bb85d7cfdecaa3ff514ee:

• Native host build passed, with real Apple Development signatures verified.
• Strict cooperative-pool bitmap/off-main decode/HLS admission regression: 7 tests in 3 suites passed, including eight consume/seek/close/cancel × plain/encrypted-next cases.
• Normal-pool original HTTP/1.1 and subtitle-channel regression: 20 XCTest tests passed; the selected Swift Testing tests also passed, including all eight HLS admission cases.
• Documentation link checker and git diff --check passed.
• The historical full-host results above were for the subtitle-only head. Combined-head CI results and the remaining failure are recorded below.

CI follow-up: one same-head diagnostic revalidation

Run 39107721993 tests combined head 87ce3bb749205284499bb85d7cfdecaa3ff514ee. The normal full macOS test step passed, including the original HLS regression. The one-thread cooperative-pool step instead failed in the unchanged ItemSwapStillTests.softwareRebuildHoldsThePicture: lines 349–351 report held == false, heldPictureLastRoute == nil, and heldPictureLastRelease == nil. This run does not yet establish why the software still was absent. No assertions were removed or relaxed.

That test and its held-picture/renderer/loading implementation are unchanged from base 151322d1. Upstream main still points to that base. Inspection of the #711 follow-up and fixture/held-picture history found earlier runner capture/fixture fixes already included in the base, but no verified fix for this exact failure.

On the unchanged combined head, a strict-pool focused rerun of held-picture + bitmap + HLS passed (15 tests / 3 suites), and a strict-pool full Swift Testing run passed (4,616 tests / 635 suites). This suggests an intermittent or runner-dependent failure; it does not prove the cause or replace the failed CI result.

The direct job-rerun request was rejected with HTTP 403 (repository admin rights required). The repository also explicitly uses the default pull_request trigger, including reopened. This PR was closed and immediately reopened once, preserving its number, SHA and history, to trigger a diagnostic full revalidation. No code or assertions were changed for that revalidation; the initial failure remains recorded. If the failure repeats, the next investigation needs the held-picture skip reason and outgoing renderer state before proposing a separate fix. The diagnostic revalidation has now completed successfully; see the final result below. This status is separate from physical Dolby Vision playback acceptance.

Final same-head CI result

Revalidation run 39108578203 completed successfully on unchanged head 87ce3bb749205284499bb85d7cfdecaa3ff514ee. All four checks pass: macOS default/all-traits normal and strict-pool suites plus standalone regressions/probes; tvOS/visionOS; iOS/release CLI; documentation links. The latest PR checks report pass and the merge state is CLEAN.

The initial held-picture failure above remains part of the evidence. It did not recur in the focused local run, full local strict run or complete CI revalidation; its exact cause remains unconfirmed. No test assertion or held-picture implementation was changed to obtain this result. #832 remains open independently.

[superuser404notfound]

Thanks @orut34iop, landed on main as 060d77a.

#832 was already on main (af85d85d), and this branch sits far behind main, so only the subtitle commit b2a5a267 was cherry-picked. Two conflicts were resolved on the way: the secondarySubtitleCues doc comment now sits next to secondarySidecarASSHeader from #826, and the CHANGELOG entry was rewritten under [Unreleased] > Changed in the file's current style.

The corrected contract matches the code: since the #112 drainer rework, selectSecondarySubtitleTrack rejects no bitmap codec, and the secondary channel has its own decoder, cursor and PGS gate over the shared packet store. The new SecondaryBitmapSubtitleTests passes, as does the full suite (780 XCTest with 1 skip, 4760 Swift Testing). It ships with the next release.

[superuser404notfound]

Released in 7.45.0 (52802af).