A switch for hosts with their own fallback ladder: decline the AE#561 software-path escalation, or be told when it takes

[cmcpherson274]

We moved our pin from 7.8.1 to 7.15.1 (b93f9c4b) on 23 September (EDT), escalation included. This is not a regression report or a condition on that move: it asks for a switch or a signal, for hosts that already re-plan a failing title.

Our ladder: the #461 escape, our stall net, then a demote that re-plans the title off the engine. Underneath, the escalation cannot be declined, and publishes a videoRoute change but not its cause (anchors at b93f9c4b; at 7.16.1 neither escalation file changed, and the NativeAVPlayerHost.swift anchors below sit ten lines further down):

• shouldEscalate's only host-set inputs, preferredDecodePath and nativeRemoteHLS (Native/SoftwarePathEscalation.swift:71-78), each change how the session is served. Neither file has a public symbol.
• A taken offer returns without surfacing the failure (Native/NativeAVPlayerHost.swift:977, :1007), and a successful rebuild publishes none: it survives only in log lines (AetherEngine+SoftwarePathEscalation.swift:34-44). Our demote never sees it as such; when the rebuild unwinds a load() the host still awaits, the host is handed the bare CancellationError any superseded load throws (AetherEngine.swift:1937), and ours read it as a failed load (measured below).

At 7.15.1 (Debug builds; Apple TV 4K unless noted):

• Our escape still takes, in libavcodec (dropped 0 stalls 0) [1], and on a DV Profile 5 title is refused before any teardown, session kept [2]. The software path is not our objection; who decides is.
• On our ordinary 7.15.1 legs (169 slices, before the fixtures below) the escalation never fired: no #561 line, and the 10 top-level item failures are all AVFoundationErrorDomain, with no revive exhaustion or -19602 [3].

Measured on 24 September (Apple TV 4K, Debug builds) with your nal-overrun-fixture.py over the docstring's libx265 testsrc recipe plus an aac tone: 8 s and 40 s Matroska files damaged at 3.12 s and 20.0 s, DirectPlay from Jellyfin on the loopback route, and the 8 s healthy twin, which played clean as shipped (the 40 s twin was not played). Your AETHER_DISABLE_NAL_SANITIZER switch turned the sanitizer off, proved by the muxer's #561 ... cut line on the shipped arm and its absence on the switched arm of the same file [4]:

• 7.15.1 as shipped: the sanitizer cuts the damaged sample and both damaged files play to the end; AVPlayer refuses nothing [5].
• 7.15.1, sanitizer off, the 40 s file: with the playhead at 15.90 s, AVPlayer failed the playing item (failedToPlayToEndTime CoreMediaErrorDomain/-19602) 46 ms after fetching the segment that holds the damaged frame. The Loopback-HLS: a single backward seek on heavy 4K can wedge the segment producer (video stalls, audio continues -> A/V desync) #93 revive's fresh item, mounted at 15.90 s, was refused at startup 3.1 s after the first failure (#561 AVPlayer refused ... at 12.00s, the :977 branch), and the rebuild completed 33 ms later. The picture stopped for 3.1 s and resumed 3.9 s back, at the 12.00 s the refused item reported: the rebuild reads the clock (AetherEngine.swift:3273) of an item refused before it played, which your 7.16.1 media-fallback fix avoids by reading the placement. From there the session ran at rate=1.00 on every tick to the end, decoded in VideoToolbox rather than libavcodec ([SWHost] selected HardwareVideoDecoder (VT HEVC)), with a 2.08 s gap in the presented pictures at the damaged frame (dpts=40.0/2080.0, then a tick with enq=+0; lost=0). Nothing our host received named the failure: it saw the route and audio-delivery changes and counted one stall. The deferred branch (:1007) is not reached by this shape on our route: the playing item's failedToPlayToEndTime feeds the Loopback-HLS: a single backward seek on heavy 4K can wedge the segment producer (video stalls, audio continues -> A/V desync) #93 revive (:738-748), whose reload re-arms hasEverPlayed (:2065), so the refusal is a startup one [6].
• 7.15.1, sanitizer off, the 8 s file: the same take at 0.00 s, 32 ms from refusal to #561 rebuilt on the software path. Our original load() was still waiting at the display-criteria gate; released 657 ms after the rebuild, it found its generation superseded and threw (load superseded (gen 1 -> 2); unwinding). Our host reads a thrown load as a failed load: it stopped the rebuilt session (ready, no frame presented yet), demoted the rung and showed its error card, as at 7.8.1. That half is ours to fix. It is also the case for this ask: the only hints were the videoRoute and audioDelivery changes, 657 ms before the throw, so a host must infer that this CancellationError, which also ends a load the host superseded itself, means the engine took the session [7].
• 7.8.1 (no sanitizer, no escalation), both damaged files: -19602 reaches our host as a failure and our ladder demotes the rung to its error card (on the 40 s file after three in-place recoveries of ours, 25.6 s after the first -19602); a Retry, pressed by our test rig 6 s later, re-plans the title as a server transcode, which plays to the end [8].

