@UnstableApi
class DownloadHelper

A helper for initializing and removing downloads.

The helper extracts track information from the media, selects tracks for downloading, and creates download requests based on the selected tracks.

A typical usage of DownloadHelper follows these steps:

  1. Build the helper using one of the forMediaItem methods.
  2. Prepare the helper using prepare and wait for the callback.
  3. Optional: Inspect the selected tracks using getMappedTrackInfo and getTrackSelections, and make adjustments using clearTrackSelections, replaceTrackSelections and addTrackSelection.
  4. Create a download request for the selected track using getDownloadRequest.
  5. Release the helper using release.

Summary

Nested types

A callback to be notified when the DownloadHelper is prepared.

A factory of DownloadHelper.

Thrown at an attempt to download live content.

Constants
const DefaultTrackSelector.Parameters!

Default track selection parameters for downloading.
const DefaultTrackSelector.Parameters!

This property is deprecated.

Use DEFAULT_TRACK_SELECTOR_PARAMETERS instead.

Public constructors
DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: RendererCapabilitiesList!
)

Creates download helper.
DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: RendererCapabilitiesList!,
    debugLoggingEnabled: Boolean
)

Creates download helper.

Public functions
Unit

Convenience method to add selections of tracks for all specified audio languages.
Unit
addTextLanguagesToSelection(
    selectUndeterminedTextLanguage: Boolean,
    languages: Array<String!>!
)

Convenience method to add selections of tracks for all specified text languages.
Unit
addTrackSelection(
    periodIndex: Int,
    trackSelectionParameters: TrackSelectionParameters!
)

Adds a selection of tracks to be downloaded.
Unit
addTrackSelectionForSingleRenderer(
    periodIndex: Int,
    rendererIndex: Int,
    trackSelectorParameters: DefaultTrackSelector.Parameters!,
    overrides: (Mutable)List<DefaultTrackSelector.SelectionOverride!>!
)

Convenience method to add a selection of tracks to be downloaded for a single renderer.
Unit
clearTrackSelections(periodIndex: Int)

Clears the selection of tracks for a period.
java-static MediaSource!
createMediaSource(
    downloadRequest: DownloadRequest!,
    dataSourceFactory: DataSource.Factory!
)

Equivalent to createMediaSource(downloadRequest, dataSourceFactory, null).
java-static MediaSource!
createMediaSource(
    downloadRequest: DownloadRequest!,
    dataSourceFactory: DataSource.Factory!,
    drmSessionManager: DrmSessionManager?
)

Utility method to create a MediaSource that only exposes the tracks defined in downloadRequest.
java-static DownloadHelper!
forMediaItem(context: Context!, mediaItem: MediaItem!)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    dataSourceFactory: DataSource.Factory!
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    dataSourceFactory: DataSource.Factory!,
    debugLoggingEnabled: Boolean
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    debugLoggingEnabled: Boolean
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    debugLoggingEnabled: Boolean
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    drmSessionManager: DrmSessionManager?
)

This function is deprecated.

Use create instead.
java-static DownloadHelper!
forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    drmSessionManager: DrmSessionManager?,
    debugLoggingEnabled: Boolean
)

This function is deprecated.

Use create instead.
java-static DefaultTrackSelector.Parameters!

This function is deprecated.

Use DEFAULT_TRACK_SELECTOR_PARAMETERS instead.
DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks.
DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks.
DownloadRequest!
getDownloadRequest(
    data: ByteArray?,
    startPositionMs: Long,
    durationMs: Long
)

Builds a DownloadRequest for downloading the selected tracks and time range.
DownloadRequest!
getDownloadRequest(
    id: String!,
    data: ByteArray?,
    startPositionMs: Long,
    durationMs: Long
)

Builds a DownloadRequest for downloading the selected tracks and time range.
Any?

Returns the manifest, or null if no manifest is loaded.
MappingTrackSelector.MappedTrackInfo!
getMappedTrackInfo(periodIndex: Int)

Returns the mapped track info for the given period.
Int

Returns the number of periods for which media is available.
TrackGroupArray!
getTrackGroups(periodIndex: Int)

Returns the track groups for the given period.
(Mutable)List<ExoTrackSelection!>!
getTrackSelections(periodIndex: Int, rendererIndex: Int)

Returns all track selections for a period and renderer.
Tracks!
getTracks(periodIndex: Int)

Returns Tracks for the given period.
Unit

Initializes the helper for starting a download.
Unit

Releases the helper and all resources it is holding.
Unit
replaceTrackSelections(
    periodIndex: Int,
    trackSelectionParameters: TrackSelectionParameters!
)

