HLS Interstitial Support

[robwalch]

Is your feature request related to a problem? Please describe.

The HLS Spec defines interstitial content scheduling via EXT-X-DATERANGE Schema for Interstitials:

https://datatracker.ietf.org/doc/html/draft-pantos-hls-rfc8216bis#appendix-D

Describe the solution you'd like

HLS.js should support scheduling and playback of Interstitial content by the best means available.

Since HLS.js is designed to handle a single HLS asset via an HTMLMediaElement with a single static timeline, it stands to reason that Interstitial playback will require multiple Hls(js) player instances, and one or more HTMLMediaElements.

Additional context

In addition to the EXT-X-DATERANGE Schema for Interstitials, EXT-X-DATERANGE also defines an optional CUE attribute (formerly X-CUE). This attribute specifies whether a DateRange is to be triggered as pre-roll, post-roll, or on START-DATE (mid-roll). It also can indicate that the action should only be triggered once.

TextTrack cues created by HLS.js are always placed according to the start date and duration of DateRanges. CUE and X-SNAP attributes may be considered as modifiers for this behavior.

Interstitial events and scheduling APIs should have cue and snap rules applied to their timing, while still providing access to the original DateRange objects and their attributes. If the program is expected to play using a single media element, without resetting between primary and interstitial items, the timeline of that element will dictate how Interstitial durations and resume offsets impact the timing of primary content segments, metadata on that timeline, and the timing of subsequent Interstitials.

Functional Requirements

• Interstitial support can be enabled/disabled using a config option (setting config.InterstitialController = null)
• Interstitial support can removed from the build via compile time option (empty Controller/config option / removed from "hls.light" builds)
• New HLS.js Interstitial events:
  • INTERSTITIALS_UPDATED - the list of Interstitial Events and Interstitial Schedule is updated
  • INTERSTITIALS_BUFFERED_TO_BOUNDARY - the buffer reaches an Interstitial Schedule boundary (both Primary segments and Interstitial Assets)
  • ASSET_LIST_LOADING / ASSET_LIST_LOADED - asset list has begun loading / a valid asset list is loaded
  • INTERSTITIAL_ASSET_PLAYER_CREATED - a player instance for an Interstitial Asset has been created
  • INTERSTITIAL_STARTED - Interstitial playback started
  • INTERSTITIAL_ENDED - Interstitial playback ended
  • INTERSTITIAL_ASSET_STARTED - Interstitial Asset playback started
  • INTERSTITIAL_ASSET_ENDED - Interstitial Asset playback ended
  • INTERSTITIAL_ASSET_ERROR - Interstitial Asset playback errored
  • INTERSTITIALS_PRIMARY_RESUMED - Interstitial schedule resumed primary playback
  • New ErrorDetails enums for Interstitial related network and parsing errors:
    • ASSET_LIST_LOAD_ERROR
    • ASSET_LIST_LOAD_TIMEOUT
    • ASSET_LIST_PARSING_ERROR
    • INTERSTITIAL_ASSET_ITEM_ERROR - Error forwarded from asset player (fatal to the asset player but not primary playback)
• HLS.js handles preloading and streaming of Interstitials via additional instances of HLS.js
  • Interstitial player instances are child instances of the primary player
• Interstitial instances (like the primary player instance) must have an HTMLMediaElement attached to append media to SourceBuffers
  • Two modes of operation will determine how individual Interstitials map to the media elements timeline:
    • "replace" mode will plot the Interstitials on the Primary timeline. It will allow seeking between scheduled items using built-in controls.
    • "reset" mode will create or reset the MediaSource for each asset in the Interstitial. Each item will start at "0" and have a duration equal to its corresponding HLS asset program (similar to AVOD playback). Additional HTMLMediaElements can be attached to Interstitial players for more seamless transitions (providing DOM elements are managed appropriately by the application using HLS.js and the platform supports multiple HTMLMediaElements and MediaSource decoding)
• Client-side Interstitial insertion (optional - may be added in later releases)

Development Plan (Overview)

• Interstitial Parsing
• Schedule position + progression
• Play-through by resetting MediaSource on Schedule Change
• HLS.js Interstitial Events and HLS.js Event enhancements for scheduling
• Single Timeline Play-through and MSE enhancements (sharing MediaSource between players)
• Seeking via Schedule, Date, or Primary Media Element
• Live Interstitials (Improving join/resume timing, testing contributed assets and edge-cases)
• Transitioning between mixed content and players (and other enhancements)
• Documentation and Examples
• Test content needed (ask or produce missing HLS asset tests)
  • Consecutive postrolls (plus looping after postroll)
  • Custom preroll, midroll, postroll video with burned in labels