@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.

Thrown at an attempt to download live content.

Constants
const DefaultTrackSelector.Parameters!

Default track selection parameters for downloading, but without any Context constraints.

Public constructors
DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: Array<RendererCapabilities!>!
)

This function is deprecated.

The Renderer instances used to produce rendererCapabilities must be kept alive for the lifetime of this DownloadHelper instance and then released (to avoid a resource leak).
DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: RendererCapabilitiesList!
)

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!)

Creates a DownloadHelper for the given progressive media item.
java-static DownloadHelper!
forMediaItem(
    context: Context!,
    mediaItem: MediaItem!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?
)

Creates a DownloadHelper for the given media item.
java-static DownloadHelper!
forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?
)

Creates a DownloadHelper for the given media item.
java-static DownloadHelper!
forMediaItem(
    mediaItem: MediaItem!,
    trackSelectionParameters: TrackSelectionParameters!,
    renderersFactory: RenderersFactory?,
    dataSourceFactory: DataSource.Factory?,
    drmSessionManager: DrmSessionManager?
)

Creates a DownloadHelper for the given media item.
java-static DefaultTrackSelector.Parameters!

Returns the default parameters used for track selection for downloading.
DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks.
DownloadRequest!

Builds a DownloadRequest for downloading the selected tracks.
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.
java-static Array<RendererCapabilities!>!

This function is deprecated.

This method leaks un-released Renderer instances.
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_WITHOUT_CONTEXT

const val DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT: DefaultTrackSelector.Parameters!

Default track selection parameters for downloading, but without any Context constraints.

If possible, use getDefaultTrackSelectorParameters instead.

See also
DEFAULT_WITHOUT_CONTEXT

Public constructors

DownloadHelper

DownloadHelper(
    mediaItem: MediaItem!,
    mediaSource: MediaSource?,
    trackSelectionParameters: TrackSelectionParameters!,
    rendererCapabilities: Array<RendererCapabilities!>!
)

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.

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 after preparation completes.

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 after preparation completes.

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 after preparation completes.

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 after preparation completes.

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 after preparation completes.

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!

Creates a DownloadHelper for the given progressive media item.

Parameters
context: Context!

The context.
mediaItem: MediaItem!

A MediaItem.
Returns
DownloadHelper!

A DownloadHelper for progressive streams.
Throws
java.lang.IllegalStateException

If the media item is of type DASH, HLS or SmoothStreaming.

forMediaItem

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

Creates a DownloadHelper for the given media item.

Parameters
context: Context!

The context.
mediaItem: MediaItem!

A MediaItem.
renderersFactory: RenderersFactory?

A RenderersFactory creating the renderers for which tracks are selected.
dataSourceFactory: DataSource.Factory?

A DataSource.Factory used to load the manifest for adaptive streams. This argument is required for adaptive streams and ignored for progressive streams.
Returns
DownloadHelper!

A DownloadHelper.
Throws
java.lang.IllegalStateException

If the corresponding module is missing for DASH, HLS or SmoothStreaming media items.
java.lang.IllegalArgumentException

If the dataSourceFactory is null for adaptive streams.

forMediaItem

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

Creates a DownloadHelper for the given media item.

Parameters
mediaItem: MediaItem!

A MediaItem.
trackSelectionParameters: TrackSelectionParameters!

TrackSelectionParameters for selecting tracks for downloading.
renderersFactory: RenderersFactory?

A RenderersFactory creating the renderers for which tracks are selected.
dataSourceFactory: DataSource.Factory?

A DataSource.Factory used to load the manifest for adaptive streams. This argument is required for adaptive streams and ignored for progressive streams.
Returns
DownloadHelper!

A DownloadHelper.
Throws
java.lang.IllegalStateException

If the corresponding module is missing for DASH, HLS or SmoothStreaming media items.
java.lang.IllegalArgumentException

If the dataSourceFactory is null for adaptive streams.

forMediaItem

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

Creates a DownloadHelper for the given media item.

Parameters
mediaItem: MediaItem!

A MediaItem.
trackSelectionParameters: TrackSelectionParameters!

TrackSelectionParameters for selecting tracks for downloading.
renderersFactory: RenderersFactory?

A RenderersFactory creating the renderers for which tracks are selected.
dataSourceFactory: DataSource.Factory?

A DataSource.Factory used to load the manifest for adaptive streams. This argument is required for adaptive streams and ignored for progressive streams.
drmSessionManager: DrmSessionManager?

An optional DrmSessionManager. Used to help determine which tracks can be selected.
Returns
DownloadHelper!

A DownloadHelper.
Throws
java.lang.IllegalStateException

If the corresponding module is missing for DASH, HLS or SmoothStreaming media items.
java.lang.IllegalArgumentException

If the dataSourceFactory is null for adaptive streams.

getDefaultTrackSelectorParameters

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

Returns the default parameters used for track selection for downloading.

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.
Returns
DownloadRequest!

The built DownloadRequest.

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.
Returns
DownloadRequest!

The built DownloadRequest.

getManifest

fun getManifest(): Any?

Returns the manifest, or null if no manifest is loaded. Must not be called until after preparation completes.

getMappedTrackInfo

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

Returns the mapped track info for the given period. Must not be called until after preparation completes.

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 after preparation completes.

getRendererCapabilities

java-static fun getRendererCapabilities(renderersFactory: RenderersFactory!): Array<RendererCapabilities!>!

getTrackGroups

fun getTrackGroups(periodIndex: Int): TrackGroupArray!

Returns the track groups for the given period. Must not be called until after preparation completes.

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 after preparation completes.

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 after preparation completes.

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 after preparation completes.

Parameters
periodIndex: Int

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

The TrackSelectionParameters to obtain the new selection of tracks.