HlsInterstitialsAdsLoader

Artifact: androidx.media3:media3-exoplayer-hls

Kotlin |Java

@UnstableApi
public final class HlsInterstitialsAdsLoader implements AdsLoader

An ads loader that reads interstitials from the HLS playlist, adds them to the AdPlaybackState and passes the ad playback state to onAdPlaybackState.

An ads ID must be unique within the playlist of ExoPlayer. If this is the case, a single HlsInterstitialsAdsLoader instance can be passed to multiple ads media sources. These ad media source can be added to the same playlist as far as each of the sources have a different ads IDs.

Summary

Nested types
`public final class HlsInterstitialsAdsLoader.AdsMediaSourceFactory implements MediaSource.Factory` A `MediaSource.Factory` to create a media source to play HLS streams with interstitials.
`public class HlsInterstitialsAdsLoader.AdsResumptionState` The state of the given ads ID to resume playback at the given `AdPlaybackState`.
`public final class HlsInterstitialsAdsLoader.Asset` An asset with a URI and a duration.
`public final class HlsInterstitialsAdsLoader.AssetList` Holds a list of `assets`.
`public interface HlsInterstitialsAdsLoader.Listener` A listener to be notified of events emitted by the ads loader.
`public final class HlsInterstitialsAdsLoader.StringAttribute` A string attribute with its name and value.

Public fields
`boolean`	`isReleased`

Public constructors
`HlsInterstitialsAdsLoader(Context context)` Creates an instance with a `DefaultDataSource.Factory` to read HLS X-ASSET-LIST JSON objects.
`HlsInterstitialsAdsLoader(DataSource.Factory dataSourceFactory)` Creates an instance.

Public methods
`void`	`addAdResumptionState( HlsInterstitialsAdsLoader.AdsResumptionState adsResumptionState )` Adds the given `AdsResumptionState` to resume playback of the `AdsMediaSource` with `ads ID` at the provided ad playback state.
`void`	`addAdResumptionState(Object adsId, AdPlaybackState adPlaybackState)` Adds the given `AdPlaybackState` to resume playback of the `AdsMediaSource` with `ads ID` at the provided ad playback state.
`void`	`addListener(HlsInterstitialsAdsLoader.Listener listener)` Adds a `Listener`.
`void`	`clearAllAdResumptionStates()` Clears all ad resumptions states.
`ImmutableList<HlsInterstitialsAdsLoader.AdsResumptionState>`	`getAdsResumptionStates()` Returns the resumption states of the currently active `ads media sources`.
`boolean`	`handleContentTimelineChanged( AdsMediaSource adsMediaSource, Timeline timeline )` Notifies the ads loader when the content source has changed its timeline.
`void`	`handlePrepareComplete( AdsMediaSource adsMediaSource, int adGroupIndex, int adIndexInAdGroup )` Notifies the ads loader that preparation of an ad media period is complete.
`void`	`handlePrepareError( AdsMediaSource adsMediaSource, int adGroupIndex, int adIndexInAdGroup, IOException exception )` Notifies the ads loader that the player was not able to prepare media for a given ad.
`boolean`	`isReleased()` Returns whether `release` has been called.
`void`	`release()` Releases the loader.
`boolean`	`removeAdResumptionState(Object adsId)` Removes the `AdsResumptionState` for the given ads ID, or null if there is no active ad playback state for the given ads ID.
`void`	`removeListener(HlsInterstitialsAdsLoader.Listener listener)` Removes a `Listener`.
`void`	`setPlayer(@Nullable Player player)` Sets the player that will play the loaded ads.
`void`	`setSupportedContentTypes(@C.ContentType int[] contentTypes)` Sets the supported content types for ad media.
`void`	`setWithAvailableAdGroup(int adGroupIndex)` Sets the given ad group to `AD_STATE_AVAILABLE`.
`void`	`setWithAvailableAdMediaItem( int adGroupIndex, int adIndexInAdGroup, @Nullable MediaItem mediaItem )` Sets the given ad to `AD_STATE_AVAILABLE`.
`void`	`setWithSkippedAd(int adGroupIndex, int adIndexInAdGroup)` Sets the given ad to `AD_STATE_SKIPPED`.
`void`	`setWithSkippedAdGroup(int adGroupIndex)` Sets the given ad group to `AD_STATE_SKIPPED`.
`void`	`skipCurrentAd()` Skips the ad currently being played.
`void`	`skipCurrentAdGroup()` Skips the ad group of the ad currently being played.
`void`	`start( AdsMediaSource adsMediaSource, DataSpec adTagDataSpec, Object adsId, AdViewProvider adViewProvider, AdsLoader.EventListener eventListener )` Starts using the ads loader for playback.
`void`	`stop( AdsMediaSource adsMediaSource, AdsLoader.EventListener eventListener )` Stops using the ads loader for playback and deregisters the event listener.