The ask, any one of:

1. A LoadOptions flag (say escalatesToSoftwarePath, default true, today's behaviour), read in shouldEscalate, so a declining host gets the failure surfaced for its own ladder (Native/NativeAVPlayerHost.swift:978, :1008).
2. A published signal when the escalation takes, carrying the failure it absorbed.
3. For the startup case above, a recognisable error on the unwound load(), or that load() kept waiting across the take as your Feature request: generation-scoped startup progress checkpoints for host loading UI #361 reroutes keep it (AetherEngine.swift:3581, :4031, :4787), so a host learns the engine took the session over rather than that its own load was cancelled.

[1] 7.15.1: DEV-E9-escape-dv-p8.log:185, :193, :233, :249.
[2] 7.15.1: DEV-E9-escape-dv-p5.log:249-253, :271.
[3] 67 Apple TV, 102 simulator.
[4] Fixtures: 1280x720 8-bit hevc Main + aac, Scripts/nal-overrun-fixture.py at b93f9c4b, four bytes changed per file. The switch: DEV-E9-esc-d8-default.log:88 and DEV-E9-esc-d40-default.log:113 ([MP4SegmentMuxer] #561 video sample at dts=... cut to the last whole unit), zero such lines on DEV-E9-esc-d8-nosan.log and DEV-E9-esc-d40-nosan.log. The healthy 8 s twin: DEV-E9-esc-h8-default.log:141, :146, :150.
[5] DEV-E9-esc-d8-default.log:141, :149; DEV-E9-esc-d40-default.log:148, :168.
[6] DEV-E9-esc-d40-nosan.log:147 (started, loopback, 3.4 s), :154-157 (21:07:18.132 the segment from 19.88 s, 18.178 the failure, 18.179 the stop), :159-164 (the revive at 15.90 s), :179-182 (21.284 to 21.285), :209-211, :217-219 (21.317), :221-223 (21.323, 12.000 s), :232-264 (27 [SWDiag] ticks, clk 12.61 to 38.61; the gap at :245-247), :244, :265 (our stall count).
[7] DEV-E9-esc-d8-nosan.log:119-122 (43.822 to 43.823), :151 (43.844), :156, :158-159, :161 (43.854), :163-164 (44.511, the gate and the unwind), :165-167 (44.517 to 44.518: our demote, our Aether load failed: CancellationError()).
[8] DEV-E9-esc-d8-7081.log:113-116, :140, :147, :158; DEV-E9-esc-d40-7081.log:149-175, :307, :441, :577, :597, :609, :617. The 7.8.1 build is main's pre-bump tree at its own pin, in private package and build directories.

[superuser404notfound]

Released in 7.17.0 (53ba6b79): LoadOptions.escalatesToSoftwarePath (default true) declines the AE#561 rebuild and surfaces the native failure as .error, and softwarePathEscalations publishes the rebuild when it is taken, with the failure it absorbed.

[cmcpherson274]

Thank you. 7.17.0 delivers all three asks: the flag, the publisher, and a waiting load() that follows the rebuild, with its own line, [AetherEngine] #629 load (gen <g>) follows the software-path rebuild instead of unwinding.

What we do with it. We keep the escalation on (escalatesToSoftwarePath = true, stated explicitly), subscribe to softwarePathEscalations, and log one line per take:

[Aether] software-path escalation taken — absorbedFailure.kind=<k> absorbedFailure.underlyingDomain=<d|none> absorbedFailure.underlyingCode=<c|none> absorbedFailure.message="<m>" positionSeconds=<p> duringStartup=<b> (AE#629; …)

It is on a 7.17.0 side branch and has not run yet; our pin is 7.15.1.

Measured at 7.15.1, read at 7.17.0. On our 40 s fixture from your script, sanitizer off, the #93 revive mounted its item at 15.90 s, AVPlayer refused it reporting 12.00 s, and the rebuild resumed at 12.00 s: a 3.9 s replay, in both our runs [1]. Your commit's 40 s ESCALATION at 12.00s is consistent with that. When our reload was pending on the item instead (also mounted at 15.90 s, refused at 12.00 s), the rebuild resumed at 15.90 s [2], so the replay is the #93 revive's, not ours. By our reading #621 does not reach it: this rebuild takes positionForSessionRebuild (AetherEngine.swift:5087, :3359-3361), while mountedStartPosition is read only by the fallback (:2568), and no 7.15.1..7.17.0 hunk touches rebuildPosition or positionForSessionRebuild. We will measure it at 7.17.0.

One code reading, as information. When the rebuild's load fails after its teardown, .error is published twice for one failure, with two different errors (e.g. publishLoadFailure, AetherEngine.swift:4936, then publishError(absorbed), AetherEngine+SoftwarePathEscalation.swift:90), and a load() it took rethrows the rebuild's own error (AetherEngine.swift:3707). When an escalation took our pending call, our side build logs [Aether] software-path rebuild failed after taking our <call> (<error>) — settled: … and starts nothing, leaving recovery or the error card to the published .error. Read, not run: no fixture of ours makes the rebuild fail.

_{[1] Apple TV 4K, Debug. Re-run: DEV-E9-esc-d40-nosan.log:162, :183, :224 (seekClock to=12.000); our post's run, file since renamed: :161, :181, :223. [2] Test legs with display criteria suppressed, where the play gate held our reload past the refusal: DEV-E9-esc4-d40-reinstall-nosan.log:199, :242, :282 (to=15.903); DEV-E9-esc4-d40-correct-nosan.log:281 (to=15.901).}

[superuser404notfound]

Thank you, both points reproduced and fixed on main in #646 (1a4ab82e), not released yet.

The replay after the #93 revive. The reading of the rebuild is right: it resumes at positionForSessionRebuild, and #621 does not reach it. The 12.00 s did not come from the revive's choice of position, though, but from the clock. The in-place swap mounts the fresh item at the held position (15.97 s here), and until its zero-tolerance mount seek lands, AVPlayer's periodic clock reads first the target and then the start of the segment it decodes up from. Both readings were published, so the playhead stepped back to 12.00 s, and the rebuild read it from there. The native host now holds the clock across an in-place swap until the mount seek completes finished, the item plays, or a seek of the host's own takes over. A release on "the clock reached the target" does not work, because the optimistic target reading arrives first.

Measured on the 40 s HEVC fixture damaged at 20 s, AETHER_DISABLE_NAL_SANITIZER=1, on macOS:

	refused at	rebuild seekClock to=
before	12.00 s	12.000
after, 3 runs	15.97 s	15.971 / 15.971 / 15.969

The healthy control plays out plainly and with seeks, and --no-sw-escalation still ends in -19602. The event's positionSeconds follows the same clock, so it now reads the held position too.

The double .error. Confirmed. A rebuild whose load failed after its teardown had already published its own failure, and the rung published the absorbed one on top. The rung now keeps the rebuild's, which is also the error a following load() throws, and the absorbed failure stays on softwarePathEscalations. A new test (a rebuild whose open is refused) counts two .error publications without the change and one with it.

The run above is headless, so a measurement on the Apple TV would still be welcome, with 1a4ab82e as a test pin until the next release.

[superuser404notfound]

Released in 7.17.1 (7d2d1f2), both the held playhead across the #93 revive and the single .error from a failed rebuild.

[cmcpherson274]

Thank you. Measured at 7.17.1 (7d2d1f21, which carries 1a4ab82e) on an Apple TV 4K (3rd generation, AppleTV14,1, tvOS 26.6), a Debug build of our app, your 40 s fixture damaged at 20 s, AETHER_DISABLE_NAL_SANITIZER=1, on our loopback route. Three rebuilds of the 40 s file (and one of the 8 s file, below):

	refused (the #561 line's own at)	rebuilt, after the refusal	rebuild seekClock to=	event positionSeconds
the plain tune (the #93 revive's item)	15.90 s	+36 ms	15.902	15.90
our reload pending on the item at the refusal	12.00 s	+33 ms	15.902	12.00
our option correction pending at the refusal	12.00 s	+28 ms	15.902	12.00

At 7.15.1 on the same fixture and box the plain tune read refused at 12.00 s and seekClock to=12.000. So on the device the rebuild now lands where the item failed: by the log, 3.2 s from failedToPlayToEndTime to the software session presenting (3.0 s of it the stage-2 wait), then play to the end (dropped 1 stalls 1). On the plain tune the event reads the held 15.90, as you said it would. On the other two the item was mounted by a load() of ours (#2 load … startPos=15.90s); there the refusal line prints at 12.00s, the event reads 12.00 with duringStartup=true, and the rebuild seeks to 15.902, so the event and the rebuild differ by 3.9 s.

The waiting load() follows. On those two runs our reload / correction was still pending when AVPlayer refused: a test setting of ours suppresses display criteria, so the engine's 200 ms play gate held each mount 210 / 211 ms, and AVPlayer refused 59 / 61 ms into it, leaving our call pending 151 / 150 ms after the refusal. Each printed #629 load (gen 2) follows the engine's own rebuild instead of unwinding and our call returned normally: no CancellationError, one escalation per run. The 8 s file, damaged at 3.12 s, did the same at 0.00 s during startup (the line at gen 1; event positionSeconds=0.00 duringStartup=true).

With the sanitizer on: both damaged files played out natively with one cut each, and the two healthy controls under the same reload and correction printed no #561 line. The single-.error half is not measured here: no fixture of ours makes a rebuild's own load fail, so that stays on your test.

Our pin is still 7.15.1; 7.17.1 is on a side branch, and we will say when it lands.

[superuser404notfound]

Thank you for the device run, it confirms the held playhead on the plain tune and the followed load().

The 3.9 s between the event and the rebuild on the two legs where a load() of yours mounted the item is a defect of the event, not of the rebuild. #646 holds the clock only across an in-place swap. A mount raised by a host load() is not one, so until its zero-tolerance mount seek lands, AVPlayer's clock reads the start of the segment it decodes up from, 12.00 s under the 15.90 s the load was handed. The native host passed that reading to the rung, which put it on the #561 line and on positionSeconds. The rebuild never used it: it resumes at positionForSessionRebuild, which during a load is the position that load was handed, hence seekClock to=15.902.

The rung now reads that same position once and reports it, so the engine's #561 line and SoftwarePathEscalationEvent.positionSeconds say where the rebuilt session comes back. The native host's own [NativeAVPlayerHost] #561 line keeps AVPlayer's raw reading. The existing test for the published event now models your leg (a load in flight, parked at 15.9, refused at 12): it fails on main with positionSeconds: 12 and passes with the change.

This is in #653, not merged or released yet.

[superuser404notfound]

Released in 7.18.2 (4a5c4a49): the engine's #561 line and SoftwarePathEscalationEvent.positionSeconds now carry the position the rebuild resumes at.

[cmcpherson274]

7.17.1 (7d2d1f2, with FFmpegBuild 3.6.0) became our app's pin on 2026-09-29, as we said we would tell you. Thank you again for the three asks, and for #646.

We run it as we described on 25 September: escalatesToSoftwarePath set explicitly to true, and one log line per take from softwarePathEscalations.

At 7.17.1 the escalation ran only in the Apple TV session our comment of 26 September comes from (Apple TV 4K, 3rd generation, AppleTV14,1, tvOS 26.6, a Debug build, one run per test): four takes, one in each of the four runs with the sanitizer off, and our line printed on each. Our full 7.17.1 test pass later that day, 157 test runs on the tvOS simulator and the same Apple TV (Debug builds), printed that line 0 times.

Not measured here. No Release build ran. The single .error has no fixture on our side. Nor do 7.17.1's AE#627 and AE#641: none of our test logs carries a line of either, and every live tune on the engine in those 157 runs went through our own reader, not a URL.

We have read the notes of 7.18.2 and of the other tags up to 7.22.0, thank you; we will test them in our next round.