Software path: nothing measures the decoded read-ahead, so an IO hiccup arrives with no cushion figure in the log

[superuser404notfound]

Split out of #295, where a ~100 ms blocked read on the demux thread turned into a visible picture stutter. The read defect is fixed. What is left is that nobody, including me, could say from a log how much cushion the software path had when it hit.

What actually bounds the read-ahead today

One thing, and it is not ours:

// SoftwarePlaybackHost.swift, runDemuxLoop
while !renderer.isReadyForMoreMediaData && !stopRequested() && !backgroundAudioOnly() {
    Thread.sleep(forTimeInterval: 0.005)
}

SampleBufferRenderer.isReadyForMoreMediaData forwards to AVSampleBufferVideoRenderer, whose fill policy is an AVFoundation heuristic. There is no target depth in seconds, no floor before playback starts, and no re-fill target after a stall. The 4-frame reorder buffer is for B-frame ordering and is not a cushion.

That may well be fine. The point is that it is unmeasured, so the question cannot be settled either way from a field trace.

Three signals that look like they answer it and do not

• frameAhead is activeProducerShiftSeconds - playlistShiftSeconds, the Clock/frame divergence accumulates under sustained seek rate (#35-class, #38 retest follow-up) #49 producer-shift fold on the native path, and it is 0 on software and audio by construction. In Software-path SD MPEG-2 (PAL 25i): intermittent brief picture glitches with no engine-log signature — first seen on 6.5.3, unchanged on 6.5.6 #295 it was read, reasonably, as "the software path runs with no read-ahead". It cannot support that claim in either direction, and the name invites exactly that reading.
• bufferedSessionTime / clock.bufferedPosition is the newest DEMUXED source PTS. It says how far the reader got, not how many decoded frames are waiting for the display.
• [Renderer] isReadyForMoreMediaData=false at enqueue #N is latched to one line per session. It marks the first time the queue filled, which is normal and healthy, not that it stayed full.

So a session can show a full queue at enqueue #8, a healthy demuxed frontier, frameAhead=0.00s, and still drop frames from a 100 ms read, with nothing in the log distinguishing "the cushion was 40 ms" from "the cushion was 2 s and something else broke".

What would settle it

1. Seconds of decoded video actually queued for display: the enqueued-frame PTS frontier minus the synchronizer time, sampled in the periodic memprobe rather than only at milestones. That is the number that decides whether a given read block is survivable.
2. A presented/dropped split on the software path, which is what the Software-path SD MPEG-2 (PAL 25i): intermittent brief picture glitches with no engine-log signature — first seen on 6.5.3, unchanged on 6.5.6 #295 reporter asked for when the defect had no signature.

With those two, the design question underneath becomes answerable rather than a matter of taste: whether the software path should hold a floor of its own instead of inheriting whatever AVSampleBufferVideoRenderer happens to accept, and whether that floor should differ for a remote source and a local one.

No user-visible symptom is attached to this issue on its own. It is the instrument that was missing while #295 was open.

[superuser404notfound]

Shipped in 6.7.0 (5d31dd98, PR #304). Both consumers are bumped.

The memprobe carries three new fields on a software session, and nothing on a native one:

swFrames=753 swAhead=0.26s swDropped=187/749 swDelay=0.00s ... frameAhead=0.00s

swAhead is seconds of decoded video queued ahead of the clock: the newest timestamp the renderer holds, minus the synchronizer. Recorded at admission into the reorder buffer, so it is past the unschedulable-PTS gate and the post-seek skip, and cleared on flush so a backward seek cannot report the distance it travelled as cushion. It is the newest timestamp HELD rather than the newest handed over, or a B-frame run would make the number breathe with the coding pattern instead of the buffer.

swDropped and swDelay come from AVSampleBufferVideoRenderer own metrics, which count frames dropped for missing their display deadline. That is the class our own counters structurally cannot see: we can only count what we refuse.

clock.bufferedPosition also stops mirroring the playhead on a VOD software session and carries the cushion instead. The #54 contract holds and the live frontier still wins where it is larger.

Two things worth stating rather than leaving to be discovered:

The numbers in the run above come from aetherctl play --sw against a headless layer that is in no view hierarchy, and the #298 warning fires in the same session. A 25 percent drop rate there is the harness, not a statement about on-device cushion. The first honest reading of these fields will come off a device.

And this is measurement only. No floor, no target depth, no change to the demux loop back-pressure, which is still whatever AVSampleBufferVideoRenderer accepts. Whether that is too little is exactly what there was no way to say, which is why the instrument came first.