Interface TimelineConfig

Initial visibility of the description (left) pane. Can be changed later with TimelineApi.setDescriptionPaneVisible.

Whether live button is shown below the timecode while live main media is loaded. Its indicator is lit while playback is pinned to the live edge, clicking it seeks to the live edge. Defaults to false.

Live mode only. Seconds of "excess space" manually reserved as a locked/unreachable region past the live edge, absorbing manifest growth without reflowing the timeline until it's used up. When undefined, the locked region is always the automatic minimum (liveEdgeDuration - liveSyncPosition), so every manifest update that grows the edge reflows the timeline.

Its "absorb without reflow" benefit is EVENT-mode-centric: for a CONTINUOUS (sliding-window) stream, liveStartTime drifts on essentially every manifest update regardless of this setting, which alone makes the timeline reflow-eligible — this option only governs whether the extent side of that reflow also grows, not whether a reflow happens at all. liveReflowCadence is the setting that actually throttles reflow frequency for CONTINUOUS streams.

Only ever governs the first reservation (iteration 0, seeded the moment the timeline first observes live state) when liveEdgeBufferSpaceUpdate is also configured — see that option for how the reservation is resolved afterwards, and for the case where this is left undefined but liveEdgeBufferSpaceUpdate is set.

Live mode only. Dynamically resolves a fresh buffer/slack amount for liveEdgeBufferSpace once the currently-reserved amount's slack is actually exhausted, instead of reserving one fixed amount for the life of the stream. Either a plain number (the same reservation reused every time it's resolved), or a function (playerLiveState, currentTime, iteration) => number resolved fresh each time — iteration is a 0-based counter of how many times the reservation has been resolved so far (incremented on every resolution, including this one), so the function can grow/shrink the reservation over the life of the stream, e.g. by iteration count or by playerLiveState/currentTime.

Deliberately not consulted on every manifest update/growth check — only when there's a fresh reservation to make: the initial one (iteration 0, seeded the moment the timeline first observes live state) and, from then on, only once growth has consumed all of the previously reserved slack (iteration 1, 2, ...). While slack from the current reservation remains, that growth is absorbed silently and this option isn't consulted at all — see liveEdgeBufferSpace for what "slack" means.

Precedence, per resolution:

• Iteration 0 (the initial reservation): liveEdgeBufferSpace is used when configured; only when it's undefined does this option get consulted for the very first value.
• Every later iteration (each time the current reservation's slack runs out): this option is consulted first — a number is used as-is, a function is called with the current (playerLiveState, currentTime, iteration). Only when this option is undefined, or its function returns undefined, does the static liveEdgeBufferSpace apply instead — so a plain liveEdgeBufferSpace with no update function behaves exactly as before: one fixed reservation, unchanged for the life of the stream.

If neither option is configured, there is no reserved buffer at all — the historical default behavior described in liveEdgeBufferSpace.

CONTINUOUS live mode only. Seconds of "evicted but still shown" slack the rendered timeline's left bound is allowed to lag behind the true, current live start by, at all times — a continuously-maintained rolling cap, not a one-time batch flush.

Undefined (default): today's behavior — the left bound tracks the true live start exactly, on every reflow. The timeline never shows anything the player can no longer actually seek to.

Set: the left bound trails the true live start by up to (never more than) this many seconds, advancing incrementally alongside it rather than jumping — so at most this many seconds of otherwise-evicted content stays visible/scrollable-to at any given moment. This cap is enforced every tick regardless of liveReflowCadence (an unrelated, extent-growth-only throttle) — "at most N seconds" is a hard guarantee. The gap can still be closed completely on demand, independent of the cap, via TimelineApi.evictLiveHistory. Either way, emits TimelineEventType.TIMELINE_LIVE_ORIGIN_ADVANCED whenever the left bound actually advances, so lanes holding onto now-unreachable items (e.g. thumbnails, which are never pruned upstream) can release them.

Live mode only. Minimum accumulated growth of liveEdgeDuration (seconds) required between geometry reflows (timecoded-width resize/reposition) while live. Segment/manifest updates that arrive in between are absorbed silently — the rendered width, scroll position, and every derived coordinate (ticks, markers, playhead) stay exactly as they were — until accumulated growth since the last reflow reaches this cadence, at which point a single reflow catches up all of the held growth at once. The live-edge-proximity overlay keeps tracking every update regardless of this setting. When undefined, every live-state update that changes the geometry reflows immediately (the previous default behavior).

Live mode only. When true, an automatic scroll-to-live-edge snap animates the scroll position over scrollEasingDuration instead of jumping there instantly. The timeline's width still resizes immediately to fit the new extent — only the follow-scroll itself eases. Manual scrolling/zooming is unaffected. Defaults to false (instant snap).

Live mode only. A live reflow whose natural (pixels-per-second-preserving) width would exceed zoomMax would otherwise just get pinned at zoomMax and stay wedged there for the rest of the stream, since every further reflow keeps demanding an even wider width, always re-clamped to the same max. When that happens, the zoom instead resets to this percentage — a usable zoom level rather than staying pinned at an increasingly meaningless max. Clamped down to zoomMax itself if a custom zoomMax is configured below this value.

Defines the maximal timeline zoom value. When undefined or set to Infinity, maximal zoom restriction is disabled.