@oddin-gg/havik-player 2.22.1 → 2.23.1

package/dist/index.d.cts

@@ -224,6 +224,33 @@ export declare interface CreatePlayerOptions {
      * true` (hls.js's own poller) caps to the covering rung with no headroom.
      */
     sizeCapHeadroom?: number;
+    /**
+     * Adaptive live hold-back (hls.js engine): raise the live-sync target for a
+     * session whose part fetches are slow, instead of letting it stall. A
+     * viewer far from the origin plays from a local edge whose every cache
+     * miss on a 0.5 s part is a cross-continent fetch (250-310 ms per part on
+     * the global slot from South America, Canada/Mexico and APAC, against
+     * 44 ms in Europe, 2026-10-30), so the fetch cycle outruns the part
+     * cadence and the 2 s buffer drains: 3-13% rebuffer there against under
+     * 1% in the US and Europe. The engine times the session's own part
+     * fetches (first byte, as a share of the part's duration, over a 10 s
+     * window): a window whose p95 is at or above 60% AND whose median is at
+     * or above 40%, two 3 s ticks running, steps the target up 0.5 s, to
+     * `adaptiveHoldBackCeiling` at most; a p95 under 40% for 60 s steps it
+     * back down. A session whose fetches are fast never moves. Each
+     * move fires `latencytargetchange`, counts in `holdBackSteps`, and shows
+     * in `targetLatencySeconds` (and the heartbeat's target latency).
+     * Default: true. Live/LL only.
+     */
+    adaptiveHoldBack?: boolean;
+    /**
+     * Highest live-sync target the adaptive hold-back may step to, in seconds.
+     * Default: 3.5 (a far session that stalls drifts to ~6 s anyway, so a
+     * steady 3.5 s is the better trade for a latency-sensitive viewer). Kept
+     * under the drift ceiling; at or below `liveLatencyTarget` it disables the
+     * stepping.
+     */
+    adaptiveHoldBackCeiling?: number;
     /**
      * DRM cold start: download the first init segment and parts while the
      * first key is still being acquired, instead of after it (hls.js waits for
@@ -796,6 +823,28 @@ export declare interface LiveStateSubscription {
     close(): void;
 }
 
+/** Payload of the `latencytargetchange` event: an SDK-initiated move of the
+ *  live-sync target (never a caller's own `liveLatencyTarget`). */
+export declare interface LiveTargetChange {
+    /** The target hls.js now converges to, in seconds. */
+    targetSeconds: number;
+    /** The target it replaced, in seconds. */
+    previousSeconds: number;
+    reason: LiveTargetReason;
+}
+
+/**
+ * Why the SDK moved the live-sync target (the `latencytargetchange` event).
+ *  - `slow-fetches`: the adaptive hold-back stepped the target UP because the
+ *    session's part fetches kept taking a large share of each part's duration.
+ *  - `fast-fetches`: it stepped the target back DOWN after fetches stayed fast.
+ *  - `connection-rtt`: the browser reported a high round-trip estimate at
+ *    start, so the session began one step above the configured target.
+ *  - `futile-chase`: a catch-up at full rate was not gaining on the live edge,
+ *    so the target was parked where playback actually is.
+ */
+export declare type LiveTargetReason = 'slow-fetches' | 'fast-fetches' | 'connection-rtt' | 'futile-chase';
+
 /**
  * `pending` is the catalog's "kickoff has passed, the stream is being
  * packaged" — not playable yet, `live` expected within seconds to minutes. It
@@ -965,6 +1014,10 @@ export declare interface PlaybackStats {
      *  gaining on the edge (hls.js engine only). After a move, `targetLatencySeconds`
      *  carries the new target and drift/atLiveEdge read against it. */
     liveRetargets?: number;
+    /** Times the adaptive hold-back moved the live-sync target this session, up
+     *  or down (hls.js engine only; see `adaptiveHoldBack`). `targetLatencySeconds`
+     *  carries the current target. */
+    holdBackSteps?: number;
     /** Times the ABR ceiling was stepped down because the device kept dropping
      *  frames on the rendition it played (hls.js engine only). */
     fpsDownCaps?: number;
@@ -1062,7 +1115,7 @@ export declare interface Player {
     destroy(): void;
 }
 
-export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'stats' | 'statechange';
+export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'latencytargetchange' | 'stats' | 'statechange';
 
 export declare interface PlayerEventMap {
     ready: void;
@@ -1092,6 +1145,13 @@ export declare interface PlayerEventMap {
     texttrackchange: number;
     /** Picture-in-Picture entered (true) or exited (false). */
     pipchange: boolean;
+    /**
+     * The SDK moved the live-sync target itself (hls.js engine): the adaptive
+     * hold-back stepped it for slow or fast part fetches or a high
+     * browser-reported RTT, or a futile catch-up parked it where playback is.
+     * Never fired for the caller's own `liveLatencyTarget`.
+     */
+    latencytargetchange: LiveTargetChange;
     stats: PlaybackStats;
     statechange: PlayerState;
 }

package/dist/index.d.ts

@@ -224,6 +224,33 @@ export declare interface CreatePlayerOptions {
      * true` (hls.js's own poller) caps to the covering rung with no headroom.
      */
     sizeCapHeadroom?: number;
+    /**
+     * Adaptive live hold-back (hls.js engine): raise the live-sync target for a
+     * session whose part fetches are slow, instead of letting it stall. A
+     * viewer far from the origin plays from a local edge whose every cache
+     * miss on a 0.5 s part is a cross-continent fetch (250-310 ms per part on
+     * the global slot from South America, Canada/Mexico and APAC, against
+     * 44 ms in Europe, 2026-10-30), so the fetch cycle outruns the part
+     * cadence and the 2 s buffer drains: 3-13% rebuffer there against under
+     * 1% in the US and Europe. The engine times the session's own part
+     * fetches (first byte, as a share of the part's duration, over a 10 s
+     * window): a window whose p95 is at or above 60% AND whose median is at
+     * or above 40%, two 3 s ticks running, steps the target up 0.5 s, to
+     * `adaptiveHoldBackCeiling` at most; a p95 under 40% for 60 s steps it
+     * back down. A session whose fetches are fast never moves. Each
+     * move fires `latencytargetchange`, counts in `holdBackSteps`, and shows
+     * in `targetLatencySeconds` (and the heartbeat's target latency).
+     * Default: true. Live/LL only.
+     */
+    adaptiveHoldBack?: boolean;
+    /**
+     * Highest live-sync target the adaptive hold-back may step to, in seconds.
+     * Default: 3.5 (a far session that stalls drifts to ~6 s anyway, so a
+     * steady 3.5 s is the better trade for a latency-sensitive viewer). Kept
+     * under the drift ceiling; at or below `liveLatencyTarget` it disables the
+     * stepping.
+     */
+    adaptiveHoldBackCeiling?: number;
     /**
      * DRM cold start: download the first init segment and parts while the
      * first key is still being acquired, instead of after it (hls.js waits for
@@ -796,6 +823,28 @@ export declare interface LiveStateSubscription {
     close(): void;
 }
 
+/** Payload of the `latencytargetchange` event: an SDK-initiated move of the
+ *  live-sync target (never a caller's own `liveLatencyTarget`). */
+export declare interface LiveTargetChange {
+    /** The target hls.js now converges to, in seconds. */
+    targetSeconds: number;
+    /** The target it replaced, in seconds. */
+    previousSeconds: number;
+    reason: LiveTargetReason;
+}
+
+/**
+ * Why the SDK moved the live-sync target (the `latencytargetchange` event).
+ *  - `slow-fetches`: the adaptive hold-back stepped the target UP because the
+ *    session's part fetches kept taking a large share of each part's duration.
+ *  - `fast-fetches`: it stepped the target back DOWN after fetches stayed fast.
+ *  - `connection-rtt`: the browser reported a high round-trip estimate at
+ *    start, so the session began one step above the configured target.
+ *  - `futile-chase`: a catch-up at full rate was not gaining on the live edge,
+ *    so the target was parked where playback actually is.
+ */
+export declare type LiveTargetReason = 'slow-fetches' | 'fast-fetches' | 'connection-rtt' | 'futile-chase';
+
 /**
  * `pending` is the catalog's "kickoff has passed, the stream is being
  * packaged" — not playable yet, `live` expected within seconds to minutes. It
@@ -965,6 +1014,10 @@ export declare interface PlaybackStats {
      *  gaining on the edge (hls.js engine only). After a move, `targetLatencySeconds`
      *  carries the new target and drift/atLiveEdge read against it. */
     liveRetargets?: number;
+    /** Times the adaptive hold-back moved the live-sync target this session, up
+     *  or down (hls.js engine only; see `adaptiveHoldBack`). `targetLatencySeconds`
+     *  carries the current target. */
+    holdBackSteps?: number;
     /** Times the ABR ceiling was stepped down because the device kept dropping
      *  frames on the rendition it played (hls.js engine only). */
     fpsDownCaps?: number;
@@ -1062,7 +1115,7 @@ export declare interface Player {
     destroy(): void;
 }
 
-export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'stats' | 'statechange';
+export declare type PlayerEvent = 'ready' | 'waiting' | 'playing' | 'buffering' | 'paused' | 'ended' | 'error' | 'warning' | 'autoplayblocked' | 'qualitychange' | 'audiotrackchange' | 'texttrackchange' | 'pipchange' | 'latencytargetchange' | 'stats' | 'statechange';
 
 export declare interface PlayerEventMap {
     ready: void;
@@ -1092,6 +1145,13 @@ export declare interface PlayerEventMap {
     texttrackchange: number;
     /** Picture-in-Picture entered (true) or exited (false). */
     pipchange: boolean;
+    /**
+     * The SDK moved the live-sync target itself (hls.js engine): the adaptive
+     * hold-back stepped it for slow or fast part fetches or a high
+     * browser-reported RTT, or a futile catch-up parked it where playback is.
+     * Never fired for the caller's own `liveLatencyTarget`.
+     */
+    latencytargetchange: LiveTargetChange;
     stats: PlaybackStats;
     statechange: PlayerState;
 }