@UnstableApi
public final 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
public interface DownloadHelper.Callback

A callback to be notified when the DownloadHelper is prepared.

Thrown at an attempt to download live content.

Constants
static final DefaultTrackSelector.Parameters

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

Public constructors
DownloadHelper(
    MediaItem mediaItem,
    @Nullable MediaSource mediaSource,
    TrackSelectionParameters trackSelectionParameters,
    RendererCapabilities[] rendererCapabilities
)

Creates download helper.

Public methods
void
addAudioLanguagesToSelection(String[] languages)

Convenience method to add selections of tracks for all specified audio languages.
void
addTextLanguagesToSelection(
    boolean selectUndeterminedTextLanguage,
    String[] languages
)

Convenience method to add selections of tracks for all specified text languages.
void
addTrackSelection(
    int periodIndex,
    TrackSelectionParameters trackSelectionParameters
)

Adds a selection of tracks to be downloaded.
void
addTrackSelectionForSingleRenderer(
    int periodIndex,
    int rendererIndex,
    DefaultTrackSelector.Parameters trackSelectorParameters,
    List<DefaultTrackSelector.SelectionOverride> overrides
)

Convenience method to add a selection of tracks to be downloaded for a single renderer.
void
clearTrackSelections(int periodIndex)

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

Equivalent to createMediaSource(downloadRequest, dataSourceFactory, null).
static MediaSource
createMediaSource(
    DownloadRequest downloadRequest,
    DataSource.Factory dataSourceFactory,
    @Nullable DrmSessionManager drmSessionManager
)

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

Creates a DownloadHelper for the given progressive media item.
static DownloadHelper
forMediaItem(
    Context context,
    MediaItem mediaItem,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory
)

Creates a DownloadHelper for the given media item.
static DownloadHelper
forMediaItem(
    MediaItem mediaItem,
    TrackSelectionParameters trackSelectionParameters,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory
)

Creates a DownloadHelper for the given media item.
static DownloadHelper
forMediaItem(
    MediaItem mediaItem,
    TrackSelectionParameters trackSelectionParameters,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory,
    @Nullable DrmSessionManager drmSessionManager
)

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

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

Builds a DownloadRequest for downloading the selected tracks.
DownloadRequest
getDownloadRequest(String id, @Nullable byte[] data)

Builds a DownloadRequest for downloading the selected tracks.
@Nullable Object

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

Returns the mapped track info for the given period.
int

Returns the number of periods for which media is available.
static RendererCapabilities[]

Extracts renderer capabilities for the renderers created by the provided renderers factory.
TrackGroupArray
getTrackGroups(int periodIndex)

Returns the track groups for the given period.
List<ExoTrackSelection>
getTrackSelections(int periodIndex, int rendererIndex)

Returns all track selections for a period and renderer.
Tracks
getTracks(int periodIndex)

Returns Tracks for the given period.
void

Initializes the helper for starting a download.
void

Releases the helper and all resources it is holding.
void
replaceTrackSelections(
    int periodIndex,
    TrackSelectionParameters trackSelectionParameters
)

Replaces a selection of tracks to be downloaded.

Constants

DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT

public static final DefaultTrackSelector.Parameters DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT

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

If possible, use getDefaultTrackSelectorParameters instead.

See also
DEFAULT_WITHOUT_CONTEXT

Public constructors

DownloadHelper

public DownloadHelper(
    MediaItem mediaItem,
    @Nullable MediaSource mediaSource,
    TrackSelectionParameters trackSelectionParameters,
    RendererCapabilities[] rendererCapabilities
)

Creates download helper.

Parameters
MediaItem mediaItem

The media item.
@Nullable 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[] rendererCapabilities

The RendererCapabilities of the renderers for which tracks are selected.

Public methods

addAudioLanguagesToSelection

public void addAudioLanguagesToSelection(String[] languages)

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
String[] languages

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

addTextLanguagesToSelection

public void addTextLanguagesToSelection(
    boolean selectUndeterminedTextLanguage,
    String[] languages
)

Convenience method to add selections of tracks for all specified text languages. Must not be called until after preparation completes.

Parameters
boolean selectUndeterminedTextLanguage

Whether a text track with undetermined language should be selected for downloading if no track with one of the specified languages is available.
String[] languages

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

addTrackSelection

public void addTrackSelection(
    int periodIndex,
    TrackSelectionParameters trackSelectionParameters
)

Adds a selection of tracks to be downloaded. Must not be called until after preparation completes.

Parameters
int periodIndex

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

The TrackSelectionParameters to obtain the new selection of tracks.

addTrackSelectionForSingleRenderer

public void addTrackSelectionForSingleRenderer(
    int periodIndex,
    int rendererIndex,
    DefaultTrackSelector.Parameters trackSelectorParameters,
    List<DefaultTrackSelector.SelectionOverride> overrides
)

Convenience method to add a selection of tracks to be downloaded for a single renderer. Must not be called until after preparation completes.

Parameters
int periodIndex

The period index the track selection is added for.
int rendererIndex

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

The DefaultTrackSelector.Parameters to obtain the new selection of tracks.
List<DefaultTrackSelector.SelectionOverride> overrides

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

clearTrackSelections

public void clearTrackSelections(int periodIndex)

