Allow invalidation of resolved assets in X-ASSET-LIST interstitials

Use case description

Our use case requires live HLS streams with HLS Interstitials where EXT-X-DATERANGE interstitials use X-ASSET-LIST rather than X-ASSET-URI. The asset-list endpoint is dynamic and is provided by a third party, so a fresh request can return a different set of ads depending on a number of business rules.

We need an opt-in way for playback to resolve asset lists for interstitials that are behind the current playback position when the user later scrubs back before them. For example, if the user joins at the live edge and several interstitial ad groups are already behind that position, the app should be able to avoid playing those immediately, but still allow them to resolve normally if the user scrubs back before any of them.

Likewise, we also need an opt-in way to re-request an asset list for an ad group that was already resolved/played earlier. When the user scrubs back before that ad group and playback reaches the ad opportunity again, we want to invalidate the previous asset-list result and request the endpoint again, rather than replaying the old resolved media items.

With current Media3 behavior, joining a live HLS interstitial stream at the live edge may immediately play the latest unplayed ad group before the current playback position. To avoid that, our app marks ad groups behind the current position as skipped and groups ahead as available. We repeat this after seek/skip events.

This prevents immediate playback of past ads, but it does not allow those past X-ASSET-LIST ad groups to resolve later. Marking a group skipped removes its pending asset-list entry from the loader's internal unresolvedAssetLists. If the user then scrubs back before that ad group and the app tries to make it available, the ad has no mediaItems, and there is no pending asset-list entry for the loader to resolve.

Similarly, once an asset list has been resolved, Media3 stores the resolved ad media items in AdPlaybackState and removes the asset-list entry from the pending unresolvedAssetLists. There does not appear to be a public API to invalidate that resolved result and schedule resolution again.

I've gone through this closed issue, but I still can't find any public API that would allow us to achieve this behavior without altering media3 internals in a fork. Please do correct me if this is already possible.

Proposed solution

We suggest to add an opt-in API that lets apps invalidate and requeue HLS X-ASSET-LIST interstitial resolution without requiring Media3 to adopt any default scrub-back ad policy.

One possibility we propose is to add a method that lets implementors invalidate and requeue X-ASSET-LIST interstitial resolution. E.g.

 void invalidateAssetListAdGroup(int adGroupIndex);

Expected behavior:

• Applies to ad groups resulting from X-ASSET-LIST
• Clears any previously resolved media items for the given ad group.
• Restores the ad group to an unresolved state so the loader can apply a new asset list
• Schedules resolution of assets (if appropriate)

We could then leverage this function in onPositionDiscontinuity to do something like:

  if (group.timeUs <= playbackPositionInPeriodUs) {
        if (isSkippable(group)) {
          hlsInterstitialsAdsLoader.setWithSkippedAdGroup(i);
        }
      } else if (isReplayable(group)) {
          hlsInterstitialsAdsLoader.invalidateAssetListAdGroup(i)
          hlsInterstitialsAdsLoader.setWithAvailableAdGroup(i);
      }

Alternatively, Media3 could expose an opt-in general request strategy on HlsInterstitialsAdsLoader, so apps can decide when an asset-list backed interstitial should be invalidated/re-requested during seek or boundary crossing.

Alternatives considered

We tried using existing public apis to:

• mark ad groups behind the current playback position as skipped
• mark future/replayable groups as available

This is not sufficient for X-ASSET-LIST interstitials.

• For past ad groups that have never been resolved, setting the group available cannot work because the ad has no resolved mediaItems. The asset-list entry was also removed from unresolvedAssetLists when the group was marked skipped, so there is no request for the loader to resolve.

• For already-resolved/played ad groups, setting the group available reuses the previously resolved media items. It does not invalidate the old asset-list response or request a new one.

The currently available function setWithAvailableAdMediaItem is not enough for our needs since we work off multiple mediaItems. It also would require to duplicate the loading logic, which would be redundant.