Sequential-origin sources: one unranged connection, native routing, and an append playlist with real durations

[tschuegy]

Problem

IPTV timeshift/catch-up archives are served by origins that fabricate HTTP range answers: any Range: bytes=X-Y gets a plausible-looking 206 + Content-Range: bytes X-Y/total, but the body is positioned on a coarse internal chunk boundary rather than byte X. Live probes against a real panel showed a request for offset 524288 returning the bytes of offset 0, suffix ranges returning the first N bytes, and range ends ignored outright. Only byte 0 is addressable, deterministically.

Through the existing reader this produced three device-visible failures on catch-up playback:

1. The 32 MB range rotations spliced ~1.9 s of misplaced content into every reconnect (mpegts Packet corrupt, negative audio packet durations, audio desync roughly once a minute).
2. FFmpeg's tail-read duration estimate ran against fabricated offsets and probed a 135-min window as 9.5 h.
3. Even with a clean sequential read, the static VOD plan's uniform EXTINF:4.000 was a lie for archives whose GOP cadence does not divide the cut target: a 1.92 s-GOP channel cut eleven 3.84 s segments and one 5.76 s segment per 48 s cycle, all advertised as 4.000, and AVPlayer on tvOS 26 visibly jumped ~1.8 s at every resync while every queue metric read clean. (A sibling channel whose keyframes happen to sit on the 4 s grid played the same pipeline flawlessly - that A/B is what finally pinned it.)

Change

Four commits, each standing on the previous:

• fix(io) - LoadOptions.sequentialOrigin declares the shape (headers cannot expose it, so it is a caller declaration, not a probe): the reader routes onto its existing forward-only streaming mode - one long-lived unranged GET, no suffix/tail probes, no size probe, no detours, no byte-offset reconnects, pb non-seekable. A connection that dies short of its advisory Content-Length reports EIO instead of EOF (EOF reads as end-of-media, which hosts deliberately never retry), and the Loopback-HLS: the final segment of a long 4K DV title never completes at EOM — AVPlayer parks ~0.1s from the end (WaitingToMinimizeStalls) → -12889; resuming into the tail can't start a master #169 VOD readError revive is not admitted (its fresh demuxer could only reopen from byte 0 and then fails its anchor seek, burning a slot on connection-capped panels). The paired declaredDurationSeconds carries the caller-known window length with the highest precedence in the AE#105 duration chain. aetherctl play grows --sequential-origin / --declared-duration.
• fix(routing) - a sequential origin keeps the native path: every reason the forward-only rule forces software (cue prewarm, segment seeks, size probes) is already answered for the explicit declaration, and the producer reads the archive linearly from byte 0 exactly like a live session does. Declared-interlaced archives still route software via the field-order policy (the Field-order routing sends progressive-in-interlaced-carriage (PsF) H.264 to software for no visual benefit — #220 reprices the stated cost #232 refute probe stays seekable-only: its sample cannot be rewound on a sequential reader).
• fix(hls) - sequential sessions render their media playlist the way the live path always has: only finalized segments, each with the duration actually muxed, as an append-only EVENT playlist that completes with ENDLIST at true source EOF. The server holds the first playlist until the startup segments exist (mirrors the live gate). Two host-facing seams from the growing playlist are closed at the engine: a caller-declared duration outranks the item's, and a sequential session with no resume anchor queues a post-readiness seek to 0 through the iOS: quick app switches pay a full pipeline rebuild — grace period before paused-background teardown, warm reload, deferred pre-ready seeks, public readiness signal #127 replay (AVPlayer defaults an EVENT playlist to edge-minus-holdback and re-anchors there after the load-time seek).
• fix(hls) - the finalize reports pair capture and duration order-independently (the muxer rotation can fire off an audio packet crossing the boundary before the first video packet of the new segment has recorded its start), plan indices a long GOP skipped report as zero-duration holes the renderer omits, and a small reorder buffer keeps the provider's strictly-contiguous append API satisfied.

Verification

• SequentialOriginReaderTests (7 tests) against an extended ThrottledOriginServer (now logs Range-header presence - a range-less GET was indistinguishable from bytes=0- - and gains a serveThenDrop directive for the short-body EIO case): exactly one unranged request past the 32 MB rotation point, EIO on short body, EOF on clean end, profile plumbing, duration precedence.
• Full suite green (1638 tests).
• Device (tvOS 26.6, Apple TV 4K, real panel): a 720p50 archive and a 1080i-sourced 1.92 s-GOP archive both play clean end-to-end; the served playlist reads EXTINF:5.760/3.840 matching the muxed media exactly; start lands at 0; the scrubber shows the declared window length.

The sequential declaration deliberately leaves scrubber seeking unavailable (byte seeking never worked against a lying origin - it was silently wrong); the follow-up story for these sources is app-side re-request with a shifted Xtream start timestamp.

🤖 Generated with Claude Code