Client-side Interstitials API

[ghouet]

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

Apple's introduction of HLS interstitials support within AVFoundation has opened up new possibilities for content publishers. This client-side API enables the seamless scheduling of HLS interstitials across any HLS content, irrespective of whether it's Video-on-Demand (VOD) or Live.
This development provides a powerful tool for enhancing the viewer experience, and/or creating new experience by composing video streams on the client side.

While hls.js already offers robust support for server-side interstitials, the emergence of a client-side API presents a compelling alternative for premium content video publishers. This client-side approach delivers the same core benefits as server-side implementations – primarily, enabling effective ad insertion – but critically, it eliminates the need for a complex manifest manipulation server. This simplification significantly reduces the operational overhead and technical complexity associated with implementing ad breaks, making it more accessible for a broader range of content providers.

Beyond the reduced infrastructure requirements, the client-side API also unlocks a new level of control and flexibility for content presentation. Publishers can now leverage these capabilities to introduce enhanced controls on the client-side, leading to a more refined and engaging user experience. This includes, but is not limited to:

• Improved Presentation Control: Finer-grained control over how interstitials are displayed, allowing for more creative and integrated ad placements that feel less disruptive to the viewer.
• Seamless Transitions: The ability to implement smoother and more sophisticated transitions on screen during interstitial playback, minimizing jarring jumps and maintaining a fluid viewing experience.
• Enhanced Skip Controls: Providing viewers with more precise and user-friendly skip controls, empowering them to navigate ad content more efficiently and on their own terms. This can lead to increased viewer satisfaction and potentially higher ad completion rates.

Describe the solution you'd like

An API like AVFoundation where the developer can schedule ad interstitials at precise times (PDT should be required for live streams) on the primary content.

It should provide the same option as the serverside-api as a baseline but could be improved with options to customize the presentation/transition of the second interstitials players, for example allowing side-by-side playback or other experiences.

See AVFoundation client API.

This proposal outlines the need for a robust client-side API within hls.js to manage and display HLS ad interstitials. Drawing inspiration from established frameworks like Apple's AVFoundation, the goal is to empower developers with precise control over the scheduling and presentation of advertisements within primary content.
The proposed API would allow developers to schedule ad interstitials at specific, precise times within the primary HLS content.

The API should offer a baseline set of functionalities mirroring those found in the existing server-side HLS Interstitials. Any new features (like skippable) added to server-side should also be added to the client-side API. This includes, but is not limited to:

1. Precise Time-Based Scheduling: The ability to specify the exact start time of an interstitial within the primary content's timeline.
2. Secondary Playback Management: Handling the loading, playback, and completion of the interstitial content.
3. Primary Content Resumption: Seamlessly returning to the primary content after the interstitial has concluded, or a playout limit has been set on the interstitial.
4. Skipping interstitials: allow control to skip an item of an asset list, or seek to a specific time within the interstitials.
5. Asset List and m3u8 manifest: support either format interchangeably.
6. emsg/ID3 monitoring: support monitoring timed metadata similarly to the main content.

Additional context

No response

[robwalch]

Adding client-side insertion of interstitial events makes sense.

Some of the "beyond baseline" items listed above fall outside the scope of interstitials - side by side, pip, and overlay would not be considered interstitials and deserve a class of their own.

Instead, I would recommend focusing the request on insertion, editing, removal, and error handling for the client-side API.

[ghouet]

Thanks updated

[robwalch]

2. Secondary Playback Management: Handling the loading, playback, and completion of the interstitial content.

Once an interstitial is schedule by the client, how would loading/playback/completion be any different?

The interstitial-controller handles loading of schedule asset-list or URIs. The asset-player instances handle loading of each asset, and playback is managed by the media element(s) attached to those instances. The same media element is transferred between instances by the interstitial-controller, but the application controlling hls.js can intervene to attach other media elements.

3. Primary Content Resumption: Seamlessly returning to the primary content after the interstitial has concluded, or a playout limit has been set on the interstitial.

Already implemented.

4. Skipping interstitials: allow control to skip an item of an asset list, or seek to a specific time within the interstitials.

Skipping is already implemented and made available via the InterstitialsManager skip method.

5. Asset List and m3u8 manifest: support either format interchangeably.

Already implemented.

6. emsg/ID3 monitoring: support monitoring timed metadata similarly to the main content.

Interstitial asset players provide exactly the same API as the primary player. Listen to the INTERSTITIAL_ASSET_PLAYER_CREATED event for the earliest opportunity access a asset player instance to attach event listeners. Access is also available via the InterstitialsManager playerQueue and INTERSTITIAL_ASSET_STARTED event object.

None of the functionality above would require duplication for Interstitials scheduled via a client-side API. The challenges in creating such an API include:

• Creation and management of DateRange objects not found in the playlists that InterstitialEvent objects depend upon
• Preventing timeline and playback interference on insertion and removal
  • changes that would impact the current playback position must
    • not be allowed
    • or deferred until seeking back to an earlier point
    • unless intentionally removing and cancelling the active interstitial