Interstitials live start, buffering, and manager fixes and docs update (#7030)

* Interstitials improvements
- Add interstitialPlayer to InterstitialsManager and simplify interface
- Fix and cover expected playback state in interstitial event callbacks (where currentTime is derived from transitional controller state)
- Fix live start in append-in-place interstitial seeking to second start position when primary starts buffering after starting in interstitial
- Simplify playout-limit handling in asset player
- Add padding to flush front buffer call (prevents start of audio segment from being removed in Safari)
- Fix an issue where buffering an interstitial in place gets stuck when the video buffer is full, but the audio buffer is not (use combined buffer in stream-controller when there is no alt-audio source)
- Fix typos (Interstitals > Interstitials)

* Add `interstitialsManager.interstitialPlayer.assetPlayers` tests - verify playingIndex player is present for relevant asset events

Author: robwalch

.eslintrc.js

@@ -18,7 +18,7 @@ module.exports = {
     __USE_VARIABLE_SUBSTITUTION__: true,
     __USE_M2TS_ADVANCED_CODECS__: true,
     __USE_MEDIA_CAPABILITIES__: true,
-    __USE_INTERSTITALS__: true,
+    __USE_INTERSTITIALS__: true,
   },
   // see https://github.com/standard/eslint-config-standard
   // 'prettier' (https://github.com/prettier/eslint-config-prettier) must be last

api-extractor/report/hls.js.api.md

@@ -2145,6 +2145,8 @@ export class HlsAssetPlayer {
     // (undocumented)
     resumeBuffering(): void;
     // (undocumented)
+    get startOffset(): number;
+    // (undocumented)
     get timelineOffset(): number;
     set timelineOffset(value: number);
     // (undocumented)
@@ -2711,6 +2713,22 @@ export interface InterstitialEventWithAssetList extends InterstitialEvent {
 // @public (undocumented)
 export type InterstitialId = string;
 
+// Warning: (ae-missing-release-tag) "InterstitialPlayer" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
+//
+// @public (undocumented)
+export interface InterstitialPlayer {
+    // (undocumented)
+    assetPlayers: (HlsAssetPlayer | null)[];
+    // (undocumented)
+    currentTime: number;
+    // (undocumented)
+    duration: number;
+    // (undocumented)
+    playingIndex: number;
+    // (undocumented)
+    scheduleItem: InterstitialScheduleEventItem | null;
+}
+
 // Warning: (ae-missing-release-tag) "InterstitialsBufferedToBoundaryData" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
 //
 // @public (undocumented)
@@ -2805,12 +2823,12 @@ export interface InterstitialsManager {
     // (undocumented)
     bufferingItem: InterstitialScheduleItem | null;
     // (undocumented)
-    bufferingPlayer: HlsAssetPlayer | null;
-    // (undocumented)
     events: InterstitialEvent[];
     // (undocumented)
     integrated: PlayheadTimes;
     // (undocumented)
+    interstitialPlayer: InterstitialPlayer | null;
+    // (undocumented)
     playerQueue: HlsAssetPlayer[];
     // (undocumented)
     playingAsset: InterstitialAssetItem | null;
@@ -2819,15 +2837,11 @@ export interface InterstitialsManager {
     // (undocumented)
     playingItem: InterstitialScheduleItem | null;
     // (undocumented)
-    playout: PlayheadTimes;
-    // (undocumented)
     primary: PlayheadTimes;
     // (undocumented)
     schedule: InterstitialScheduleItem[];
     // (undocumented)
     skip: () => void;
-    // (undocumented)
-    waitingIndex: number;
 }
 
 // Warning: (ae-missing-release-tag) "InterstitialsPrimaryResumed" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)
@@ -4131,7 +4145,6 @@ export type PlayheadTimes = {
     currentTime: number;
     duration: number;
     seekableStart: number;
-    seekTo: (time: number) => void;
 };
 
 // Warning: (ae-missing-release-tag) "PlaylistContextType" is part of the package's API, but it is missing a release tag (@alpha, @beta, @public, or @internal)

build-config.js

@@ -73,7 +73,7 @@ const buildConstants = (type, additional = {}) => ({
     __USE_MEDIA_CAPABILITIES__: JSON.stringify(
       type === BUILD_TYPE.full || addMediaCapabilitiesSupport,
     ),
-    __USE_INTERSTITALS__: JSON.stringify(
+    __USE_INTERSTITIALS__: JSON.stringify(
       type === BUILD_TYPE.full || addInterstitialSupport,
     ),
 

docs/API.md

@@ -2019,34 +2019,79 @@ HLS.js supports playback of X-ASSET-URI and X-ASSET-LIST m3u8 playlists schedule
 
 The data includes the list of Interstitial events with their asset lists, the schedule of event and primary segment items, information about which items and assets are buffering and playing, the player instance currently buffering media, and the queue of players responsible for the streaming of assets.
 
-Use `skip()` to skip the current interstitial. Use `primary`, `playout`, and `integrated` to get `currentTime`, `duration` and to seek along the respective timeline.
+Use `skip()` to skip the current interstitial.
+Use `primary` and `integrated` playhead objects to get `currentTime`, `duration` and to seek along the respective timeline.
+Use `interstitialPlayer` to get active intersititial info (playing or upcoming buffering break) like `currentTime`, `duration`, and `playingIndex` within an Interstital break.
 
 ```ts
 interface InterstitialsManager {
-  events: InterstitialEvent[]; // An array of Interstitials (events) parsed from the latest media playlist update
   schedule: InterstitialScheduleItem[]; // An array of primary and event items with start and end times representing the scheduled program
-  playerQueue: HlsAssetPlayer[]; // And array of child Hls instances created to preload and stream Interstitial asset content
-  bufferingPlayer: HlsAssetPlayer | null; // The child Hls instance assigned to streaming media at the edge of the forward buffer
+  integrated: PlayheadTimes; // playhead mapping and control that applies the X-TIMELINE-OCCUPIES attribute to each event item
+  primary: PlayheadTimes; // playhead mapping and control based on the primary content
+
+  interstitialPlayer: InterstitialPlayer | null; // interface for interstitial playback state
+
   bufferingAsset: InterstitialAssetItem | null; // The Interstitial asset currently being streamed
   bufferingItem: InterstitialScheduleItem | null; // The primary item or event item currently being streamed
   bufferingIndex: number; // The index of `bufferingItem` in the `schedule` array
+
   playingAsset: InterstitialAssetItem | null; // The Interstitial asset currently being streamed
   playingItem: InterstitialScheduleItem | null; // The primary item or event item currently being played
   playingIndex: number; // The index of `playingItem` in the `schedule` array
-  waitingIndex: number; // The index of the item whose asset list is being loaded in the `schedule` array
-  primary: PlayheadTimes; // playhead mapping and seekTo method based on the primary content
-  playout: PlayheadTimes; // playhead mapping and seekTo method based on playout of all items in the `schedule` array
-  integrated: PlayheadTimes; // playhead mapping and seekTo method that applies the X-TIMELINE-OCCUPIES attribute to each event item
+
+  events: InterstitialEvent[]; // An array of Interstitials (events) parsed from the latest media playlist update
+  playerQueue: HlsAssetPlayer[]; // And array of child Hls instances created to preload and stream Interstitial asset content
+
   skip: () => void; // A method for skipping the currently playing event item, provided it is not jump restricted
 }
 
 type PlayheadTimes = {
   bufferedEnd: number; // The buffer end time relative to the playhead in the scheduled program
-  currentTime: number; // The current playhead time in the scheduled program
+  currentTime: number; // (get/set) The current playhead time in the scheduled program
   duration: number; // The time at the end of the scheduled program
   seekableStart: number; // The earliest available time where media is available (maps to the start of the first segment in primary media playlists)
-  seekTo: (time: number) => void; // A method for seeking to the designated time the scheduled program
 };
+
+interface InterstitialPlayer {
+  currentTime: number; // (get/set) The current playhead time within the interstitial break (no-op prior to playback)
+  duration: number; // the playout duration of the interstitial break
+  assetPlayers: (HlsAssetPlayer | null)[]; // The asset players assigned to the break asset list
+  playingIndex: number; // The index of the currently playing asset (or -1 prior to playback)
+  scheduleItem: InterstitialScheduleEventItem | null; // The interstitial schedule item for the break
+}
+```
+
+The interstials manager can be used to get various apects of interstitial playback.
+
+Time remaining in interstial event break:
+
+```js
+const interstitialPlayer = hls.interstitialsManager.interstitialPlayer;
+// Is the interstitialPlayer playing an asset?
+if (interstitialPlayer && interstitialPlayer.playingIndex > -1) {
+  const timeRemaining = Math.ceil(
+    interstitialPlayer.duration - interstitialPlayer.currentTime,
+  );
+}
+```
+
+The last watched position of primary content:
+
+```js
+const primaryLastWatched = hls.interstitialsManager.primary.currentTime;
+```
+
+Integrated timeline position and time ranges:
+
+```js
+const currentTime = hls.interstitialsManager.integrated.currentTime;
+const timelineRanges = hls.interstitialsManager.schedule.map((item) => {
+  return {
+    interstitial: item.event,
+    start: item.integrated.start,
+    end: item.integrated.end,
+  };
+});
 ```
 
 ### Interstitial Events

src/config.ts

@@ -308,7 +308,7 @@ export type HlsConfig = {
   interstitialsController?: typeof InterstitialsController;
   // Option to disable internal playback handling of Interstitials (set to false to disable Interstitials playback without disabling parsing and schedule events)
   enableInterstitialPlayback: boolean;
-  // Option to disable appending Interstitals inline on same timeline and MediaSource as Primary media
+  // Option to disable appending Interstitials inline on same timeline and MediaSource as Primary media
   interstitialAppendInPlace: boolean;
   // How many seconds past the end of a live playlist to preload Interstitial assets
   interstitialLiveLookAhead: number;
@@ -440,7 +440,7 @@ export const hlsDefaultConfig: HlsConfig = {
   enableEmsgMetadataCues: true,
   enableEmsgKLVMetadata: false,
   enableID3MetadataCues: true,
-  enableInterstitialPlayback: __USE_INTERSTITALS__,
+  enableInterstitialPlayback: __USE_INTERSTITIALS__,
   interstitialAppendInPlace: true,
   interstitialLiveLookAhead: 10,
   useMediaCapabilities: __USE_MEDIA_CAPABILITIES__,
@@ -533,7 +533,7 @@ export const hlsDefaultConfig: HlsConfig = {
       : defaultLoadPolicy,
   },
   interstitialAssetListLoadPolicy: {
-    default: __USE_INTERSTITALS__
+    default: __USE_INTERSTITIALS__
       ? {
           maxTimeToFirstByteMs: 10000,
           maxLoadTimeMs: 30000,
@@ -582,7 +582,7 @@ export const hlsDefaultConfig: HlsConfig = {
   contentSteeringController: __USE_CONTENT_STEERING__
     ? ContentSteeringController
     : undefined,
-  interstitialsController: __USE_INTERSTITALS__
+  interstitialsController: __USE_INTERSTITIALS__
     ? InterstitialsController
     : undefined,
 };

src/controller/base-stream-controller.ts

@@ -454,7 +454,7 @@ export default class BaseStreamController
   ) {
     const config = this.hls.config;
     if (
-      __USE_INTERSTITALS__ &&
+      __USE_INTERSTITIALS__ &&
       config.interstitialsController &&
       config.enableInterstitialPlayback !== false &&
       frag.type !== PlaylistLevelType.SUBTITLE
@@ -488,7 +488,7 @@ export default class BaseStreamController
           }
         }
       }
-      // Skip loading of fragments that overlap completely with appendInPlace interstitals
+      // Skip loading of fragments that overlap completely with appendInPlace interstitials
       const playerQueue = interstitials?.playerQueue;
       if (playerQueue) {
         for (let i = playerQueue.length; i--; ) {

src/controller/id3-track-controller.ts

@@ -461,7 +461,7 @@ class ID3TrackController implements ComponentAPI {
             this.id3Track.addCue(cue);
             cues[key] = cue;
             if (
-              __USE_INTERSTITALS__ &&
+              __USE_INTERSTITIALS__ &&
               this.hls.config.interstitialsController
             ) {
               if (key === 'X-ASSET-LIST' || key === 'X-ASSET-URL') {

src/controller/interstitial-player.ts

@@ -9,17 +9,24 @@ import {
 } from '../loader/interstitial-event';
 import { BufferHelper } from '../utils/buffer-helper';
 import type { HlsConfig } from '../config';
+import type { InterstitialScheduleEventItem } from '../controller/interstitials-schedule';
 import type Hls from '../hls';
 import type { BufferCodecsData, MediaAttachingData } from '../types/events';
 
+export interface InterstitialPlayer {
+  currentTime: number;
+  duration: number;
+  assetPlayers: (HlsAssetPlayer | null)[];
+  playingIndex: number;
+  scheduleItem: InterstitialScheduleEventItem | null;
+}
 export class HlsAssetPlayer {
   public readonly hls: Hls;
   public readonly interstitial: InterstitialEvent;
   public readonly assetItem: InterstitialAssetItem;
   public tracks: Partial<BufferCodecsData> | null = null;
   private hasDetails: boolean = false;
   private mediaAttached: HTMLMediaElement | null = null;
-  private playoutOffset: number = 0;
 
   constructor(
     HlsPlayerClass: typeof Hls,
@@ -49,8 +56,6 @@ export class HlsAssetPlayer {
       this.mediaAttached = media;
       const event = this.interstitial;
       if (event.playoutLimit) {
-        this.playoutOffset =
-          event.assetList[event.assetList.indexOf(assetItem)]?.startOffset || 0;
         media.addEventListener('timeupdate', this.checkPlayout);
       }
     });
@@ -59,7 +64,8 @@ export class HlsAssetPlayer {
   private checkPlayout = () => {
     const interstitial = this.interstitial;
     const playoutLimit = interstitial.playoutLimit;
-    if (this.playoutOffset + this.currentTime >= playoutLimit) {
+    const currentTime = this.currentTime;
+    if (this.startOffset + currentTime >= playoutLimit) {
       this.hls.trigger(Events.PLAYOUT_LIMIT_REACHED, {});
     }
   };
@@ -98,7 +104,7 @@ export class HlsAssetPlayer {
   }
 
   get duration(): number {
-    const duration = this.assetItem?.duration;
+    const duration = this.assetItem.duration;
     if (!duration) {
       return 0;
     }
@@ -113,6 +119,10 @@ export class HlsAssetPlayer {
     return Math.max(0, duration - this.currentTime);
   }
 
+  get startOffset(): number {
+    return this.assetItem.startOffset;
+  }
+
   get timelineOffset(): number {
     return this.hls?.config.timelineOffset || 0;
   }