Tune LL-HLS for low-latency
without losing the live edge.

Player sees PART inflight but the next PART arrives 0.6–0.9s after the previous one instead of the declared PART-TARGET=0.33. Latency rises sharply; the player stutters because it waits for parts that the encoder dragged longer.

Encoder GOP slipped out of rhythm with the partial-segment packager. EXT-X-PART-INF declared PART-TARGET=0.33 but the encoder emits 2.5s GOPs under load, and the packager is forced to fill each PART with ~0.66s of media. part.timing_consistent flags the proportional drift.

Tighten the encoder cadence so GOP duration is an exact multiple of PART-TARGET (PART-TARGET=0.33 with GOP=2.0 aligns as 6 parts per GOP). Reconfigure the packager to refresh PART-DURATION each cycle; the part.timing_consistent probe reports bounded jitter once the cadence is in lock-step.

Edge logs show the player issuing a full BLOCKING playlist GET every refresh instead of a delta request. Cache misses spike; bandwidth spent on each refresh is 4–5KB when ~80B would have been enough.

The client lost its delta cursor — usually because _HLS_msn/_HLS_part drifted, the server missed a delta window, or the client believed the playlist was stale and triggered a reload. CAN-BLOCK-RELOAD lets the server hold the connection; the client gave up too early.

Tune the delta-timeout on the packager to match the BLOCKING budget (default 3s); when a BLOCKING request returns the full playlist, the server-control_can_block_reload probe should flip to fail and streamwake should report the over-fetch ratio.

A preload hint is in the playlist — TYPE=PART for the next part the encoder is about to publish — but the SERVER-CONTROL block says CAN-PRELOAD-BEFORE=false (or is missing). Players that trust the hint issue a request, the 404 fires, and the player mis-attributes the failure.

Packager inconsistency: the hint tag is being emitted by the partial-segment emitter, but the SERVER-CONTROL block was authored by a different upstream module that does not "see" the same publish pipeline. The two pieces disagree on whether preload is allowed.

Make SERVER-CONTROL authoritative — every playlist writer must read CAN-PRELOAD-BEFORE from the same source as the hint emitter. preload.can_preload_hint should fail across any playlist where the hint and the SERVER-CONTROL disagree.

Every few segments the player drops into a discontinuity. PDT jumps by 0.5–1.0s at the boundary, even though no EXT-X-DISCONTINUITY tag is in the playlist. ABR ladder descends because the time mismatch breaks the buffer math.

TARGETDURATION=6 was set but the packager emitted 6.5s segments. PART-TARGET=0.33 over 6s = 18 parts, but 18 × 0.33 = 5.94 < 6, leaving ~60ms unaccounted for; the packager rolled the leftover into the next segment, shifting PDT.

Either tune PART-TARGET so the residual is divisible (18 × 0.33 = 5.94 → PART-TARGET=0.333 for 18 parts = 6.00), or lower TARGETDURATION to PART-TARGET * floor(segment / PART-TARGET). The part.timing_consistent probe must flag mismatches between TARGETDURATION and PART-TARGET * N.

Player reports frequent re-buffer events at the start of every sixth part. Codec profiler shows a keyframe mid-PART, so the player rolls forward to the next IDR but the partial append is missing the leading frame.

Encoder GOP period and packager PART cadence are not locked. The encoder emits a 2.0s GOP, but the packager is splitting on inference — parts occasionally start in the middle of a frame. gop.boundary_aligned fails whenever a keyframe index lands inside a PART instead of at its boundary.

Lock the encoder to a fixed GOP that divides evenly into TARGETDURATION, hand that cadence to the packager, and force partial splitters to start at every keyframe. The gop.boundary_aligned probe flips to pass when every PART starts with an IDR.

The variant playlist lacks the SERVER-CONTROL block entirely (no PART-HOLD-BACK, no CAN-BLOCK-RELOAD). Players default to legacy HLS timing, stop asking for delta updates, and revert to a full BLOCKING request every refresh.

The packager detected the partial-segment emission but did not emit the SERVER-CONTROL block at the variant head. Most often a config-flag (SERVER-CONTROL_ENABLED=false), or the playlist is being proxied by an upstream cache that dropped the line.

Make the SERVER-CONTROL block a required emission on every LL-HLS variant. server_control.target_latency_window should fail on any variant missing CAN-BLOCK-RELOAD or PART-HOLD-BACK — both fields are required for the delta vs reload decision.

Latency glass shows either 8–10 seconds of glass-to-glass delay (over-buffered) or 0.3 seconds (starved, dropping in the playback core). Both happen on the same source within minutes of each other.

PART-HOLD-BACK was tuned once and never re-tuned. As segment duration shifted (4s → 6s) and GOP cadence was changed to accommodate higher resolutions, the original PART-HOLD-BACK value either over-anchored the playback head or let it chase the live edge too aggressively.

Tune PART-HOLD-BACK against the measured playback-head window — the agent reports the actual window in server_control.target_latency_window. As a rule, PART-HOLD-BACK should sit between 1.0× and 1.5× the measured jitter; tune up if over-buffered, down if starved.

Player keeps asking for a part the server already deleted from the playlist. Server returns 410 Gone or a full reload. Cursor TTL is permanently wrong because the player believes it is still behind.

Client cursor (_HLS_msn/_HLS_part) advanced past the server's bookkeeping window — usually because the client was paused and the server removed 30+ parts from the tail of the playlist while paused. The cursor is no longer valid; the server cannot fulfill a delta, so it returns 410.

Force a full playlist reload after any pause > PART-HOLD-BACK × 3, or have the agent monitor part-cursor deltas and prompt a reload proactively. The playlist.delta_updates probe should treat 410 responses as fail and run a fresh playlist fetch.

PLAYER_LOGS show playlist_load timeout at 6s; the player stalls for the reload window, then attempts a full BLOCKING request, which itself times out. Latency spikes to ~12s before the first frame re-paints.

CAN-BLOCK-RELOAD=YES but the BLOCKING budget is too short for the edge round-trip — typically because edge POP RTT rose under load, or the playlist itself grew past the budget due to long EXTINF lists. blocking-playlist.timeout fires before the playlist returns.

Raise the BLOCKING budget (the HLS spec default is 3 * TARGETDURATION), or move the player to a delta-first workload under higher POP RTT. blocking-playlist.timeout should flag timeouts shorter than 3× TARGETDURATION + 1s RTT headroom.

Player preloads a part the encoder already finished; cache miss for the part, then a redundant fetch right after. HTTP request rate roughly doubles on the live edge during preload windows.

Packager emitted the preload hint just before becoming aware that the part had already been published (only possible with a 0.0s PART-TARGET or an encoder publishing ahead of PART-HOLD-BACK). The hint references a URL the player no longer needs.

Filter hints against the published MSD — preload.can_preload_hint rejects any hint whose URI is already covered by an EXTINF in the playlist. The probe should report hint_vs_published_uri diff every cycle; resolve by aligning the packager pipeline.