Replaces a selection of tracks to be downloaded.

Constants

DEFAULT_TRACK_SELECTOR_PARAMETERS

const val DEFAULT_TRACK_SELECTOR_PARAMETERS: DefaultTrackSelector.Parameters!

Default track selection parameters for downloading.

DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT

const val DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT: DefaultTrackSelector.Parameters!

Public constructors

DownloadHelper

DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: RendererCapabilitiesList!
)

Creates download helper.

Parameters
mediaItem: MediaItem!

The media item.
mediaSource: MediaSource?

A MediaSource for which tracks are selected, or null if no track selection needs to be made.
trackSelectionParameters: TrackSelectionParameters!

TrackSelectionParameters for selecting tracks for downloading.
rendererCapabilities: RendererCapabilitiesList!

The RendererCapabilitiesList of the renderers for which tracks are selected.

DownloadHelper

DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: RendererCapabilitiesList!,
    debugLoggingEnabled: Boolean
)

Creates download helper.

Parameters
mediaItem: MediaItem!

The media item.
mediaSource: MediaSource?

A MediaSource to be prepared, or null if no preparation needs to be done.
trackSelectionParameters: TrackSelectionParameters!

TrackSelectionParameters for selecting tracks for downloading.
rendererCapabilities: RendererCapabilitiesList!

The RendererCapabilitiesList of the renderers for which tracks are selected.
debugLoggingEnabled: Boolean

Whether to log debug information.

Public functions

addAudioLanguagesToSelection

fun addAudioLanguagesToSelection(languages: Array<String!>!): Unit

Convenience method to add selections of tracks for all specified audio languages. If an audio track in one of the specified languages is not available, the default fallback audio track is used instead. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
languages: Array<String!>!

A list of audio languages for which tracks should be added to the download selection, as IETF BCP 47 conformant tags.

addTextLanguagesToSelection

fun addTextLanguagesToSelection(
    selectUndeterminedTextLanguage: Boolean,
    languages: Array<String!>!
): Unit

Convenience method to add selections of tracks for all specified text languages. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
selectUndeterminedTextLanguage: Boolean

Whether a text track with undetermined language should be selected for downloading if no track with one of the specified languages is available.
languages: Array<String!>!

A list of text languages for which tracks should be added to the download selection, as IETF BCP 47 conformant tags.

addTrackSelection

fun addTrackSelection(
    periodIndex: Int,
    trackSelectionParameters: TrackSelectionParameters!
): Unit

Adds a selection of tracks to be downloaded. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index this track selection is added for.
trackSelectionParameters: TrackSelectionParameters!

The TrackSelectionParameters to obtain the new selection of tracks.

addTrackSelectionForSingleRenderer

fun addTrackSelectionForSingleRenderer(
    periodIndex: Int,
    rendererIndex: Int,
    trackSelectorParameters: DefaultTrackSelector.Parameters!,
    overrides: (Mutable)List<DefaultTrackSelector.SelectionOverride!>!
): Unit

Convenience method to add a selection of tracks to be downloaded for a single renderer. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index the track selection is added for.
rendererIndex: Int

The renderer index the track selection is added for.
trackSelectorParameters: DefaultTrackSelector.Parameters!

The DefaultTrackSelector.Parameters to obtain the new selection of tracks.
overrides: (Mutable)List<DefaultTrackSelector.SelectionOverride!>!

A list of SelectionOverrides to apply to the trackSelectorParameters. If empty, trackSelectorParameters are used as they are.

clearTrackSelections

fun clearTrackSelections(periodIndex: Int): Unit

Clears the selection of tracks for a period. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index for which track selections are cleared.

createMediaSource

java-static fun createMediaSource(
    downloadRequest: DownloadRequest!,
    dataSourceFactory: DataSource.Factory!
): MediaSource!

Equivalent to createMediaSource(downloadRequest, dataSourceFactory, null).

createMediaSource

java-static fun createMediaSource(
    downloadRequest: DownloadRequest!,
    dataSourceFactory: DataSource.Factory!,
    drmSessionManager: DrmSessionManager?
): MediaSource!

Utility method to create a MediaSource that only exposes the tracks defined in downloadRequest.

Parameters
downloadRequest: DownloadRequest!

A DownloadRequest.
dataSourceFactory: DataSource.Factory!

A factory for DataSources to read the media.
drmSessionManager: DrmSessionManager?

An optional DrmSessionManager to be passed to the .
Returns
MediaSource!

A MediaSource that only exposes the tracks defined in downloadRequest.

forMediaItem

