SW path: fold PTS discontinuities on forward-only VOD, decouple audio decode-ahead from the video gate

[tschuegy]

Problem

Two SW-path weaknesses surfaced while chasing an IPTV catch-up bug on device (tvOS 26.6), both independent of the source that exposed them:

1. The live PTS-discontinuity fold is gated isLive, and non-live sessions run unprotected. A forward-only VOD source (chunked timeshift archive) restarted its timestamps at PTS ~0 every ~85 s; FFmpeg's 33-bit wrap correction read the -2718 s jump as +92726 s, the renderer waited 25 hours for the frame's display time, and the video queue died with FigVideoQueueRemote -12080 - picture and sound frozen ~90 s into every session.
2. The combined demux loop paces everything on the video renderer's ~10-frame queue, so interleaved audio can never build more than ~0.3 s of lead over the synchronizer clock (the master clock). Any decode/deinterlace jitter beyond that starves the audio renderer and the clock leaps; a timeline gap lets the free-running clock run away while the picture freezes. The DVR feeder arm has AudioLookaheadPolicy for exactly this; the combined loop had nothing.

Change

• fix(sw) fold - the discontinuity fold gate widens to the new pure decision shouldFoldTimeline(isLive:sourceSeekable:): live folds as before, and a forward-only non-live source folds too (its timeline is served as-is and a non-seekable pb offers no seek-based recovery). Seekable VOD keeps its trusted container timeline untouched. Seams log per occurrence with a soft cap of 20 lines.
• fix(sw) audio decoupling - video packets park in a bounded FIFO (drained at the renderer's pace) while audio keeps decoding up to AudioLookaheadPolicy.targetLeadSeconds ahead of the clock, and a genuine audio underrun pauses the clock for a rebuffer via the same policy the DVR feeder uses, with an everHadLead latch so exactly-realtime origins do not eat a spurious pause at session start. At a fold seam the parked pre-seam tail is decoded before the flush drops its reference chain. Live-without-ring sessions keep the historical lockstep pacing.
• diag(sw) - the SW path gains a 1 Hz [SWDiag] line (clock + delta, decoded-audio lead, parked depth, rebuffer state, the display layer's own drop counter, accumulated render delay with per-second delta, queue-target status, surface state, isReadyForDisplay). The native path has LagDiag; SW sessions only had the 30 s memprobe, which is too coarse to see the clock leaps and layer-drop bursts a stuttering session is made of. It also names a headless-harness artifact: a never-bound layer (surf=DETACHED) drops ~8 frames/s that a bound one does not.

Verification

• SWTimelineFoldTests pins the fold decision; full suite green (1632 tests).
• Device: with the fold active, the chunked archive's seams fold cleanly instead of freezing into -12080; [SWDiag] on a healthy session reads dclk=1.00, aLead 3-5 s sawtooth, layerDrop flat, delay=0.00.
• On an M-series Mac via aetherctl play: clock exact across 5+ minutes, no rebuffer churn on fast origins, rebuffer pause/resume behaves on origins that deliver below realtime.

🤖 Generated with Claude Code