Sentinel seek position used to jump to the live edge of an HLS stream. Roku clips this to the manifest's available range, landing at the live edge.

Maximum behind-live offset (seconds) at which we still consider the user to be at the live edge. Absorbs 1-tick rounding flicker between the integer wall-clock (roDateTime.AsSeconds) and int(m.top.position). Both tick discretely but can be out of phase by up to 1 second depending on calibration alignment, which would otherwise flicker the UI between LIVE and -0:01 every second during normal play.

The largest forward step between two position notifications that still counts as playing (see liveProgressOnPosition). Notifications arrive every 0.5 s (the Video node's default notificationInterval); the headroom is for a busy render thread delivering them late. A larger step is a jump (the live-edge join, a seek) and counts nothing. VideoPlayerView logs every jump and a per-mount summary of the steps it saw, which is the evidence for tuning this.

How much of the stream a mount must have played (see newLiveProgress) for its end or stall to count as a feed that dropped: the count resets, and a stall restarts the channel.

How many times in a row a Live TV channel is restarted after its stream ends without having played healthily, before the player stops restarting it and shows the playback error.

How much of the stream a mount restarted after a stall must play before its own stall restarts the channel again. A restart into a playlist that stopped growing plays what was left past the join before it stalls, and that counts as progress: measured 2026-09-23 on a Stick 4K against 12.1, 19.5 s with 4 s segments (32 s and 64 s windows alike) and 29.6 s with 10 s segments, so it grows with the segment length and soon passes LIVE_RESTART_HEALTHY_MS. Four times the 10 s case.

Apply a scrub-during-pause delta to the accumulated behind-live counter. Forward scrub (positive delta) reduces behind; backward scrub (negative) grows it. Clamped to >= 0 so a forward scrub past the live edge resolves to 0 (live edge).

Build a queue array from a Jellyfin /livetv/channels response and locate the currently-playing channel within it.

Whether a Live TV channel whose stream ended should be restarted, given its count from nextLiveRestartCount.

Compute seconds the user is behind the live edge using a hybrid play/pause model.

Roku's m.top.position for live HLS DVR streams keeps advancing during pause: it tracks the live edge, not the user's playhead. So position-vs-wallclock math cancels out to zero during pause and we have to switch strategies based on state:

During pause: behindLive = accumulated + (now - pausedAtEpoch) Wall-clock-only: independent of position so Roku's auto-advance during pause is invisible to us.

During play: behindLive = (now - epochAtPosition0) - position Position-math: self-correcting on scrubs while playing, where position really tracks the user's playhead.

On the pause-to-play transition the caller re-anchors epochAtPosition0 so play-math continues from the same offset where wall-clock math left off.

scrub adjustments made during the current pause)

The translation key for the error shown when the host gives up on a Live TV channel: a channel that never showed any video since the viewer chose it is not sending any, and one that did has stopped.

A new stream loaded into the same mount (a retry, or an audio or subtitle change that reloads). Its positions are on a timeline of their own, joined at the live edge again, so they cannot be compared with the mark the previous stream left; keeping it would count nothing until the new stream passed the old stream's furthest position. The progress already made stays.

One position notification. A forward step of at most LIVE_PROGRESS_MAX_STEP_MS past the furthest position so far is playing and adds to the progress; a larger one is a jump (the live-edge join, a seek) that moves the mark without counting; a step back (a seek back, a replayed window) counts nothing and leaves the mark where it was. The live-edge seek sentinel is not a position at all.

the caller's debug log

The channel's stream ended. Counts this end (nextLiveRestartCount) and returns whether the channel should be restarted; false means give up and show the error.

A player mount. Only a Live TV restart keeps the budget, so a first mount, a channel switch and a queue advance all start a fresh one.

The channel's stream stalled (VideoPlayerView.bufferCheck saw no buffering progress). Restarts only a mount that had played healthily, the dropped-feed case the restart exists for; any other stall returns false (show the error). Unlike an end, a stall is only detected at least 30 s into the spinner, so the end budget's three restarts would keep a viewer waiting for minutes.

After a stall restart, "healthily" means LIVE_STALL_REPROVE_MS rather than LIVE_RESTART_HEALTHY_MS: a restart into a playlist that stopped growing plays its leftover and stalls again, and with long segments that leftover alone would pass the lower bar every time.

How much of a live stream one player mount has played, for the restart rule: the sum of the small forward steps between position notifications that took the player past the furthest position it had reached. Driven by liveProgressOnPosition from the player's position observer.

Why steps, and not the position at a state change: the first playing reports no real position (measured on a Stick 4K, 12.1: the live-edge seek sentinel in some runs, 0 in others), and a stream that plays until it stalls has no state change in between, so the position there cannot anchor anything. Why only NEW ground: at the end of a playlist that stops growing, the player replays its window before it buffers, so time spent playing called a stale upstream healthy and restarted it forever. Pausing and buffering take no steps, so they count nothing either.

The step fields are diagnostics for LIVE_PROGRESS_MAX_STEP_MS (see VideoPlayerView's log lines).

the furthest position reached (-1 before the first usable one); smallestJumpMs is 0 with no jumps

The Live TV restart budget PlayerHostView carries across its player mounts, since how much a mount played is measured by that mount's player (newLiveProgress). liveRestartOnMount, liveRestartOnEnd and liveRestartOnStall hold the whole rule, including when each field resets, so it can be tested without a player.

isStallRestart: the last restart answered a stall and no mount since has played LIVE_STALL_REPROVE_MS; hasPlayed: some mount since the viewer chose the channel made progress, which decides the error's wording (liveGiveUpCauseKey)

The count of consecutive restarts after a Live TV channel's stream ends.

A live feed that drops mid-stream surfaces as finished, and the player restarts the channel instead of dropping the viewer back to the guide. A stream that ends before it ever plays (an on-demand playlist listed as a channel, joined at its end) also surfaces as finished, and restarting it only loops. So an end after healthy playback resets the count, and any other end adds one; canRestartLiveChannel decides whether that count still allows a restart.

What liveRestartOnEnd and liveRestartOnStall both learn from a mount's progress.

The toast for a RecordProgramTask result: scheduled or cancelled, and whether it worked. A failed result that is not a record reads as a failed cancel, as the task reports it.

Compute the new accumulated baseline after a scrub during pause. Folds the elapsed pause duration into accumulated first so the wall-clock pause counter can be reset from the scrub moment. Otherwise a forward scrub to live edge would still leave the wall-clock counter adding to total behindLive.

Caller is expected to also reset pausedAtEpoch = now after this returns.

Decide whether a video should be tagged as ContentNode contenttype="episode". Tagging "episode" enables the Next-Episode flow in VideoPlayerView.

Episodes and series items are always episodes. Recordings are episodes only when their metadata identifies them as part of a series (seriesId set). A standalone recording of a movie or sports event should not trigger the Next-Episode prompt.

Recordings without a season/episode number but WITH a seriesId still count as series content (for example news bulletins or shows whose EPG omits S/E numbering).