Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Allow configuring asset-list prefetch timing per HLS interstitial

Open
  • Is something wrong?
#3,494 0 comments 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 4 days

@marcbaechinger is already working on this.

Since Oct 28, 2026.

Assessment

This issue has not been assessed yet.

Description

enhancement needs triage
Use case description

We would like to control when HlsInterstitialsAdsLoader resolves the X-ASSET-LIST for each interstitial, allowing resolution both earlier and later than the current default.

In our implementation, asset-list resolution triggers an ad-decision request. Its timing affects both the time available to cache the returned ads before playback and which assets we request. (We can handle media caching ourselves through existing APIs.)

For live streams, we check whether the content position at which playback should resume after the break is already available:

resumePosition = breakStartPosition + plannedBreakDuration

If the known live edge has not reached that position, we request an additional filler audio asset. Resolving later may avoid requesting that asset while still leaving enough time to prepare the ads before playback reaches the break.

Whether this is possible depends on the listener’s distance behind the live edge, the break duration, and the resolution lead time.

Conversely, other breaks may benefit from earlier resolution to accommodate ad-service latency and allow more time for caching.

Currently, maybeExecuteOrSetNextAssetListResolutionMessage() in HlsInterstitialsAdsLoader.java:1432 calculates resolution timing using a fixed heuristic:

resolutionStartTimeUs =
    max(
        currentPeriodPositionUs,
        resolutionStartTimeUs
            - (TARGET_DURATION_MULTIPLIER * nextAssetResolution.targetDurationUs));

TARGET_DURATION_MULTIPLIER is a constant set to 3, so a ten-second playlist target duration causes resolution approximately 30 seconds before the break.

This ties ad-decision timing to segment duration rather than application requirements. Configurable timing would let us balance preparation time against content availability, which can favor either earlier or later resolution. Our manifests provide custom prefetch markers that specify the resolution timing for each break.

The requested capability would concern asset-list resolution timing. Media caching could remain application-managed.

Proposed solution

Would it be possible to expose an API for configuring asset-list resolution timing per interstitial, retaining the existing heuristic when no override is provided?

One possible API would be:

public void setAssetListResolutionLeadTimeMs(
    Object adsId,
    String interstitialId,
    long leadTimeMs);

The lead time would specify how long before the break’s start resolution should become eligible:

// Resolve 60 seconds before this break.
adsLoader.setAssetListResolutionLeadTimeMs(
    adsId,
    "break-123",
    60_000L,
)

// Resolve only 5 seconds before another break.
adsLoader.setAssetListResolutionLeadTimeMs(
    adsId,
    "break-456",
    5_000L,
)

A lead time relative to the break would avoid ambiguity as the live window moves. An application with an explicit prefetch marker could calculate:

val leadTimeMs = breakStartPositionMs - prefetchPositionMs

The configured timing would replace the default for that interstitial, allowing earlier or later resolution while preserving Media3’s handling of seeks and live-window updates. A per-interstitial scheduling callback would also meet our needs.

Alternatives considered
  • A global configurable lead time: Allows earlier or later resolution globally, but cannot express different requirements for individual breaks.
  • Delaying resolution inside a custom DataSource: Could postpone the ad-decision request, but would keep Media3’s load in flight while waiting and could block other asset-list requests.
  • A timing callback: Media3 could ask the application when to resolve each break’s asset list, then schedule the request itself. This would also work for our use case.
Dominant language
Java
Stars
3.1k
Forks
998
Avg merge
6d 8h
Merged PRs (30d)
2

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from androidx/media

All issues in androidx/media

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.