TrackSelectionOverride: Remove select-all-tracks constructor

This constructor always does the wrong thing for non-adaptive groups
containing more than 1 track, because it'll incorrectly generate an
adaptive selection. Replace it with a constructor for specifying a
single track within the group instead.

PiperOrigin-RevId: 431673458

docs/track-selection.md

@@ -113,25 +113,27 @@ specifying specific tracks directly:
 
 ### Selecting specific tracks
 
-It's possible to specify specific tracks in `TrackSelectionParameters` that
-should be selected for the current set of tracks. Note that a change in the
-available tracks, for example when changing items in a playlist, will also
-invalidate such a track override.
-
-The simplest way to specify track overrides is to specify the `TrackGroup` that
-should be selected for its track type. For example, you can specify an audio
-track group to select this audio group and prevent any other audio track groups
-from being selected:
+It's possible to specify in `TrackSelectionParameters` which of the currently
+available tracks should be selected. First, the player's currently available
+tracks should be queried using `Player.getTracksInfo`. Second, having identified
+which tracks to select, they can be set on `TrackSelectionParameters` using
+`TrackSelectionOverrides`. For example, to select the first track from a
+specific `audioTrackGroup`:
 
 ~~~
 player.setTrackSelectionParameters(
     player.getTrackSelectionParameters()
         .buildUpon()
-        .setOverrideForType(new TrackSelectionOverride(audioTrackGroup))
+        .setOverrideForType(
+            new TrackSelectionOverride(audioTrackGroup, /* trackIndex= */ 0))
         .build());
 ~~~
 {: .language-java}
 
+Note that a `TrackSelectionOverride` will only apply to media items that contain
+the `TrackGroup` specified in the override. Hence an override may not apply to
+a subsequent media item if that item contains different tracks.
+
 ### Disabling track types or groups
 
 Track types, like video, audio or text, can be disabled completely using

library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java

