Package com.google.android.exoplayer2.trackselection

## Class DefaultTrackSelector

- java.lang.Object
- - com.google.android.exoplayer2.trackselection.TrackSelector
  - - com.google.android.exoplayer2.trackselection.MappingTrackSelector
    - - com.google.android.exoplayer2.trackselection.DefaultTrackSelector

- Direct Known Subclasses:
    `FakeTrackSelector`

      public class DefaultTrackSelector
      extends MappingTrackSelector

  A default `TrackSelector` suitable for most use cases. Track selections are made according to configurable `DefaultTrackSelector.Parameters`, which can be set by calling `setParameters(Parameters)`.

  ### Modifying parameters

  To modify only some aspects of the parameters currently used by a selector, it's possible to obtain a `DefaultTrackSelector.ParametersBuilder` initialized with the current `DefaultTrackSelector.Parameters`. The desired modifications can be made on the builder, and the resulting `DefaultTrackSelector.Parameters` can then be built and set on the selector. For example the following code modifies the parameters to restrict video track selections to SD, and to select a German audio track if there is one:

       // Build on the current parameters.
       Parameters currentParameters = trackSelector.getParameters();
       // Build the resulting parameters.
       Parameters newParameters = currentParameters
           .buildUpon()
           .setMaxVideoSizeSd()
           .setPreferredAudioLanguage("deu")
           .build();
       // Set the new parameters.
       trackSelector.setParameters(newParameters);

  Convenience methods and chaining allow this to be written more concisely as:

       trackSelector.setParameters(
           trackSelector
               .buildUponParameters()
               .setMaxVideoSizeSd()
               .setPreferredAudioLanguage("deu"));

  Selection `DefaultTrackSelector.Parameters` support many different options, some of which are described below.

  ### Selecting specific tracks

  Track selection overrides can be used to select specific tracks. To specify an override for a renderer, it's first necessary to obtain the tracks that have been mapped to it:

       MappedTrackInfo mappedTrackInfo = trackSelector.getCurrentMappedTrackInfo();
       TrackGroupArray rendererTrackGroups = mappedTrackInfo == null ? null
           : mappedTrackInfo.getTrackGroups(rendererIndex);

  If `rendererTrackGroups` is null then there aren't any currently mapped tracks, and so setting an override isn't possible. Note that a `Player.Listener` registered on the player can be used to determine when the current tracks (and therefore the mapping) changes. If `rendererTrackGroups` is non-null then an override can be set. The next step is to query the properties of the available tracks to determine the `groupIndex` and the `trackIndices` within the group it that should be selected. The override can then be specified using `DefaultTrackSelector.ParametersBuilder.setSelectionOverride(int, com.google.android.exoplayer2.source.TrackGroupArray, com.google.android.exoplayer2.trackselection.DefaultTrackSelector.SelectionOverride)`:

       SelectionOverride selectionOverride = new SelectionOverride(groupIndex, trackIndices);
       trackSelector.setParameters(
           trackSelector
               .buildUponParameters()
               .setSelectionOverride(rendererIndex, rendererTrackGroups, selectionOverride));

  ### Constraint based track selection

  Whilst track selection overrides make it possible to select specific tracks, the recommended way of controlling which tracks are selected is by specifying constraints. For example consider the case of wanting to restrict video track selections to SD, and preferring German audio tracks. Track selection overrides could be used to select specific tracks meeting these criteria, however a simpler and more flexible approach is to specify these constraints directly:

       trackSelector.setParameters(
           trackSelector
               .buildUponParameters()
               .setMaxVideoSizeSd()
               .setPreferredAudioLanguage("deu"));

  There are several benefits to using constraint based track selection instead of specific track overrides:
  - You can specify constraints before knowing what tracks the media provides. This can simplify track selection code (e.g. you don't have to listen for changes in the available tracks before configuring the selector).
  - Constraints can be applied consistently across all periods in a complex piece of media, even if those periods contain different tracks. In contrast, a specific track override is only applied to periods whose tracks match those for which the override was set.

  ### Disabling renderers

  Renderers can be disabled using `DefaultTrackSelector.ParametersBuilder.setRendererDisabled(int, boolean)`. Disabling a renderer differs from setting a `null` override because the renderer is disabled unconditionally, whereas a `null` override is applied only when the track groups available to the renderer match the `TrackGroupArray` for which it was specified.

  ### Tunneling

  Tunneled playback can be enabled in cases where the combination of renderers and selected tracks support it. Tunneled playback is enabled by passing an audio session ID to `DefaultTrackSelector.ParametersBuilder.setTunnelingEnabled(boolean)`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `protected static class` | `DefaultTrackSelector.AudioTrackScore` | Represents how well an audio track matches the selection `DefaultTrackSelector.Parameters`.
    `protected static class` | `DefaultTrackSelector.OtherTrackScore` | Represents how well any other track (non video, audio or text) matches the selection `DefaultTrackSelector.Parameters`.
    `static class` | `DefaultTrackSelector.Parameters` | Extends `TrackSelectionParameters` by adding fields that are specific to `DefaultTrackSelector`.
    `static class` | `DefaultTrackSelector.ParametersBuilder` | A builder for `DefaultTrackSelector.Parameters`.
    `static class` | `DefaultTrackSelector.SelectionOverride` | A track selection override.
    `protected static class` | `DefaultTrackSelector.TextTrackScore` | Represents how well a text track matches the selection `DefaultTrackSelector.Parameters`.
    `protected static class` | `DefaultTrackSelector.VideoTrackScore` | Represents how well a video track matches the selection `DefaultTrackSelector.Parameters`.

    - ### Nested classes/interfaces inherited from class com.google.android.exoplayer2.trackselection.MappingTrackSelector

      `MappingTrackSelector.MappedTrackInfo`

    - ### Nested classes/interfaces inherited from class com.google.android.exoplayer2.trackselection.TrackSelector

      `TrackSelector.InvalidationListener`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultTrackSelector()` | Deprecated. Use `DefaultTrackSelector(Context)` instead.
    `DefaultTrackSelector​(Context context)` |
    `DefaultTrackSelector​(Context context, ExoTrackSelection.Factory trackSelectionFactory)` |
    `DefaultTrackSelector​(DefaultTrackSelector.Parameters parameters, ExoTrackSelection.Factory trackSelectionFactory)` |
    `DefaultTrackSelector​(ExoTrackSelection.Factory trackSelectionFactory)` | Deprecated. Use `DefaultTrackSelector(Context, ExoTrackSelection.Factory)`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `DefaultTrackSelector.ParametersBuilder` | `buildUponParameters()` | Returns a new `DefaultTrackSelector.ParametersBuilder` initialized with the current selection parameters.
    `protected static int` | `getFormatLanguageScore​(Format format, String language, boolean allowUndeterminedFormatLanguage)` | Returns a score for how well a language specified in a `Format` matches a given language.
    `DefaultTrackSelector.Parameters` | `getParameters()` | Gets the current selection parameters.
    `protected static boolean` | `isSupported​(int formatSupport, boolean allowExceedsCapabilities)` | Returns true if the `C.FormatSupport` in the given `RendererCapabilities.Capabilities` is `C.FORMAT_HANDLED` or if `allowExceedsCapabilities` is set and the format support is `C.FORMAT_EXCEEDS_CAPABILITIES`.
    `protected static String` | `normalizeUndeterminedLanguageToNull​(String language)` | Normalizes the input string to null if it does not define a language, or returns it otherwise.
    `protected @NullableType ExoTrackSelection.Definition[]` | `selectAllTracks​(MappingTrackSelector.MappedTrackInfo mappedTrackInfo, int[][][] rendererFormatSupports, int[] rendererMixedMimeTypeAdaptationSupports, DefaultTrackSelector.Parameters params)` | Called from `selectTracks(MappedTrackInfo, int[][][], int[], MediaPeriodId, Timeline)` to make a track selection for each renderer, prior to overrides and disabled flags being applied.
    `protected Pair<ExoTrackSelection.Definition,​DefaultTrackSelector.AudioTrackScore>` | `selectAudioTrack​(TrackGroupArray groups, int[][] formatSupport, int mixedMimeTypeAdaptationSupports, DefaultTrackSelector.Parameters params, boolean enableAdaptiveTrackSelection)` | Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for an audio renderer.
    `protected ExoTrackSelection.Definition` | `selectOtherTrack​(int trackType, TrackGroupArray groups, int[][] formatSupport, DefaultTrackSelector.Parameters params)` | Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for a renderer whose type is neither video, audio or text.
    `protected Pair<ExoTrackSelection.Definition,​DefaultTrackSelector.TextTrackScore>` | `selectTextTrack​(TrackGroupArray groups, int[][] formatSupport, DefaultTrackSelector.Parameters params, String selectedAudioLanguage)` | Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for a text renderer.
    `protected Pair<@NullableType RendererConfiguration[],​@NullableType ExoTrackSelection[]>` | `selectTracks​(MappingTrackSelector.MappedTrackInfo mappedTrackInfo, int[][][] rendererFormatSupports, int[] rendererMixedMimeTypeAdaptationSupports, MediaSource.MediaPeriodId mediaPeriodId, Timeline timeline)` | Given mapped track information, returns a track selection and configuration for each renderer.
    `protected ExoTrackSelection.Definition` | `selectVideoTrack​(TrackGroupArray groups, int[][] formatSupport, int mixedMimeTypeAdaptationSupports, DefaultTrackSelector.Parameters params, boolean enableAdaptiveTrackSelection)` | Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for a video renderer.
    `void` | `setParameters​(DefaultTrackSelector.Parameters parameters)` | Atomically sets the provided parameters for track selection.
    `void` | `setParameters​(DefaultTrackSelector.ParametersBuilder parametersBuilder)` | Atomically sets the provided parameters for track selection.

    - ### Methods inherited from class com.google.android.exoplayer2.trackselection.MappingTrackSelector

      `getCurrentMappedTrackInfo, onSelectionActivated, selectTracks`

    - ### Methods inherited from class com.google.android.exoplayer2.trackselection.TrackSelector

      `getBandwidthMeter, init, invalidate`

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

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

- - ### Constructor Detail

    - #### DefaultTrackSelector

          @Deprecated
          public DefaultTrackSelector()

      Deprecated.
      Use `DefaultTrackSelector(Context)` instead.

    - #### DefaultTrackSelector

          @Deprecated
          public DefaultTrackSelector​(ExoTrackSelection.Factory trackSelectionFactory)

      Deprecated.
      Use `DefaultTrackSelector(Context, ExoTrackSelection.Factory)`.

    - #### DefaultTrackSelector

          public DefaultTrackSelector​(Context context)

      Parameters:
        `context` - Any `Context`.

    - #### DefaultTrackSelector

          public DefaultTrackSelector​(Context context,
                                      ExoTrackSelection.Factory trackSelectionFactory)

      Parameters:
        `context` - Any `Context`.
        `trackSelectionFactory` - A factory for `ExoTrackSelection`s.

    - #### DefaultTrackSelector

          public DefaultTrackSelector​(DefaultTrackSelector.Parameters parameters,
                                      ExoTrackSelection.Factory trackSelectionFactory)

      Parameters:
        `parameters` - Initial `DefaultTrackSelector.Parameters`.
        `trackSelectionFactory` - A factory for `ExoTrackSelection`s.

  - ### Method Detail

    - #### setParameters

          public void setParameters​(DefaultTrackSelector.Parameters parameters)

      Atomically sets the provided parameters for track selection.
      Parameters:
        `parameters` - The parameters for track selection.

    - #### setParameters

          public void setParameters​(DefaultTrackSelector.ParametersBuilder parametersBuilder)

      Atomically sets the provided parameters for track selection.
      Parameters:
        `parametersBuilder` - A builder from which to obtain the parameters for track selection.

    - #### getParameters

          public DefaultTrackSelector.Parameters getParameters()

      Gets the current selection parameters.
      Returns:
        The current selection parameters.

    - #### buildUponParameters

          public DefaultTrackSelector.ParametersBuilder buildUponParameters()

      Returns a new `DefaultTrackSelector.ParametersBuilder` initialized with the current selection parameters.

    - #### selectTracks

          protected final Pair<@NullableType RendererConfiguration[],​@NullableType ExoTrackSelection[]> selectTracks​(MappingTrackSelector.MappedTrackInfo mappedTrackInfo,
                                                                                                                           @Capabilities
                                                                                                                           int[][][] rendererFormatSupports,
                                                                                                                           @AdaptiveSupport
                                                                                                                           int[] rendererMixedMimeTypeAdaptationSupports,
                                                                                                                           MediaSource.MediaPeriodId mediaPeriodId,
                                                                                                                           Timeline timeline)
                                                                                                                    throws ExoPlaybackException

      Description copied from class: `MappingTrackSelector`
      Given mapped track information, returns a track selection and configuration for each renderer.
      Specified by:
        `selectTracks` in class `MappingTrackSelector`
      Parameters:
        `mappedTrackInfo` - Mapped track information.
        `rendererFormatSupports` - The `RendererCapabilities.Capabilities` for ach mapped track, indexed by renderer, track group and track (in that order).
        `rendererMixedMimeTypeAdaptationSupports` - The `RendererCapabilities.AdaptiveSupport` for mixed MIME type adaptation for the renderer.
        `mediaPeriodId` - The `MediaSource.MediaPeriodId` of the period for which tracks are to be selected.
        `timeline` - The `Timeline` holding the period for which tracks are to be selected.
      Returns:
        A pair consisting of the track selections and configurations for each renderer. A null configuration indicates the renderer should be disabled, in which case the track selection will also be null. A track selection may also be null for a non-disabled renderer if `RendererCapabilities.getTrackType()` is `C.TRACK_TYPE_NONE`.
      Throws:
        `ExoPlaybackException` - If an error occurs while selecting the tracks.

    - #### selectAllTracks

          protected @NullableType ExoTrackSelection.Definition[] selectAllTracks​(MappingTrackSelector.MappedTrackInfo mappedTrackInfo,
                                                                                 @Capabilities
                                                                                 int[][][] rendererFormatSupports,
                                                                                 @AdaptiveSupport
                                                                                 int[] rendererMixedMimeTypeAdaptationSupports,
                                                                                 DefaultTrackSelector.Parameters params)
                                                                          throws ExoPlaybackException

      Called from `selectTracks(MappedTrackInfo, int[][][], int[], MediaPeriodId, Timeline)` to make a track selection for each renderer, prior to overrides and disabled flags being applied.

      The implementation should not account for overrides and disabled flags. Track selections generated by this method will be overridden to account for these properties.

      Parameters:
        `mappedTrackInfo` - Mapped track information.
        `rendererFormatSupports` - The `RendererCapabilities.Capabilities` for each mapped track, indexed by renderer, track group and track (in that order).
        `rendererMixedMimeTypeAdaptationSupports` - The `RendererCapabilities.AdaptiveSupport` for mixed MIME type adaptation for the renderer.
      Returns:
        The `ExoTrackSelection.Definition`s for the renderers. A null entry indicates no selection was made.
      Throws:
        `ExoPlaybackException` - If an error occurs while selecting the tracks.

    - #### selectVideoTrack

          @Nullable
          protected ExoTrackSelection.Definition selectVideoTrack​(TrackGroupArray groups,
                                                                  @Capabilities
                                                                  int[][] formatSupport,
                                                                  @AdaptiveSupport
                                                                  int mixedMimeTypeAdaptationSupports,
                                                                  DefaultTrackSelector.Parameters params,
                                                                  boolean enableAdaptiveTrackSelection)
                                                           throws ExoPlaybackException

      Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for a video renderer.
      Parameters:
        `groups` - The `TrackGroupArray` mapped to the renderer.
        `formatSupport` - The `RendererCapabilities.Capabilities` for each mapped track, indexed by track group and track (in that order).
        `mixedMimeTypeAdaptationSupports` - The `RendererCapabilities.AdaptiveSupport` for mixed MIME type adaptation for the renderer.
        `params` - The selector's current constraint parameters.
        `enableAdaptiveTrackSelection` - Whether adaptive track selection is allowed.
      Returns:
        The `ExoTrackSelection.Definition` for the renderer, or null if no selection was made.
      Throws:
        `ExoPlaybackException` - If an error occurs while selecting the tracks.

    - #### selectAudioTrack

          @Nullable
          protected Pair<ExoTrackSelection.Definition,​DefaultTrackSelector.AudioTrackScore> selectAudioTrack​(TrackGroupArray groups,
                                                                                                                   @Capabilities
                                                                                                                   int[][] formatSupport,
                                                                                                                   @AdaptiveSupport
                                                                                                                   int mixedMimeTypeAdaptationSupports,
                                                                                                                   DefaultTrackSelector.Parameters params,
                                                                                                                   boolean enableAdaptiveTrackSelection)
                                                                                                            throws ExoPlaybackException

      Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for an audio renderer.
      Parameters:
        `groups` - The `TrackGroupArray` mapped to the renderer.
        `formatSupport` - The `RendererCapabilities.Capabilities` for each mapped track, indexed by track group and track (in that order).
        `mixedMimeTypeAdaptationSupports` - The `RendererCapabilities.AdaptiveSupport` for mixed MIME type adaptation for the renderer.
        `params` - The selector's current constraint parameters.
        `enableAdaptiveTrackSelection` - Whether adaptive track selection is allowed.
      Returns:
        The `ExoTrackSelection.Definition` and corresponding `DefaultTrackSelector.AudioTrackScore`, or null if no selection was made.
      Throws:
        `ExoPlaybackException` - If an error occurs while selecting the tracks.

    - #### selectTextTrack

          @Nullable
          protected Pair<ExoTrackSelection.Definition,​DefaultTrackSelector.TextTrackScore> selectTextTrack​(TrackGroupArray groups,
                                                                                                                 @Capabilities
                                                                                                                 int[][] formatSupport,
                                                                                                                 DefaultTrackSelector.Parameters params,
                                                                                                                 @Nullable
                                                                                                                 String selectedAudioLanguage)
                                                                                                          throws ExoPlaybackException

      Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for a text renderer.
      Parameters:
        `groups` - The `TrackGroupArray` mapped to the renderer.
        `formatSupport` - The `RendererCapabilities.Capabilities` for each mapped track, indexed by track group and track (in that order).
        `params` - The selector's current constraint parameters.
        `selectedAudioLanguage` - The language of the selected audio track. May be null if the selected text track declares no language or no text track was selected.
      Returns:
        The `ExoTrackSelection.Definition` and corresponding `DefaultTrackSelector.TextTrackScore`, or null if no selection was made.
      Throws:
        `ExoPlaybackException` - If an error occurs while selecting the tracks.

    - #### selectOtherTrack

          @Nullable
          protected ExoTrackSelection.Definition selectOtherTrack​(int trackType,
                                                                  TrackGroupArray groups,
                                                                  @Capabilities
                                                                  int[][] formatSupport,
                                                                  DefaultTrackSelector.Parameters params)
                                                           throws ExoPlaybackException

      Called by `selectAllTracks(MappedTrackInfo, int[][][], int[], Parameters)` to create a `ExoTrackSelection` for a renderer whose type is neither video, audio or text.
      Parameters:
        `trackType` - The type of the renderer.
        `groups` - The `TrackGroupArray` mapped to the renderer.
        `formatSupport` - The `RendererCapabilities.Capabilities` for each mapped track, indexed by track group and track (in that order).
        `params` - The selector's current constraint parameters.
      Returns:
        The `ExoTrackSelection` for the renderer, or null if no selection was made.
      Throws:
        `ExoPlaybackException` - If an error occurs while selecting the tracks.

    - #### isSupported

          protected static boolean isSupported​(@Capabilities
                                               int formatSupport,
                                               boolean allowExceedsCapabilities)

      Returns true if the `C.FormatSupport` in the given `RendererCapabilities.Capabilities` is `C.FORMAT_HANDLED` or if `allowExceedsCapabilities` is set and the format support is `C.FORMAT_EXCEEDS_CAPABILITIES`.
      Parameters:
        `formatSupport` - `RendererCapabilities.Capabilities`.
        `allowExceedsCapabilities` - Whether to return true if `C.FormatSupport` is `C.FORMAT_EXCEEDS_CAPABILITIES`.
      Returns:
        True if `C.FormatSupport` is `C.FORMAT_HANDLED`, or if `allowExceedsCapabilities` is set and the format support is `C.FORMAT_EXCEEDS_CAPABILITIES`.

    - #### normalizeUndeterminedLanguageToNull

          @Nullable
          protected static String normalizeUndeterminedLanguageToNull​(@Nullable
                                                                      String language)

      Normalizes the input string to null if it does not define a language, or returns it otherwise.
      Parameters:
        `language` - The string.
      Returns:
        The string, optionally normalized to null if it does not define a language.

    - #### getFormatLanguageScore

          protected static int getFormatLanguageScore​(Format format,
                                                      @Nullable
                                                      String language,
                                                      boolean allowUndeterminedFormatLanguage)

      Returns a score for how well a language specified in a `Format` matches a given language.
      Parameters:
        `format` - The `Format`.
        `language` - The language, or null.
        `allowUndeterminedFormatLanguage` - Whether matches with an empty or undetermined format language tag are allowed.
      Returns:
        A score of 4 if the languages match fully, a score of 3 if the languages match partly, a score of 2 if the languages don't match but belong to the same main language, a score of 1 if the format language is undetermined and such a match is allowed, and a score of 0 if the languages don't match at all.