Update track selection documentation.

The Javadoc of DefaultTrackSelector can be shortened as it's not the
right place to document detailed options of the Player track selection
parameters.

The documentation page about track selection is updated to the new
APIs and extended with most relevant options and information needed
to work with ExoPlayer's track selection API.

#minor-release

PiperOrigin-RevId: 409088989

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/DefaultTrackSelector.java

@@ -28,7 +28,6 @@ import androidx.media3.common.Bundleable;
 import androidx.media3.common.C;
 import androidx.media3.common.C.FormatSupport;
 import androidx.media3.common.Format;
-import androidx.media3.common.Player;
 import androidx.media3.common.Timeline;
 import androidx.media3.common.TrackGroup;
 import androidx.media3.common.TrackGroupArray;
@@ -65,112 +64,36 @@ import java.util.concurrent.atomic.AtomicReference;
 import org.checkerframework.checker.nullness.compatqual.NullableType;
 
 /**
- * A default {@link TrackSelector} suitable for most use cases. Track selections are made according
+ * A default {@link TrackSelector} suitable for most use cases.
- * to configurable {@link Parameters}, which can be set by calling {@link
- * Player#setTrackSelectionParameters}.
  *
  * <h2>Modifying parameters</h2>
  *
- * To modify only some aspects of the parameters currently used by a selector, it's possible to
+ * Track selection parameters should be modified by obtaining a {@link
- * obtain a {@link ParametersBuilder} initialized with the current {@link Parameters}. The desired
+ * TrackSelectionParameters.Builder} initialized with the current {@link TrackSelectionParameters}
- * modifications can be made on the builder, and the resulting {@link Parameters} can then be built
+ * from the player. The desired modifications can be made on the builder, and the resulting {@link
- * and set on the selector. For example the following code modifies the parameters to restrict video
+ * TrackSelectionParameters} can then be built and set on the player:
- * track selections to SD, and to select a German audio track if there is one:
- *
- * <pre>{@code
- * // Build on the current parameters.
- * TrackSelectionParameters currentParameters = player.getTrackSelectionParameters();
- * // Build the resulting parameters.
- * TrackSelectionParameters newParameters = currentParameters
- *     .buildUpon()
- *     .setMaxVideoSizeSd()
- *     .setPreferredAudioLanguage("deu")
- *     .build();
- * // Set the new parameters.
- * player.setTrackSelectionParameters(newParameters);
- * }</pre>
- *
- * Convenience methods and chaining allow this to be written more concisely as:
  *
  * <pre>{@code
  * player.setTrackSelectionParameters(
  *     player.getTrackSelectionParameters()
  *         .buildUpon()
  *         .setMaxVideoSizeSd()
- *         .setPreferredAudioLanguage("deu")
+ *         .setPreferredAudioLanguage("de")
  *         .build());
+ *
  * }</pre>
  *
- * Selection {@link Parameters} support many different options, some of which are described below.
+ * Some specialized parameters are only available in the extended {@link Parameters} class, which
- *
+ * can be retrieved and modified in a similar way in this track selector:
- * <h2>Selecting specific tracks</h2>
- *
- * 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:
  *
  * <pre>{@code
- * MappedTrackInfo mappedTrackInfo = trackSelector.getCurrentMappedTrackInfo();
+ * defaultTrackSelector.setParameters(
- * TrackGroupArray rendererTrackGroups = mappedTrackInfo == null ? null
+ *     defaultTrackSelector.getParameters()
- *     : mappedTrackInfo.getTrackGroups(rendererIndex);
- * }</pre>
- *
- * If {@code rendererTrackGroups} is null then there aren't any currently mapped tracks, and so
- * setting an override isn't possible. Note that a {@link Player.Listener} registered on the player
- * can be used to determine when the current tracks (and therefore the mapping) changes. If {@code
- * 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 {@code groupIndex} and the {@code
- * trackIndices} within the group it that should be selected. The override can then be specified
- * using {@link ParametersBuilder#setSelectionOverride}:
- *
- * <pre>{@code
- * SelectionOverride selectionOverride = new SelectionOverride(groupIndex, trackIndices);
- * player.setTrackSelectionParameters(
- *     ((Parameters)player.getTrackSelectionParameters())
  *         .buildUpon()
- *         .setSelectionOverride(rendererIndex, rendererTrackGroups, selectionOverride)
+ *         .setTunnelingEnabled(true)
  *         .build());
+ *
  * }</pre>
- *
- * <h2>Constraint based track selection</h2>
- *
- * 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:
- *
- * <pre>{@code
- * player.setTrackSelectionParameters(
- *     player.getTrackSelectionParameters()
- *         .buildUpon()
- *         .setMaxVideoSizeSd()
- *         .setPreferredAudioLanguage("deu")
- *         .build());
- * }</pre>
- *
- * There are several benefits to using constraint based track selection instead of specific track
- * overrides:
- *
- * <ul>
- *   <li>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).
- *   <li>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.
- * </ul>
- *
- * <h2>Disabling renderers</h2>
- *
- * Renderers can be disabled using {@link ParametersBuilder#setRendererDisabled}. Disabling a
- * renderer differs from setting a {@code null} override because the renderer is disabled
- * unconditionally, whereas a {@code null} override is applied only when the track groups available
- * to the renderer match the {@link TrackGroupArray} for which it was specified.
- *
- * <h2>Tunneling</h2>
- *
- * Tunneled playback can be enabled in cases where the combination of renderers and selected tracks
- * supports it. This can be done by using {@link ParametersBuilder#setTunnelingEnabled(boolean)}.
  */
 @UnstableApi
 public class DefaultTrackSelector extends MappingTrackSelector {