@@ -62,14 +62,14 @@ public final class TrackSelectionOverride implements Bundleable {
   private static final int FIELD_TRACK_GROUP = 0;
   private static final int FIELD_TRACKS = 1;
 
-  /** Constructs an instance to force all tracks in {@code trackGroup} to be selected. */
-  public TrackSelectionOverride(TrackGroup trackGroup) {
-    this.trackGroup = trackGroup;
-    ImmutableList.Builder<Integer> builder = new ImmutableList.Builder<>();
-    for (int i = 0; i < trackGroup.length; i++) {
-      builder.add(i);
-    }
-    this.trackIndices = builder.build();
+  /**
+   * Constructs an instance to force {@code trackIndex} in {@code trackGroup} to be selected.
+   *
+   * @param trackGroup The {@link TrackGroup} for which to override the track selection.
+   * @param trackIndex The index of the track in the {@link TrackGroup} to select.
+   */
+  public TrackSelectionOverride(TrackGroup trackGroup, int trackIndex) {
+    this(trackGroup, ImmutableList.of(trackIndex));
   }
 
   /**
@@ -123,13 +123,9 @@ public final class TrackSelectionOverride implements Bundleable {
   /** Object that can restore {@code TrackSelectionOverride} from a {@link Bundle}. */
   public static final Creator<TrackSelectionOverride> CREATOR =
       bundle -> {
-        @Nullable Bundle trackGroupBundle = bundle.getBundle(keyForField(FIELD_TRACK_GROUP));
-        checkNotNull(trackGroupBundle); // Mandatory as there are no reasonable defaults.
+        Bundle trackGroupBundle = checkNotNull(bundle.getBundle(keyForField(FIELD_TRACK_GROUP)));
         TrackGroup trackGroup = TrackGroup.CREATOR.fromBundle(trackGroupBundle);
-        @Nullable int[] tracks = bundle.getIntArray(keyForField(FIELD_TRACKS));
-        if (tracks == null) {
-          return new TrackSelectionOverride(trackGroup);
-        }
+        int[] tracks = checkNotNull(bundle.getIntArray(keyForField(FIELD_TRACKS)));
         return new TrackSelectionOverride(trackGroup, Ints.asList(tracks));
       };
 

library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverrideTest.java

@@ -31,12 +31,12 @@ import org.junit.runner.RunWith;
 public final class TrackSelectionOverrideTest {
 
   @Test
-  public void newTrackSelectionOverride_withJustTrackGroup_selectsAllTracks() {
+  public void newTrackSelectionOverride_withOneTrack_selectsOneTrack() {
     TrackSelectionOverride trackSelectionOverride =
-        new TrackSelectionOverride(newTrackGroupWithIds(1, 2));
+        new TrackSelectionOverride(newTrackGroupWithIds(1, 2), /* trackIndex= */ 1);
 
     assertThat(trackSelectionOverride.trackGroup).isEqualTo(newTrackGroupWithIds(1, 2));
-    assertThat(trackSelectionOverride.trackIndices).containsExactly(0, 1).inOrder();
+    assertThat(trackSelectionOverride.trackIndices).containsExactly(1).inOrder();
   }
 
   @Test

library/common/src/test/java/com/google/android/exoplayer2/trackselection/TrackSelectionParametersTest.java

@@ -71,7 +71,8 @@ public final class TrackSelectionParametersTest {
   @Test
   public void parametersSet_fromDefault_isAsExpected() {
     TrackSelectionOverride override1 =
-        new TrackSelectionOverride(new TrackGroup(new Format.Builder().build()));
+        new TrackSelectionOverride(
+            new TrackGroup(new Format.Builder().build()), /* trackIndex= */ 0);
     TrackSelectionOverride override2 =
         new TrackSelectionOverride(
             new TrackGroup(
@@ -105,7 +106,9 @@ public final class TrackSelectionParametersTest {
             // General
             .setForceLowestBitrate(false)
             .setForceHighestSupportedBitrate(true)
-            .addOverride(new TrackSelectionOverride(new TrackGroup(new Format.Builder().build())))
+            .addOverride(
+                new TrackSelectionOverride(
+                    new TrackGroup(new Format.Builder().build()), /* trackIndex= */ 0))
             .addOverride(
                 new TrackSelectionOverride(
                     new TrackGroup(
@@ -206,8 +209,10 @@ public final class TrackSelectionParametersTest {
 
   @Test
   public void addOverride_onDifferentGroups_addsOverride() {
-    TrackSelectionOverride override1 = new TrackSelectionOverride(newTrackGroupWithIds(1));
-    TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(2));
+    TrackSelectionOverride override1 =
+        new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0);
+    TrackSelectionOverride override2 =
+        new TrackSelectionOverride(newTrackGroupWithIds(2), /* trackIndex= */ 0);
 
     TrackSelectionParameters trackSelectionParameters =
         new TrackSelectionParameters.Builder(getApplicationContext())
@@ -238,8 +243,10 @@ public final class TrackSelectionParametersTest {
 
   @Test
   public void setOverrideForType_onSameType_replacesOverride() {
-    TrackSelectionOverride override1 = new TrackSelectionOverride(newTrackGroupWithIds(1));
-    TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(2));
+    TrackSelectionOverride override1 =
+        new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0);
+    TrackSelectionOverride override2 =
+        new TrackSelectionOverride(newTrackGroupWithIds(2), /* trackIndex= */ 0);
 
     TrackSelectionParameters trackSelectionParameters =
         new TrackSelectionParameters.Builder(getApplicationContext())
@@ -252,8 +259,10 @@ public final class TrackSelectionParametersTest {
 
   @Test
   public void clearOverridesOfType_ofTypeAudio_removesAudioOverride() {
-    TrackSelectionOverride override1 = new TrackSelectionOverride(AAC_TRACK_GROUP);
-    TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(1));
+    TrackSelectionOverride override1 =
+        new TrackSelectionOverride(AAC_TRACK_GROUP, /* trackIndex= */ 0);
+    TrackSelectionOverride override2 =
+        new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0);
     TrackSelectionParameters trackSelectionParameters =
         new TrackSelectionParameters.Builder(getApplicationContext())
             .addOverride(override1)
@@ -266,8 +275,10 @@ public final class TrackSelectionParametersTest {
 
   @Test
   public void clearOverride_ofTypeGroup_removesOverride() {
-    TrackSelectionOverride override1 = new TrackSelectionOverride(AAC_TRACK_GROUP);
-    TrackSelectionOverride override2 = new TrackSelectionOverride(newTrackGroupWithIds(1));
+    TrackSelectionOverride override1 =
+        new TrackSelectionOverride(AAC_TRACK_GROUP, /* trackIndex= */ 0);
+    TrackSelectionOverride override2 =
+        new TrackSelectionOverride(newTrackGroupWithIds(1), /* trackIndex= */ 0);
     TrackSelectionParameters trackSelectionParameters =
         new TrackSelectionParameters.Builder(getApplicationContext())
             .addOverride(override1)

library/core/src/test/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelectorTest.java

@@ -300,7 +300,7 @@ public final class DefaultTrackSelectorTest {
     trackSelector.setParameters(
         trackSelector
             .buildUponParameters()
-            .setOverrideForType(new TrackSelectionOverride(videoGroupH264))
+            .setOverrideForType(new TrackSelectionOverride(videoGroupH264, /* trackIndex= */ 0))
             .build());
     TrackSelectorResult result =
         trackSelector.selectTracks(
@@ -317,7 +317,7 @@ public final class DefaultTrackSelectorTest {
     trackSelector.setParameters(
         trackSelector
             .buildUponParameters()
-            .setOverrideForType(new TrackSelectionOverride(videoGroupAv1))
+            .setOverrideForType(new TrackSelectionOverride(videoGroupAv1, /* trackIndex= */ 0))
             .build());
     result =
         trackSelector.selectTracks(
@@ -348,7 +348,8 @@ public final class DefaultTrackSelectorTest {
     trackSelector.setParameters(
         trackSelector
             .buildUponParameters()
-            .setOverrideForType(new TrackSelectionOverride(audioGroupUnsupported))
+            .setOverrideForType(
+                new TrackSelectionOverride(audioGroupUnsupported, /* trackIndex= */ 0))
             .build());
     TrackSelectorResult result =
         trackSelector.selectTracks(