Package com.google.android.exoplayer2.offline

## Class DownloadHelper

- java.lang.Object
- - com.google.android.exoplayer2.offline.DownloadHelper

-     public final class DownloadHelper
      extends Object

  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(Callback)` and wait for the callback.
  3. Optional: Inspect the selected tracks using `getMappedTrackInfo(int)` and `getTrackSelections(int, int)`, and make adjustments using `clearTrackSelections(int)`, `replaceTrackSelections(int, Parameters)` and `addTrackSelection(int, Parameters)`.
  4. Create a download request for the selected track using `getDownloadRequest(byte[])`.
  5. Release the helper using `release()`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static interface` | `DownloadHelper.Callback` | A callback to be notified when the `DownloadHelper` is prepared.
    `static class` | `DownloadHelper.LiveContentUnsupportedException` | Thrown at an attempt to download live content.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static DefaultTrackSelector.Parameters` | `DEFAULT_TRACK_SELECTOR_PARAMETERS` | Deprecated. This instance does not have `Context` constraints.
    `static DefaultTrackSelector.Parameters` | `DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_CONTEXT` | Default track selection parameters for downloading, but without any `Context` constraints.
    `static DefaultTrackSelector.Parameters` | `DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_VIEWPORT` | Deprecated. This instance does not have `Context` constraints.

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DownloadHelper​(MediaItem mediaItem, MediaSource mediaSource, DefaultTrackSelector.Parameters trackSelectorParameters, RendererCapabilities[] rendererCapabilities)` | Creates download helper.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `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, DefaultTrackSelector.Parameters trackSelectorParameters)` | 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, DrmSessionManager drmSessionManager)` | Utility method to create a `MediaSource` that only exposes the tracks defined in `downloadRequest`.
    `static DownloadHelper` | `forDash​(Context context, Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.
    `static DownloadHelper` | `forDash​(Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory, DrmSessionManager drmSessionManager, DefaultTrackSelector.Parameters trackSelectorParameters)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory, DrmSessionManager)` instead.
    `static DownloadHelper` | `forHls​(Context context, Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.
    `static DownloadHelper` | `forHls​(Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory, DrmSessionManager drmSessionManager, DefaultTrackSelector.Parameters trackSelectorParameters)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory, DrmSessionManager)` instead.
    `static DownloadHelper` | `forMediaItem​(Context context, MediaItem mediaItem)` | Creates a `DownloadHelper` for the given progressive media item.
    `static DownloadHelper` | `forMediaItem​(Context context, MediaItem mediaItem, RenderersFactory renderersFactory, DataSource.Factory dataSourceFactory)` | Creates a `DownloadHelper` for the given media item.
    `static DownloadHelper` | `forMediaItem​(MediaItem mediaItem, DefaultTrackSelector.Parameters trackSelectorParameters, RenderersFactory renderersFactory, DataSource.Factory dataSourceFactory)` | Creates a `DownloadHelper` for the given media item.
    `static DownloadHelper` | `forMediaItem​(MediaItem mediaItem, DefaultTrackSelector.Parameters trackSelectorParameters, RenderersFactory renderersFactory, DataSource.Factory dataSourceFactory, DrmSessionManager drmSessionManager)` | Creates a `DownloadHelper` for the given media item.
    `static DownloadHelper` | `forProgressive​(Context context, Uri uri)` | Deprecated. Use `forMediaItem(Context, MediaItem)`
    `static DownloadHelper` | `forProgressive​(Context context, Uri uri, String cacheKey)` | Deprecated. Use `forMediaItem(Context, MediaItem)`
    `static DownloadHelper` | `forSmoothStreaming​(Context context, Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.
    `static DownloadHelper` | `forSmoothStreaming​(Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.
    `static DownloadHelper` | `forSmoothStreaming​(Uri uri, DataSource.Factory dataSourceFactory, RenderersFactory renderersFactory, DrmSessionManager drmSessionManager, DefaultTrackSelector.Parameters trackSelectorParameters)` | Deprecated. Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory, DrmSessionManager)` instead.
    `static DefaultTrackSelector.Parameters` | `getDefaultTrackSelectorParameters​(Context context)` | Returns the default parameters used for track selection for downloading.
    `DownloadRequest` | `getDownloadRequest​(byte[] data)` | Builds a `DownloadRequest` for downloading the selected tracks.
    `DownloadRequest` | `getDownloadRequest​(String id, byte[] data)` | Builds a `DownloadRequest` for downloading the selected tracks.
    `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)` | 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.
    `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, DefaultTrackSelector.Parameters trackSelectorParameters)` | Replaces a selection of tracks to be downloaded.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### 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(Context)` instead.

      See Also:
        `DefaultTrackSelector.Parameters.DEFAULT_WITHOUT_CONTEXT`

    - #### DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_VIEWPORT

          @Deprecated
          public static final DefaultTrackSelector.Parameters DEFAULT_TRACK_SELECTOR_PARAMETERS_WITHOUT_VIEWPORT

      Deprecated.
      This instance does not have `Context` constraints. Use `getDefaultTrackSelectorParameters(Context)` instead.

    - #### DEFAULT_TRACK_SELECTOR_PARAMETERS

          @Deprecated
          public static final DefaultTrackSelector.Parameters DEFAULT_TRACK_SELECTOR_PARAMETERS

      Deprecated.
      This instance does not have `Context` constraints. Use `getDefaultTrackSelectorParameters(Context)` instead.

  - ### Constructor Detail

    - #### DownloadHelper

          public DownloadHelper​(MediaItem mediaItem,
                                @Nullable
                                MediaSource mediaSource,
                                DefaultTrackSelector.Parameters trackSelectorParameters,
                                RendererCapabilities[] rendererCapabilities)

      Creates download helper.
      Parameters:
        `mediaItem` - The media item.
        `mediaSource` - A `MediaSource` for which tracks are selected, or null if no track selection needs to be made.
        `trackSelectorParameters` - `DefaultTrackSelector.Parameters` for selecting tracks for downloading.
        `rendererCapabilities` - The `RendererCapabilities` of the renderers for which tracks are selected.

  - ### Method Detail

    - #### getDefaultTrackSelectorParameters

          public static DefaultTrackSelector.Parameters getDefaultTrackSelectorParameters​(Context context)

      Returns the default parameters used for track selection for downloading.

    - #### getRendererCapabilities

          public static RendererCapabilities[] getRendererCapabilities​(RenderersFactory renderersFactory)

      Extracts renderer capabilities for the renderers created by the provided renderers factory.
      Parameters:
        `renderersFactory` - A `RenderersFactory`.
      Returns:
        The `RendererCapabilities` for each renderer created by the `renderersFactory`.

    - #### forProgressive

          @Deprecated
          public static DownloadHelper forProgressive​(Context context,
                                                      Uri uri)

      Deprecated.
      Use `forMediaItem(Context, MediaItem)`

    - #### forProgressive

          @Deprecated
          public static DownloadHelper forProgressive​(Context context,
                                                      Uri uri,
                                                      @Nullable
                                                      String cacheKey)

      Deprecated.
      Use `forMediaItem(Context, MediaItem)`

    - #### forDash

          @Deprecated
          public static DownloadHelper forDash​(Context context,
                                               Uri uri,
                                               DataSource.Factory dataSourceFactory,
                                               RenderersFactory renderersFactory)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.

    - #### forDash

          @Deprecated
          public static DownloadHelper forDash​(Uri uri,
                                               DataSource.Factory dataSourceFactory,
                                               RenderersFactory renderersFactory,
                                               @Nullable
                                               DrmSessionManager drmSessionManager,
                                               DefaultTrackSelector.Parameters trackSelectorParameters)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory, DrmSessionManager)` instead.

    - #### forHls

          @Deprecated
          public static DownloadHelper forHls​(Context context,
                                              Uri uri,
                                              DataSource.Factory dataSourceFactory,
                                              RenderersFactory renderersFactory)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.

    - #### forHls

          @Deprecated
          public static DownloadHelper forHls​(Uri uri,
                                              DataSource.Factory dataSourceFactory,
                                              RenderersFactory renderersFactory,
                                              @Nullable
                                              DrmSessionManager drmSessionManager,
                                              DefaultTrackSelector.Parameters trackSelectorParameters)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory, DrmSessionManager)` instead.

    - #### forSmoothStreaming

          @Deprecated
          public static DownloadHelper forSmoothStreaming​(Uri uri,
                                                          DataSource.Factory dataSourceFactory,
                                                          RenderersFactory renderersFactory)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.

    - #### forSmoothStreaming

          @Deprecated
          public static DownloadHelper forSmoothStreaming​(Context context,
                                                          Uri uri,
                                                          DataSource.Factory dataSourceFactory,
                                                          RenderersFactory renderersFactory)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory)` instead.

    - #### forSmoothStreaming

          @Deprecated
          public static DownloadHelper forSmoothStreaming​(Uri uri,
                                                          DataSource.Factory dataSourceFactory,
                                                          RenderersFactory renderersFactory,
                                                          @Nullable
                                                          DrmSessionManager drmSessionManager,
                                                          DefaultTrackSelector.Parameters trackSelectorParameters)

      Deprecated.
      Use `forMediaItem(MediaItem, Parameters, RenderersFactory, DataSource.Factory, DrmSessionManager)` instead.

    - #### forMediaItem

          public static DownloadHelper forMediaItem​(Context context,
                                                    MediaItem mediaItem)

      Creates a `DownloadHelper` for the given progressive media item.
      Parameters:
        `context` - The context.
        `mediaItem` - A `MediaItem`.
      Returns:
        A `DownloadHelper` for progressive streams.
      Throws:
        `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` - The context.
        `mediaItem` - A `MediaItem`.
        `renderersFactory` - A `RenderersFactory` creating the renderers for which tracks are selected.
        `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:
        A `DownloadHelper`.
      Throws:
        `IllegalStateException` - If the corresponding module is missing for DASH, HLS or SmoothStreaming media items.
        `IllegalArgumentException` - If the `dataSourceFactory` is null for adaptive streams.

    - #### forMediaItem

          public static DownloadHelper forMediaItem​(MediaItem mediaItem,
                                                    DefaultTrackSelector.Parameters trackSelectorParameters,
                                                    @Nullable
                                                    RenderersFactory renderersFactory,
                                                    @Nullable
                                                    DataSource.Factory dataSourceFactory)

      Creates a `DownloadHelper` for the given media item.
      Parameters:
        `mediaItem` - A `MediaItem`.
        `renderersFactory` - A `RenderersFactory` creating the renderers for which tracks are selected.
        `trackSelectorParameters` - `DefaultTrackSelector.Parameters` for selecting tracks for downloading.
        `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:
        A `DownloadHelper`.
      Throws:
        `IllegalStateException` - If the corresponding module is missing for DASH, HLS or SmoothStreaming media items.
        `IllegalArgumentException` - If the `dataSourceFactory` is null for adaptive streams.

    - #### forMediaItem

          public static DownloadHelper forMediaItem​(MediaItem mediaItem,
                                                    DefaultTrackSelector.Parameters trackSelectorParameters,
                                                    @Nullable
                                                    RenderersFactory renderersFactory,
                                                    @Nullable
                                                    DataSource.Factory dataSourceFactory,
                                                    @Nullable
                                                    DrmSessionManager drmSessionManager)

      Creates a `DownloadHelper` for the given media item.
      Parameters:
        `mediaItem` - A `MediaItem`.
        `renderersFactory` - A `RenderersFactory` creating the renderers for which tracks are selected.
        `trackSelectorParameters` - `DefaultTrackSelector.Parameters` for selecting tracks for downloading.
        `dataSourceFactory` - A `DataSource.Factory` used to load the manifest for adaptive streams. This argument is required for adaptive streams and ignored for progressive streams.
        `drmSessionManager` - An optional `DrmSessionManager`. Used to help determine which tracks can be selected.
      Returns:
        A `DownloadHelper`.
      Throws:
        `IllegalStateException` - If the corresponding module is missing for DASH, HLS or SmoothStreaming media items.
        `IllegalArgumentException` - If the `dataSourceFactory` is null for adaptive streams.

    - #### 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` - A `DownloadRequest`.
        `dataSourceFactory` - A factory for `DataSource`s to read the media.
        `drmSessionManager` - An optional `DrmSessionManager` to be passed to the `MediaSource`.
      Returns:
        A `MediaSource` that only exposes the tracks defined in `downloadRequest`.

    - #### prepare

          public void prepare​(DownloadHelper.Callback callback)

      Initializes the helper for starting a download.
      Parameters:
        `callback` - A callback to be notified when preparation completes or fails.
      Throws:
        `IllegalStateException` - If the download helper has already been prepared.

    - #### release

          public void release()

      Releases the helper and all resources it is holding.

    - #### getManifest

          @Nullable
          public Object getManifest()

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

    - #### getPeriodCount

          public int getPeriodCount()

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

    - #### getTrackGroups

          public TrackGroupArray getTrackGroups​(int periodIndex)

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

      Use `getMappedTrackInfo(int)` to get the track groups mapped to renderers.

      Parameters:
        `periodIndex` - The period index.
      Returns:
        The track groups for the period. May be `TrackGroupArray.EMPTY` for single stream content.

    - #### 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:
        `periodIndex` - The period index.
      Returns:
        The `MappingTrackSelector.MappedTrackInfo` for the period.

    - #### 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:
        `periodIndex` - The period index.
        `rendererIndex` - The renderer index.
      Returns:
        A list of selected `track selections`.

    - #### clearTrackSelections

          public void clearTrackSelections​(int periodIndex)

      Clears the selection of tracks for a period. Must not be called until after preparation completes.
      Parameters:
        `periodIndex` - The period index for which track selections are cleared.

    - #### replaceTrackSelections

          public void replaceTrackSelections​(int periodIndex,
                                             DefaultTrackSelector.Parameters trackSelectorParameters)

      Replaces a selection of tracks to be downloaded. Must not be called until after preparation completes.
      Parameters:
        `periodIndex` - The period index for which the track selection is replaced.
        `trackSelectorParameters` - The `DefaultTrackSelector.Parameters` to obtain the new selection of tracks.

    - #### addTrackSelection

          public void addTrackSelection​(int periodIndex,
                                        DefaultTrackSelector.Parameters trackSelectorParameters)

      Adds a selection of tracks to be downloaded. Must not be called until after preparation completes.
      Parameters:
        `periodIndex` - The period index this track selection is added for.
        `trackSelectorParameters` - The `DefaultTrackSelector.Parameters` to obtain the new selection of tracks.

    - #### 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:
        `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:
        `selectUndeterminedTextLanguage` - Whether a text track with undetermined language should be selected for downloading if no track with one of the specified `languages` is available.
        `languages` - A list of text languages for which tracks should be added to the download selection, as IETF BCP 47 conformant tags.

    - #### 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:
        `periodIndex` - The period index the track selection is added for.
        `rendererIndex` - The renderer index the track selection is added for.
        `trackSelectorParameters` - The `DefaultTrackSelector.Parameters` to obtain the new selection of tracks.
        `overrides` - A list of `SelectionOverrides` to apply to the `trackSelectorParameters`. If empty, `trackSelectorParameters` are used as they are.

    - #### 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:
        `data` - Application provided data to store in `DownloadRequest.data`.
      Returns:
        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:
        `id` - The unique content id.
        `data` - Application provided data to store in `DownloadRequest.data`.
      Returns:
        The built `DownloadRequest`.