@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.
public final class DownloadHelper.Factory

A factory of DownloadHelper.

Thrown at an attempt to download live content.

Constants
static final DefaultTrackSelector.Parameters

Default track selection parameters for downloading.
static final DefaultTrackSelector.Parameters

This field is deprecated.

Use DEFAULT_TRACK_SELECTOR_PARAMETERS instead.

Public constructors
DownloadHelper(
    MediaItem mediaItem,
    @Nullable MediaSource mediaSource,
    TrackSelectionParameters trackSelectionParameters,
    RendererCapabilitiesList rendererCapabilities
)

Creates download helper.
DownloadHelper(
    MediaItem mediaItem,
    @Nullable MediaSource mediaSource,
    TrackSelectionParameters trackSelectionParameters,
    RendererCapabilitiesList rendererCapabilities,
    boolean debugLoggingEnabled
)

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)

This method is deprecated.

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

This method is deprecated.

Use create instead.
static DownloadHelper
forMediaItem(
    Context context,
    MediaItem mediaItem,
    DataSource.Factory dataSourceFactory,
    boolean debugLoggingEnabled
)

This method is deprecated.

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

This method is deprecated.

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

This method is deprecated.

Use create instead.
static DownloadHelper
forMediaItem(
    Context context,
    MediaItem mediaItem,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory,
    boolean debugLoggingEnabled
)

This method is deprecated.

Use create instead.
static DownloadHelper
forMediaItem(
    MediaItem mediaItem,
    TrackSelectionParameters trackSelectionParameters,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory,
    boolean debugLoggingEnabled
)

This method is deprecated.

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

This method is deprecated.

Use create instead.
static DownloadHelper
forMediaItem(
    MediaItem mediaItem,
    TrackSelectionParameters trackSelectionParameters,
    @Nullable RenderersFactory renderersFactory,
    @Nullable DataSource.Factory dataSourceFactory,
    @Nullable DrmSessionManager drmSessionManager,
    boolean debugLoggingEnabled
)

This method is deprecated.

Use create instead.
static DefaultTrackSelector.Parameters

This method is deprecated.

Use DEFAULT_TRACK_SELECTOR_PARAMETERS instead.
DownloadRequest

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

Builds a DownloadRequest for downloading the selected tracks.
DownloadRequest
getDownloadRequest(
    @Nullable byte[] data,
    long startPositionMs,
    long durationMs
)

Builds a DownloadRequest for downloading the selected tracks and time range.
DownloadRequest
getDownloadRequest(
    String id,
    @Nullable byte[] data,
    long startPositionMs,
    long durationMs
)

Builds a DownloadRequest for downloading the selected tracks and time range.
@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.
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

public static final DefaultTrackSelector.Parameters DEFAULT_TRACK_SELECTOR_PARAMETERS

Default track selection parameters for downloading.

DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT

public static final DefaultTrackSelector.Parameters DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT

Public constructors

DownloadHelper

public DownloadHelper(
    MediaItem mediaItem,
    @Nullable MediaSource mediaSource,
    TrackSelectionParameters trackSelectionParameters,
    RendererCapabilitiesList 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.
RendererCapabilitiesList rendererCapabilities

The RendererCapabilitiesList of the renderers for which tracks are selected.

DownloadHelper

public DownloadHelper(
    MediaItem mediaItem,
    @Nullable MediaSource mediaSource,
    TrackSelectionParameters trackSelectionParameters,
    RendererCapabilitiesList rendererCapabilities,
    boolean debugLoggingEnabled
)

Creates download helper.

Parameters
MediaItem mediaItem

The media item.
@Nullable MediaSource mediaSource

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

TrackSelectionParameters for selecting tracks for downloading.
RendererCapabilitiesList rendererCapabilities

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

Whether to log debug information.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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)

forMediaItem

public static DownloadHelper forMediaItem(
    Context context,
    MediaItem mediaItem,
    DataSource.Factory dataSourceFactory
)

forMediaItem

public static DownloadHelper forMediaItem(
    Context context,
    MediaItem mediaItem,
    DataSource.Factory dataSourceFactory,
    boolean debugLoggingEnabled
)

forMediaItem

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

forMediaItem

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

forMediaItem

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

forMediaItem

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

forMediaItem

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

forMediaItem

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

getDefaultTrackSelectorParameters

public static DefaultTrackSelector.Parameters getDefaultTrackSelectorParameters(Context context)

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.

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.

getDownloadRequest

public DownloadRequest getDownloadRequest(
    @Nullable byte[] data,
    long startPositionMs,
    long durationMs
)

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

Application provided data to store in data.
long startPositionMs

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.
long durationMs

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

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

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
String id

The unique content id.
@Nullable byte[] data

Application provided data to store in data.
long startPositionMs

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.
long durationMs

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

public @Nullable Object getManifest()

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

getMappedTrackInfo

public MappingTrackSelector.MappedTrackInfo getMappedTrackInfo(int periodIndex)

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

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 onPrepared is triggered.

getTrackGroups

public TrackGroupArray getTrackGroups(int periodIndex)

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
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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

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 onPrepared is triggered and the passed tracksInfoAvailable is true.

Parameters
int periodIndex

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

The TrackSelectionParameters to obtain the new selection of tracks.