Public fields

isReleased

public boolean isReleased

Public constructors

HlsInterstitialsAdsLoader

public HlsInterstitialsAdsLoader(Context context)

Creates an instance with a DefaultDataSource.Factory to read HLS X-ASSET-LIST JSON objects.

Parameters
`Context context`	The context.

HlsInterstitialsAdsLoader

public HlsInterstitialsAdsLoader(DataSource.Factory dataSourceFactory)

Creates an instance.

Parameters
`DataSource.Factory dataSourceFactory`	The data source factory to read HLS X-ASSET-LIST JSON objects.

Public methods

addAdResumptionState

public void addAdResumptionState(
    HlsInterstitialsAdsLoader.AdsResumptionState adsResumptionState
)

Adds the given AdsResumptionState to resume playback of the AdsMediaSource with ads ID at the provided ad playback state.

If added while the given ads ID is active, the resumption state is ignored. The resumption state for a given ads ID must be added before start or after stop is called for that ads ID.

Parameters
`HlsInterstitialsAdsLoader.AdsResumptionState adsResumptionState`	The state to resume with.

Throws
`java.lang.IllegalArgumentException`	Thrown if the ad playback state `ends with a live placeholder`.

addAdResumptionState

public void addAdResumptionState(Object adsId, AdPlaybackState adPlaybackState)

Adds the given AdPlaybackState to resume playback of the AdsMediaSource with ads ID at the provided ad playback state.

If added while the given ads ID is active, the resumption state is ignored. The resumption state for a given ads ID must be added before start or after stop is called for that ads ID.

Parameters
`Object adsId`	The ads ID identifying the `AdsMediaSource` to resume with the given state.
`AdPlaybackState adPlaybackState`	The state to resume with.

Throws
`java.lang.IllegalArgumentException`	Thrown if the ad playback state `ends with a live placeholder`.

addListener

public void addListener(HlsInterstitialsAdsLoader.Listener listener)

Adds a Listener.

clearAllAdResumptionStates

public void clearAllAdResumptionStates()

Clears all ad resumptions states.

getAdsResumptionStates

public ImmutableList<HlsInterstitialsAdsLoader.AdsResumptionState> getAdsResumptionStates()

Returns the resumption states of the currently active ads media sources.

Call this method to get the resumption states before releasing the player and resume at the same state later.

Live streams and streams with an ads ID that are not of type string are ignored and are not included in the returned list of ad resumption state.

See onStop and addAdResumptionState also.

handleContentTimelineChanged

public boolean handleContentTimelineChanged(
    AdsMediaSource adsMediaSource,
    Timeline timeline
)

Notifies the ads loader when the content source has changed its timeline. Called on the main thread by AdsMediaSource.

The default implementation returns false which makes the content timeline immediately being reported to the player.

When overriding this method for the purpose of reading ad data from the timeline to populate the AdPlaybackState with, false needs to be passed to the constructor of AdsMediaSource to indicate that the content source needs to be prepared upfront. This way an ads loader can defer calling onAdPlaybackState until the ad data from the timeline is available and populate the initial ad playback state with that data before publishing.

For live streams, this method is called additional times when the content source reports an advancing live window with new available media and/or new ad data in the manifest. If in such a case, the ads loader as a result calls onAdPlaybackState, true must be returned. This prevents the timeline being reported with stale ad data. Conversely, when the ad playback state is not passed into onAdPlaybackState, false must be returned to not drop a timeline update that needs to be published to the player.

