What should the engine do?
Problem
The loopback HLS session hard-caps forward buffering at 10 segments (~40–60 s):
HLSSegmentProducer.bufferAheadSegments = 10, coupled with the SegmentCache forward
window. A host cannot buffer further ahead — AVPlayerItem.preferredForwardBufferDuration
is irrelevant past the window the loopback publishes/serves, because the producer simply
stops demuxing ahead (backpressure).
Use case: a user-facing "generous / unlimited buffer" playback setting for dropout-robust
playback on flaky networks. On the direct-play path this setting can never exceed the
engine's window today.
Proposal
New LoadOptions.forwardBufferSegments: Int? (nil = historical 10), plumbed via a single
HLSVideoEngine.forwardWindowSegments value into both coupled spots — producer
race-ahead and cache forward window stay identical by construction (a drift between the
two is exactly what stalls AVPlayer, per the SegmentCache docs).
Suggested engine-side clamp 4...150:
- below 4, AVPlayer's own ~5–7-segment prefetch would starve (
LiveWindowSizing.minSafeSegments rationale);
- above 150 (~10 min at 4 s segments, ~1.5 GB disk at 4K HEVC ≈ 10 MB/segment) the disk
and ahead-of-time demux cost stops being worth it.
Ignored for nativeRemoteHLS (AVPlayer talks to the remote server directly).
Patch
A ready, syntax-checked patch against current main (4.8.0-prep, ab93219) is attached:
0001-forwardBufferSegments.patch — 4 files, +45/−9, purely additive (all new parameters
default to today's behavior; no call-site or ABI breakage for existing hosts).
0001-forwardBufferSegments.patch
Motivating media or use case
Not one specific file — a robustness/UX scenario: the host app (a Jellyfin client) exposes a user-facing buffer setting ("Unlimited / 2 minutes / System"). Users watch high-bitrate direct-play remuxes (e.g. 4K HEVC at 40–80 Mbit/s) from a remote Jellyfin server over fluctuating links — WLAN edge cases, cellular, hotel/train Wi-Fi. Brief throughput dips longer than the current window stall playback: the loopback publishes/serves at most 10 segments (~40–60 s) ahead, the producer parks on backpressure, and AVPlayerItem.preferredForwardBufferDuration cannot buy more than the window regardless of how much headroom the connection has while it's healthy. With a configurable window (e.g. 150 segments ≈ 10 min on disk), the session could pre-buffer aggressively during good stretches and ride out multi-minute dropouts — the "Unlimited" setting would then work on the direct-play path the way it already does for transcoded HLS, where AVPlayer manages its own forward buffer against the origin.
Area
Public API surface
Host app / integration context
No response
Would you be willing to open a PR?
Maybe, with guidance
What should the engine do?
Problem
The loopback HLS session hard-caps forward buffering at 10 segments (~40–60 s):
HLSSegmentProducer.bufferAheadSegments = 10, coupled with theSegmentCacheforwardwindow. A host cannot buffer further ahead —
AVPlayerItem.preferredForwardBufferDurationis irrelevant past the window the loopback publishes/serves, because the producer simply
stops demuxing ahead (backpressure).
Use case: a user-facing "generous / unlimited buffer" playback setting for dropout-robust
playback on flaky networks. On the direct-play path this setting can never exceed the
engine's window today.
Proposal
New
LoadOptions.forwardBufferSegments: Int?(nil = historical 10), plumbed via a singleHLSVideoEngine.forwardWindowSegmentsvalue into both coupled spots — producerrace-ahead and cache forward window stay identical by construction (a drift between the
two is exactly what stalls AVPlayer, per the SegmentCache docs).
Suggested engine-side clamp 4...150:
LiveWindowSizing.minSafeSegmentsrationale);and ahead-of-time demux cost stops being worth it.
Ignored for
nativeRemoteHLS(AVPlayer talks to the remote server directly).Patch
A ready, syntax-checked patch against current
main(4.8.0-prep, ab93219) is attached:0001-forwardBufferSegments.patch— 4 files, +45/−9, purely additive (all new parametersdefault to today's behavior; no call-site or ABI breakage for existing hosts).
0001-forwardBufferSegments.patch
Motivating media or use case
Not one specific file — a robustness/UX scenario: the host app (a Jellyfin client) exposes a user-facing buffer setting ("Unlimited / 2 minutes / System"). Users watch high-bitrate direct-play remuxes (e.g. 4K HEVC at 40–80 Mbit/s) from a remote Jellyfin server over fluctuating links — WLAN edge cases, cellular, hotel/train Wi-Fi. Brief throughput dips longer than the current window stall playback: the loopback publishes/serves at most 10 segments (~40–60 s) ahead, the producer parks on backpressure, and AVPlayerItem.preferredForwardBufferDuration cannot buy more than the window regardless of how much headroom the connection has while it's healthy. With a configurable window (e.g. 150 segments ≈ 10 min on disk), the session could pre-buffer aggressively during good stretches and ride out multi-minute dropouts — the "Unlimited" setting would then work on the direct-play path the way it already does for transcoded HLS, where AVPlayer manages its own forward buffer against the origin.
Area
Public API surface
Host app / integration context
No response
Would you be willing to open a PR?
Maybe, with guidance