java-static fun forMediaItem(context: Context!, mediaItem: MediaItem!): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    dataSourceFactory: DataSource.Factory!
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    dataSourceFactory: DataSource.Factory!,
    debugLoggingEnabled: Boolean
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    debugLoggingEnabled: Boolean
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    debugLoggingEnabled: Boolean
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    drmSessionManager: DrmSessionManager?
): DownloadHelper!

forMediaItem

java-static fun forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    drmSessionManager: DrmSessionManager?,
    debugLoggingEnabled: Boolean
): DownloadHelper!

getDefaultTrackSelectorParameters

java-static fun getDefaultTrackSelectorParameters(context: Context!): DefaultTrackSelector.Parameters!

getDownloadRequest

fun getDownloadRequest(data: ByteArray?): DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks. Must not be called until after preparation completes. The uri of the DownloadRequest will be used as content id.

Parameters
data: ByteArray?

Application provided data to store in data.

getDownloadRequest

fun getDownloadRequest(id: String!, data: ByteArray?): DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks. Must not be called until after preparation completes.

Parameters
id: String!

The unique content id.
data: ByteArray?

Application provided data to store in data.

getDownloadRequest

fun getDownloadRequest(
    data: ByteArray?,
    startPositionMs: Long,
    durationMs: Long
): DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks and time range. Must not be called until preparation completes.

This method is only supported for progressive streams.

Parameters
data: ByteArray?

Application provided data to store in data.
startPositionMs: Long

The start position (in milliseconds) of the media that download should cover from, or TIME_UNSET if the download should cover from the default start position.
durationMs: Long

The end position (in milliseconds) of the media that download should cover to, or TIME_UNSET if the download should cover to the end of the media. If the endPositionMs is larger than the duration of the media, then the download will cover to the end of the media.

getDownloadRequest

fun getDownloadRequest(
    id: String!,
    data: ByteArray?,
    startPositionMs: Long,
    durationMs: Long
): DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks and time range. Must not be called until preparation completes.

This method is only supported for progressive streams.

Parameters
id: String!

The unique content id.
data: ByteArray?

Application provided data to store in data.
startPositionMs: Long

The start position (in milliseconds) of the media that download should cover from, or TIME_UNSET if the download should cover from the default start position.
durationMs: Long

The duration (in milliseconds) of the media that download should cover, or TIME_UNSET if the download should cover to the end of the media. If the end position resolved from startPositionMs and durationMs is beyond the duration of the media, then the download will just cover to the end of the media.

getManifest

fun getManifest(): Any?

Returns the manifest, or null if no manifest is loaded. Must not be called until onPrepared is triggered.

getMappedTrackInfo

fun getMappedTrackInfo(periodIndex: Int): MappingTrackSelector.MappedTrackInfo!

Returns the mapped track info for the given period. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index.
Returns
MappingTrackSelector.MappedTrackInfo!

The MappedTrackInfo for the period.

getPeriodCount

fun getPeriodCount(): Int

Returns the number of periods for which media is available. Must not be called until onPrepared is triggered.

getTrackGroups

fun getTrackGroups(periodIndex: Int): TrackGroupArray!

Returns the track groups for the given period. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Use getMappedTrackInfo to get the track groups mapped to renderers.

Parameters
periodIndex: Int

The period index.
Returns
TrackGroupArray!

The track groups for the period. May be EMPTY for single stream content.

getTrackSelections

fun getTrackSelections(periodIndex: Int, rendererIndex: Int): (Mutable)List<ExoTrackSelection!>!

Returns all track selections for a period and renderer. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index.
rendererIndex: Int

The renderer index.
Returns
(Mutable)List<ExoTrackSelection!>!

A list of selected track selections.

getTracks

fun getTracks(periodIndex: Int): Tracks!

Returns Tracks for the given period. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index.
Returns
Tracks!

The Tracks for the period. May be EMPTY for single stream content.

prepare

fun prepare(callback: DownloadHelper.Callback!): Unit

Initializes the helper for starting a download.

Parameters
callback: DownloadHelper.Callback!

A callback to be notified when preparation completes or fails.
Throws
java.lang.IllegalStateException

If the download helper has already been prepared.

release

fun release(): Unit

Releases the helper and all resources it is holding.

replaceTrackSelections

fun replaceTrackSelections(
    periodIndex: Int,
    trackSelectionParameters: TrackSelectionParameters!
): Unit

Replaces a selection of tracks to be downloaded. Must not be called until onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
periodIndex: Int

The period index for which the track selection is replaced.
trackSelectionParameters: TrackSelectionParameters!

The TrackSelectionParameters to obtain the new selection of tracks.