Generally, if the timeline is not required to populate the ad playback state, start should be used to initiate loading ad data and publish the first ad playback state as early as possible. This method can still be overridden for informational or other purpose. In this case, false is returned here and the AdsMediaSource is used with lazy preparation enabled.

Parameters
`AdsMediaSource adsMediaSource`	The ads media source for which the content timeline changed.
`Timeline timeline`	The timeline of the content source.

Returns
`boolean`	true If `onAdPlaybackState` is or will be called, false otherwise.

handlePrepareComplete

public void handlePrepareComplete(
    AdsMediaSource adsMediaSource,
    int adGroupIndex,
    int adIndexInAdGroup
)

Notifies the ads loader that preparation of an ad media period is complete. Called on the main thread by AdsMediaSource.

Parameters
`AdsMediaSource adsMediaSource`	The ads media source for which preparation of ad media completed.
`int adGroupIndex`	The index of the ad group.
`int adIndexInAdGroup`	The index of the ad in the ad group.

handlePrepareError

public void handlePrepareError(
    AdsMediaSource adsMediaSource,
    int adGroupIndex,
    int adIndexInAdGroup,
    IOException exception
)

Notifies the ads loader that the player was not able to prepare media for a given ad. Implementations should update the ad playback state as the specified ad has failed to load. Called on the main thread by AdsMediaSource.

Parameters
`AdsMediaSource adsMediaSource`	The ads media source for which preparation of ad media failed.
`int adGroupIndex`	The index of the ad group.
`int adIndexInAdGroup`	The index of the ad in the ad group.
`IOException exception`	The preparation error.

isReleased

public boolean isReleased()

Returns whether release has been called.

Returns
`boolean`	True if `release` has been called, false otherwise.

release

public void release()

Releases the loader. Must be called by the application on the main thread when the instance is no longer needed.

removeAdResumptionState

public boolean removeAdResumptionState(Object adsId)

Removes the AdsResumptionState for the given ads ID, or null if there is no active ad playback state for the given ads ID.

Parameters
`Object adsId`	The ads ID for which to remove the resumption state.

Returns
`boolean`	The removed resumption state or null.

removeListener

public void removeListener(HlsInterstitialsAdsLoader.Listener listener)

Removes a Listener.

setPlayer

public void setPlayer(@Nullable Player player)

Sets the player that will play the loaded ads.

This method must be called before the player is prepared with media using this ads loader.

This method must also be called on the main thread and only players which are accessed on the main thread are supported ( player.getApplicationLooper() == Looper.getMainLooper()).

Throws
`java.lang.IllegalStateException`	If an app is attempting to set a new player instance after `release` was called or while `ads media sources` started by the old player are still active, an `IllegalStateException` is thrown. Release the old player first, or remove all ads media sources from it before setting another player instance.

setSupportedContentTypes

public void setSupportedContentTypes(@C.ContentType int[] contentTypes)

Sets the supported content types for ad media. Must be called before the first call to start. Subsequent calls may be ignored. Called on the main thread by AdsMediaSource.

Parameters
`@C.ContentType int[] contentTypes`	The supported content types for ad media. Each element must be one of `CONTENT_TYPE_DASH`, `CONTENT_TYPE_HLS`, `CONTENT_TYPE_SS` and `CONTENT_TYPE_OTHER`.

setWithAvailableAdGroup

public void setWithAvailableAdGroup(int adGroupIndex)

Sets the given ad group to AD_STATE_AVAILABLE. Ads that are in state AD_STATE_UNAVAILABLE or AD_STATE_ERROR are left unchanged.

Parameters
`int adGroupIndex`	The index of the ad group in the ad playback state.

Throws
`java.lang.IllegalArgumentException`	if there is no ad group available for the given index.
`java.lang.IllegalStateException`	if called when the player `is not set` or if any ad in the group doesn't have a media item for the ad stream assigned.

setWithAvailableAdMediaItem

public void setWithAvailableAdMediaItem(
    int adGroupIndex,
    int adIndexInAdGroup,
    @Nullable MediaItem mediaItem
)

