Publish the effective video route: nativeRemoteHLS does not reflect an ingest fallback

[edde746]

LoadOptions.nativeRemoteHLS records what the host asked for, but the engine can change the effective route after that: the #168 carriage watchdog reroutes onto the ingest loopback mid-session, and the #199 remembered-verdict path takes the loopback straight away. In both cases options.nativeRemoteHLS is set to false internally, and loadedOptions is not public, so a host has no way to learn which pipeline actually ended up serving the session.

That matters because host behaviour differs per route:

• external subtitles: the loopback honours load-time LoadOptions.externalSubtitles, the bypass drops them, so a host that compensates after load ends up registering them twice once a fallback happens;
• subtitle timing ownership: on the bypass AVPlayer draws the origin's WebVTT, on the loopback the host's own renderer owns it;
• composited PiP subtitles: only meaningful on the software path.

Could the engine publish the effective route — e.g. @Published public internal(set) var activeVideoRoute: VideoRoute with .nativeAVPlayer / .loopbackIngest / .software, or simply expose the post-fallback nativeRemoteHLS — so hosts can reconcile on the change rather than inferring it? A published value would also let a host react to the mid-session reroute, which today is only visible as a log line.

Workaround in the meantime is asking subtitleTracks whether external entries already exist, which covers duplicate registration but not the timing or PiP decisions.

[superuser404notfound]

Shipped in 6.15.0 as AetherEngine.videoRoute.

@Published public internal(set) var videoRoute: VideoRoute
// .none / .remoteBypass / .loopback / .software / .audio

Two deliberate departures from the sketch in the issue.

The name. Not .nativeAVPlayer: the loopback is AVPlayer too, so that name would point a host at the wrong distinction. .remoteBypass is AVPlayer on the origin URL, no demuxer and no local server. .loopback is the demuxer plus the local HLS-fMP4 server.

Both directions. The issue lists only the moves onto the loopback. It also goes the other way, and nativeRemoteHLS flips to true underneath the session when it does. All four publish:

Move	Trigger	When
.remoteBypass -> .loopback	#168 watchdog: readyToPlay, but no video track for a master that advertises one	mid-session
.remoteBypass -> .loopback	#199: that master's verdict is remembered, so the doomed mount is skipped	at load
.remoteBypass -> .loopback	AE#268: playlist plus the first segment's PMT identify a finite HEVC-in-MPEG-TS VOD	at load
.loopback -> .remoteBypass	AE#154 / AE#246: an HLS playlist reached the loopback path, which cannot demux it	at load

The value is derived rather than stored a second time: a pure fold over playbackBackend and the session's effective options, recomputed from each one's didSet and assigned only on a real change. That is the arrangement playbackPhase already uses, and it is what keeps a reroute added later from being able to forget the route, since every reroute already writes one of those two properties.

Two behaviours worth knowing before writing against it:

• A declared bypass is not a route. The value stays .none until a backend exists, so a load that reroutes before it ever mounts natively never publishes a bypass it did not take.
• Teardown returns it to .none, like every other per-session published value.

On the three motivations, the first one is already gone:

• External subtitles. 6.14.0 closed that separately (nativeRemoteHLS: external subtitles can never become renditions (load-time dropped, post-load overlay-only) #316). Both entrances into the bypass now register LoadOptions.externalSubtitles themselves, and the legible-group discovery merges instead of assigning, so the post-load compensation can come out entirely, and the duplicate registration after a fallback goes with it.
• Subtitle timing ownership. This is what the route is for. On .remoteBypass AVPlayer draws the origin's renditions; on .loopback and .software your renderer owns them.
• Composited PiP subtitles. playbackBackend == .software already answered that one, and videoRoute == .software now answers it in the same value.

The mid-session case is the one worth proving rather than asserting, so it was run end to end against a live master advertising hvc1 while carrying HEVC in MPEG-TS:

[AetherEngine] #321: effective video route = remoteBypass
[NativeAVPlayerHost] #1 asset.load(tracks) ok count=0
[NativeAVPlayerHost] #1 carriage probe: hevcInMPEGTS from playlist evidence (#293)
[NativeAVPlayerHost] #1 the source's own PMT declares HEVC in MPEG-TS, so AVPlayer will build no
                        video track; rerouting 4.0s before the watchdog grace (#293)
[AetherEngine] #168: rerouting onto the live-ingest loopback path (TS -> fMP4 remux)
[AetherEngine] #321: effective video route = loopback

The other direction is on real media too: Apple's bipbop_adv_example_hevc master takes the AE#154 reroute and publishes remoteBypass at the moment it happens, with no misleading .loopback emission in front of it. 1606 tests green, -strict-concurrency=complete clean, tvOS and iOS Simulator builds green.

aetherctl play prints route= next to backend= now, so the value is capturable from the harness without a device.

Leaving this open until you have confirmed it reads the way your host needs it, in particular that a reroute on your own masters arrives as a published change rather than a log line.

Thanks for the write-up. Listing the three per-route behaviours is what made the scope obvious.

[edde746]

Confirmed on 6.15.2 — videoRoute reads exactly the way this host needs it.

The host mirrors $videoRoute into the latch that owns subtitle ownership, so a reroute
arrives as a published change and moves rendition-vs-libass ownership with it; our route
suite drives the .loopback → .remoteBypass flip and back on that latch directly. Two of
your design notes turned out to be the load-bearing ones:

• .none being teardown rather than a decision is what keeps the latch from resolving
  subtitle ownership against the outgoing track while PiP still reads active — we treat it
  as a dropped latch, and beginNewSession owns the reset.
• The value staying .none until a backend exists means a load that reroutes before
  mounting never shows us a bypass it didn't take, so we key nothing on the declared
  options anymore.

All three motivations from the issue are resolved: the duplicate-registration compensation
is deleted outright (see #316), timing ownership keys on .remoteBypass, and the composite
PiP decision reads .software from the same value. Fine to close from our side.