Clears the selection of tracks for a period. Must not be called until after preparation completes.

Parameters
int periodIndex

The period index for which track selections are cleared.

createMediaSource

public static MediaSource createMediaSource(
    DownloadRequest downloadRequest,
    DataSource.Factory dataSourceFactory
)

Equivalent to createMediaSource(downloadRequest, dataSourceFactory, null).

createMediaSource

public static MediaSource createMediaSource(
    DownloadRequest downloadRequest,
    DataSource.Factory dataSourceFactory,
    @Nullable DrmSessionManager drmSessionManager
)

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

Parameters
DownloadRequest downloadRequest

A DownloadRequest.
DataSource.Factory dataSourceFactory

A factory for DataSources to read the media.
@Nullable DrmSessionManager drmSessionManager

An optional DrmSessionManager to be passed to the .
Returns
MediaSource

A MediaSource that only exposes the tracks defined in downloadRequest.

forMediaItem

public static DownloadHelper forMediaItem(Context context, MediaItem mediaItem)

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

public static DownloadHelper forMediaItem(
    Context context,
    MediaItem mediaItem,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory
)

Creates a DownloadHelper for the given media item.

Parameters
Context context

The context.
MediaItem mediaItem

A MediaItem.
@Nullable RenderersFactory renderersFactory

A RenderersFactory creating the renderers for which tracks are selected.
@Nullable DataSource.Factory dataSourceFactory

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

public static DownloadHelper forMediaItem(
    MediaItem mediaItem,
    TrackSelectionParameters trackSelectionParameters,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory
)

Creates a DownloadHelper for the given media item.

Parameters
MediaItem mediaItem

A MediaItem.
TrackSelectionParameters trackSelectionParameters

TrackSelectionParameters for selecting tracks for downloading.
@Nullable RenderersFactory renderersFactory

A RenderersFactory creating the renderers for which tracks are selected.
@Nullable DataSource.Factory dataSourceFactory

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

public static DownloadHelper forMediaItem(
    MediaItem mediaItem,
    TrackSelectionParameters trackSelectionParameters,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory,
    @Nullable DrmSessionManager drmSessionManager
)

Creates a DownloadHelper for the given media item.

Parameters
MediaItem mediaItem

A MediaItem.
TrackSelectionParameters trackSelectionParameters

TrackSelectionParameters for selecting tracks for downloading.
@Nullable RenderersFactory renderersFactory

A RenderersFactory creating the renderers for which tracks are selected.
@Nullable DataSource.Factory dataSourceFactory

A DataSource.Factory used to load the manifest for adaptive streams. This argument is required for adaptive streams and ignored for progressive streams.
@Nullable 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

public static DefaultTrackSelector.Parameters getDefaultTrackSelectorParameters(Context context)

Returns the default parameters used for track selection for downloading.

getDownloadRequest

public DownloadRequest getDownloadRequest(@Nullable byte[] data)

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
@Nullable byte[] data

Application provided data to store in data.
Returns
DownloadRequest

The built DownloadRequest.

getDownloadRequest

public DownloadRequest getDownloadRequest(String id, @Nullable byte[] data)

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

Parameters
String id

The unique content id.
@Nullable byte[] data

Application provided data to store in data.
Returns
DownloadRequest

The built DownloadRequest.

getManifest

public @Nullable Object getManifest()

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

getMappedTrackInfo

public MappingTrackSelector.MappedTrackInfo getMappedTrackInfo(int periodIndex)

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

Parameters
int periodIndex

The period index.
Returns
MappingTrackSelector.MappedTrackInfo

The MappedTrackInfo for the period.

getPeriodCount

public int getPeriodCount()

Returns the number of periods for which media is available. Must not be called until after preparation completes.

getRendererCapabilities

public static RendererCapabilities[] getRendererCapabilities(RenderersFactory renderersFactory)

Extracts renderer capabilities for the renderers created by the provided renderers factory.

Parameters
RenderersFactory renderersFactory

A RenderersFactory.
Returns
RendererCapabilities[]

The RendererCapabilities for each renderer created by the renderersFactory.

getTrackGroups

public TrackGroupArray getTrackGroups(int periodIndex)

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
int periodIndex

The period index.
Returns
TrackGroupArray

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

getTrackSelections

public List<ExoTrackSelection> getTrackSelections(int periodIndex, int rendererIndex)

Returns all track selections for a period and renderer. Must not be called until after preparation completes.

Parameters
int periodIndex

The period index.
int rendererIndex

The renderer index.
Returns
List<ExoTrackSelection>

A list of selected track selections.

getTracks

public Tracks getTracks(int periodIndex)

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

Parameters
int periodIndex

The period index.
Returns
Tracks

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

prepare

public void prepare(DownloadHelper.Callback callback)

Initializes the helper for starting a download.

Parameters
DownloadHelper.Callback callback

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

If the download helper has already been prepared.

release

public void release()

Releases the helper and all resources it is holding.

replaceTrackSelections

public void replaceTrackSelections(
    int periodIndex,
    TrackSelectionParameters trackSelectionParameters
)

Replaces a selection of tracks to be downloaded. Must not be called until after preparation completes.

Parameters
int periodIndex

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

The TrackSelectionParameters to obtain the new selection of tracks.