Sets the given ad to AD_STATE_AVAILABLE.

Parameters
`int adGroupIndex`	The index of the ad group in the ad playback state.
`int adIndexInAdGroup`	The index of the ad in the ad group in the ad playback state.
`@Nullable MediaItem mediaItem`	The optional media item. If not set the same ad media item is played again.

Throws
`java.lang.IllegalArgumentException`	if there is no ad group or ad available for the given indices or if the provided `MediaItem` is not an HLS media item.
`java.lang.IllegalStateException`	if the media item that was passed in is null, and the given ad doesn't have a media item set already, or if called when the player `is not set`.

setWithSkippedAd

public void setWithSkippedAd(int adGroupIndex, int adIndexInAdGroup)

Sets the given ad to AD_STATE_SKIPPED.

Ads that are already in state AD_STATE_PLAYED, AD_STATE_SKIPPED or AD_STATE_ERROR are left unchanged.

Parameters
`int adGroupIndex`	The index of the ad group in the ad playback state.
`int adIndexInAdGroup`	The index of the ad in the ad group in the ad playback state.

Throws
`java.lang.IllegalArgumentException`	if there is no ad group or ad available for the given indices.
`java.lang.IllegalStateException`	if called when the player `is not set`.

setWithSkippedAdGroup

public void setWithSkippedAdGroup(int adGroupIndex)

Sets the given ad group to AD_STATE_SKIPPED.

Ads that are already in state AD_STATE_PLAYED, AD_STATE_SKIPPED or AD_STATE_ERROR are left unchanged.

Parameters
`int adGroupIndex`	The index of the ad group in the ad playback state.

Throws
`java.lang.IllegalArgumentException`	if there is no ad group available for the given index.
`java.lang.IllegalStateException`	if called when the player `is not set`.

skipCurrentAd

public void skipCurrentAd()

Skips the ad currently being played.

Does nothing if no ad is playing or the ad is not managed by this ads loader.

skipCurrentAdGroup

public void skipCurrentAdGroup()

Skips the ad group of the ad currently being played.

Does nothing if no ad is playing or the ad is not managed by this ads loader.

start

public void start(
    AdsMediaSource adsMediaSource,
    DataSpec adTagDataSpec,
    Object adsId,
    AdViewProvider adViewProvider,
    AdsLoader.EventListener eventListener
)

Starts using the ads loader for playback. Called on the main thread by AdsMediaSource.

Requests the ads loader to start loading ad data from the provided adTagDataSpec. Publishing an initial AdPlaybackState to provided eventListener is required to start playback. In the case of a pre roll, this ensures that the player doesn't briefly start playing content before ad data is available.

Parameters
`AdsMediaSource adsMediaSource`	The ads media source requesting to start loading ads.
`DataSpec adTagDataSpec`	A data spec for the ad tag to load.
`Object adsId`	An opaque identifier for the ad playback state across start/stop calls.
`AdViewProvider adViewProvider`	Provider of views for the ad UI.
`AdsLoader.EventListener eventListener`	Listener for ads loader events.

stop

public void stop(
    AdsMediaSource adsMediaSource,
    AdsLoader.EventListener eventListener
)

Stops using the ads loader for playback and deregisters the event listener. Called on the main thread by AdsMediaSource.

Parameters
`AdsMediaSource adsMediaSource`	The ads media source requesting to stop loading/playing ads.
`AdsLoader.EventListener eventListener`	The ads media source's listener for ads loader events.

HlsInterstitialsAdsLoader

Summary

Nested types

Public fields

Public constructors

Public methods

Public fields

isReleased

Public constructors

HlsInterstitialsAdsLoader

HlsInterstitialsAdsLoader

Public methods

addAdResumptionState

addAdResumptionState

addListener

clearAllAdResumptionStates

getAdsResumptionStates

handleContentTimelineChanged

handlePrepareComplete

handlePrepareError

isReleased

release

removeAdResumptionState

removeListener

setPlayer

setSupportedContentTypes

setWithAvailableAdGroup

setWithAvailableAdMediaItem

setWithSkippedAd

setWithSkippedAdGroup

skipCurrentAd

skipCurrentAdGroup

start

stop