DownloadHelper

Artifact: androidx.media3:media3-exoplayer

View Source

---

Kotlin |Java

@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 class DownloadHelper.LiveContentUnsupportedException extends IOException Thrown at an attempt to download live content.

Constants
static final DefaultTrackSelector.Parameters	DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT Default track selection parameters for downloading, but without any Context constraints.

Public constructors
DownloadHelper(     MediaItem mediaItem,     @Nullable MediaSource mediaSource,     TrackSelectionParameters trackSelectionParameters,     RendererCapabilities[] rendererCapabilities ) This method 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,     @Nullable MediaSource mediaSource,     TrackSelectionParameters trackSelectionParameters,     RendererCapabilitiesList 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	getDefaultTrackSelectorParameters(Context context) Returns the default parameters used for track selection for downloading.
DownloadRequest	getDownloadRequest(@Nullable byte[] data) 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	getManifest() 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	getPeriodCount() Returns the number of periods for which media is available.
static RendererCapabilities[]	getRendererCapabilities(RenderersFactory renderersFactory) This method is deprecated. This method leaks un-released Renderer instances.
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	prepare(DownloadHelper.Callback callback) Initializes the helper for starting a download.
void	release() 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
)

This method 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). Use DownloadHelper instead to avoid needing to manually manage this bookkeeping.

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.

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)

This method is deprecated.

This method leaks un-released Renderer instances. There is no direct replacement. Equivalent functionality can be implemented by constructing the renderer instances, calling getCapabilities on each one, then releasing the renderers when the capabilities are no longer required.

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.