AirPlay carries audio but no picture on the software path, and the engine announces the opposite

[superuser404notfound]

Field report (Discord): an MKV played to an AirPlay receiver gave sound and no picture. Log from AetherPlayer 0.18.1 (69), iPhone 17 Pro, iOS 27.0, engine 7.5.0.

The session that produced it:

[VTProbe] canHardwareDecode codec=27 1280x720 -> true (status=0)
[AetherEngine] source is forward-only, forcing software path
[AetherEngine] dispatch: codec=27 -> software
[AetherEngine] #315: an external screen holds the picture, so no local first frame is coming;
               latching hasFirstFrameReadyForDisplay at readiness
[AetherEngine] #321: effective video route = software

Audio then played to the receiver for 16 s (clock advancing, enq and disp tracking) with nothing on either screen.

Mechanism

The AirPlay video path (#86, #227) is an AVPlayer feature end to end: handleExternalPlaybackChange returns early unless playbackBackend == .native, and the receiver is served the engine's own loopback HLS over the LAN IP. The software path has no AVPlayer. Its audio reaches the receiver because AVSampleBufferAudioRenderer follows the audio session route, and its picture goes into a local AVSampleBufferDisplayLayer, which AirPlay does not carry (only screen mirroring would). So audio-and-no-video is the guaranteed outcome of a software-path session on a wireless receiver, not a failure mode.

Two things are worth separating here.

The engine states the opposite of what is true. externalPlaybackHoldsThePicture is read on a session where nothing holds the picture, and #315 latches hasFirstFrameReadyForDisplay on readiness to spare the host a cover that would never lift. On the native path that is exactly right. On the software path it promises a picture that does not exist anywhere, so a host cannot tell the viewer what is going on, and the log reads as if everything is fine. Whatever is decided about routing, this asymmetry should go: the software path should either not take the #315 branch, or the fact that this route carries no picture should be published so a host can say so and point at mirroring.

The routing premise that put this session on the software path does not hold here. The codec was hardware decodable (canHardwareDecode ... -> true); what forced software was the origin answering a suffix range with status=200 and never resolving a size, so the source degraded to forward-only (AetherEngine.swift, the !probe.isSourceSeekable && !options.isLive branch). The exemption next to it already describes this case: options.sequentialOrigin keeps a linear source on the native path because the producer reads from byte 0, the duration is declared, and the segment plan falls back to uniform stride. Here the container declared its duration ([SWHost] session start: ... duration=183.1s), so the #126 premise (unknown length, zero segments) is not what happened. Whether a duration-carrying forward-only URL source should get the same treatment as a declared sequential origin is its own question, and it is the difference between AirPlay working and not working for this class of source.

Scope

Consumers that play arbitrary URLs (AetherPlayer). A Jellyfin library source answers ranges, stays native, and AirPlays normally, so Sodalite is not affected in practice.

The interruption wedge visible in the same log is filed separately.

[superuser404notfound]

Measured the open half, and the answer is no: a forward-only URL source should not be routed to the native path. Two runs against the origin from the report (30.9 MB MKV, no Content-Length, suffix range answered with status=200), both with --sequential-origin --declared-duration 183.13, which is the strongest case the native path can be given today.

Run 1, main as it stood: the session died before playing a frame.

[HLSVideoEngine] cue prewarm: seek to 91.6s took 2493.9ms
[HLSVideoEngine] segment plan: keyframe-aligned, 21 IRAPs -> 17 segments
[matroska,webm] File ended prematurely at pos. 32435595
[HLSVideoEngine] #126 VOD pump reached eof without producing anything (0 packets written, 0 segments cached)

That is a defect of its own and it is now fixed on main (3e2f945e): the prewarm is priced as a byte-range read plus a seek that fails fast where it cannot, and on a non-seekable pb libavformat implements a forward seek by reading and discarding. So it walked to the middle of the file, the single unranged GET was spent, and the producer had nothing left. The planner already skipped its IRAP spacing scan two blocks below for exactly this reason. cuePrewarmMayRun(hasSegmentedReader:isSourceSeekable:) now covers the larger hole above it.

Run 2, with that fixed: the source plans on uniform stride and plays, and it is still not good enough to route onto.

[HLSVideoEngine] segment plan: uniform stride fallback (1 IRAPs in index, need >=2, ...) -> stride=4.000s, 46 segments
[HLSVideoEngine] restart at idx=0 refused: a sequential origin can only be read from byte 0,
                 so the reposition would mislabel content; surfacing source failure
  PHASE error("Source cannot be repositioned (code -5)") t+6.30s
  ... recovers, plays to 15.10s with rebuffering stretches and 19 drops

The seg0 re-cut restart is refused by construction on a sequential origin, and the refusal is published as a fatal error phase before the session recovers. A host shows an error dialog over a film that then keeps playing. Against that, the software path plays the same source cleanly from the first frame.

So the routing stays as it is, and the honest summary for this class of source is the one in the code now: the software path renders locally, a wireless receiver gets the sound, and screen mirroring is what carries the picture. An origin that answers ranges (any Jellyfin library) stays native and AirPlays normally.

What would change the answer is not a routing flag but the restart: a producer that can revive a sequential origin by re-requesting it from byte 0 and relabelling, rather than refusing. That is a bigger piece of work and it has no reporter behind it yet, so I am leaving it unbuilt and noted here.

[superuser404notfound]

Released in 7.6.0 (2dd24f04).