Move TrackGroupArray back to ExoPlayer

PiperOrigin-RevId: 435325454

library/common/src/main/java/com/google/android/exoplayer2/TracksInfo.java

@@ -41,8 +41,8 @@ public final class TracksInfo implements Bundleable {
 
   /**
    * Information about a single group of tracks, including the underlying {@link TrackGroup}, the
-   * {@link C.TrackType type} of tracks it contains, and the level to which each track is supported
-   * by the player.
+   * level to which each track is supported by the player, and whether any of the tracks are
+   * selected.
    */
   public static final class TrackGroupInfo implements Bundleable {
 
@@ -55,25 +55,25 @@ public final class TracksInfo implements Bundleable {
     private final boolean[] trackSelected;
 
     /**
-     * Constructs a TrackGroupInfo.
+     * Constructs an instance.
      *
-     * @param trackGroup The {@link TrackGroup} described.
-     * @param adaptiveSupported Whether adaptive selections containing more than one track in the
-     *     {@code trackGroup} are supported.
-     * @param trackSupport The {@link C.FormatSupport} of each track in the {@code trackGroup}.
-     * @param tracksSelected Whether each track in the {@code trackGroup} is selected.
+     * @param trackGroup The underlying {@link TrackGroup}.
+     * @param adaptiveSupported Whether the player supports adaptive selections containing more than
+     *     one track in the group.
+     * @param trackSupport The {@link C.FormatSupport} of each track in the group.
+     * @param trackSelected Whether each track in the {@code trackGroup} is selected.
      */
     public TrackGroupInfo(
         TrackGroup trackGroup,
         boolean adaptiveSupported,
         @C.FormatSupport int[] trackSupport,
-        boolean[] tracksSelected) {
+        boolean[] trackSelected) {
       length = trackGroup.length;
-      checkArgument(length == trackSupport.length && length == tracksSelected.length);
+      checkArgument(length == trackSupport.length && length == trackSelected.length);
       this.trackGroup = trackGroup;
       this.adaptiveSupported = adaptiveSupported && length > 1;
       this.trackSupport = trackSupport.clone();
-      this.trackSelected = tracksSelected.clone();
+      this.trackSelected = trackSelected.clone();
     }
 
     /** Returns the underlying {@link TrackGroup}. */
@@ -263,11 +263,11 @@ public final class TracksInfo implements Bundleable {
     }
   }
 
-  private final ImmutableList<TrackGroupInfo> trackGroupInfos;
-
   /** An {@code TrackInfo} that contains no tracks. */
   public static final TracksInfo EMPTY = new TracksInfo(ImmutableList.of());
 
+  private final ImmutableList<TrackGroupInfo> trackGroupInfos;
+
   /**
    * Constructs an instance.
    *

library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroup.java

@@ -37,7 +37,21 @@ import java.lang.annotation.Target;
 import java.util.Arrays;
 import java.util.List;
 
-/** Defines an immutable group of tracks identified by their format identity. */
+/**
+ * An immutable group of tracks. All tracks in a group present the same content, but their formats
+ * may differ.
+ *
+ * <p>As an example of how tracks can be grouped, consider an adaptive playback where a main video
+ * feed is provided in five resolutions, and an alternative video feed (e.g., a different camera
+ * angle in a sports match) is provided in two resolutions. In this case there will be two video
+ * track groups, one corresponding to the main video feed containing five tracks, and a second for
+ * the alternative video feed containing two tracks.
+ *
+ * <p>Note that audio tracks whose languages differ are not grouped, because content in different
+ * languages is not considered to be the same. Conversely, audio tracks in the same language that
+ * only differ in properties such as bitrate, sampling rate, channel count and so on can be grouped.
+ * This also applies to text tracks.
+ */
 public final class TrackGroup implements Bundleable {
 
   private static final String TAG = "TrackGroup";

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

@@ -33,16 +33,21 @@ import java.lang.annotation.RetentionPolicy;
 import java.util.List;
 
 /**
- * Forces the selection of {@link #trackIndices} for a {@link TrackGroup}.
+ * A track selection override, consisting of a {@link TrackGroup} and the indices of the tracks
+ * within the group that should be selected.
  *
- * <p>If multiple tracks in {@link #trackGroup} are overridden, as many as possible will be selected
- * depending on the player capabilities.
+ * <p>A track selection override is applied during playback if the media being played contains a
+ * {@link TrackGroup} equal to the one in the override. If a {@link TrackSelectionParameters}
+ * contains only one override of a given track type that applies to the media, this override will be
+ * used to control the track selection for that type. If multiple overrides of a given track type
+ * apply then the player will apply only one of them.
  *
- * <p>If {@link #trackIndices} is empty, no tracks from {@link #trackGroup} will be played. This is
- * similar to {@link TrackSelectionParameters#disabledTrackTypes}, except it will only affect the
- * playback of the associated {@link TrackGroup}. For example, if the only {@link
- * C#TRACK_TYPE_VIDEO} {@link TrackGroup} is associated with no tracks, no video will play until the
- * next video starts.
+ * <p>If {@link #trackIndices} is empty then the override specifies that no tracks should be
+ * selected. Adding an empty override to a {@link TrackSelectionParameters} is similar to {@link
+ * TrackSelectionParameters.Builder#setTrackTypeDisabled disabling a track type}, except that an
+ * empty override will only be applied if the media being played contains a {@link TrackGroup} equal
+ * to the one in the override. Conversely, disabling a track type will prevent selection of tracks
+ * of that type for all media.
  */
 public final class TrackSelectionOverride implements Bundleable {
 

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

@@ -49,10 +49,11 @@ import org.checkerframework.checker.initialization.qual.UnknownInitialization;
 import org.checkerframework.checker.nullness.qual.EnsuresNonNull;
 
 /**
- * Constraint parameters for track selection.
+ * Parameters for controlling track selection.
  *
- * <p>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:
+ * <p>Parameters can be queried and set on a {@link Player}. 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:
  *
  * <pre>{@code
  * // Build on the current parameters.
@@ -654,28 +655,26 @@ public class TrackSelectionParameters implements Bundleable {
       return this;
     }
 
-    /** Adds an override for the provided {@link TrackGroup}. */
+    /** Adds an override, replacing any override for the same {@link TrackGroup}. */
     public Builder addOverride(TrackSelectionOverride override) {
       overrides.put(override.trackGroup, override);
       return this;
     }
 
-    /** Removes the override associated with the provided {@link TrackGroup} if present. */
-    public Builder clearOverride(TrackGroup trackGroup) {
-      overrides.remove(trackGroup);
-      return this;
-    }
-
-    /** Set the override for the type of the provided {@link TrackGroup}. */
+    /** Sets an override, replacing all existing overrides with the same track type. */
     public Builder setOverrideForType(TrackSelectionOverride override) {
       clearOverridesOfType(override.getTrackType());
       overrides.put(override.trackGroup, override);
       return this;
     }
 
-    /**
-     * Remove any override associated with {@link TrackGroup TrackGroups} of type {@code trackType}.
-     */
+    /** Removes the override for the provided {@link TrackGroup}, if there is one. */
+    public Builder clearOverride(TrackGroup trackGroup) {
+      overrides.remove(trackGroup);
+      return this;
+    }
+
+    /** Removes all overrides of the provided track type. */
     public Builder clearOverridesOfType(@C.TrackType int trackType) {
       Iterator<TrackSelectionOverride> it = overrides.values().iterator();
       while (it.hasNext()) {
@@ -687,7 +686,7 @@ public class TrackSelectionParameters implements Bundleable {
       return this;
     }
 
-    /** Removes all track overrides. */
+    /** Removes all overrides. */
     public Builder clearOverrides() {
       overrides.clear();
       return this;

library/core/src/main/java/com/google/android/exoplayer2/MetadataRetriever.java

@@ -152,7 +152,7 @@ public final class MetadataRetriever {
                 mediaPeriod.maybeThrowPrepareError();
               }
               mediaSourceHandler.sendEmptyMessageDelayed(
-                  MESSAGE_CHECK_FOR_FAILURE, /* delayMillis= */ ERROR_POLL_INTERVAL_MS);
+                  MESSAGE_CHECK_FOR_FAILURE, /* delayMs= */ ERROR_POLL_INTERVAL_MS);
             } catch (Exception e) {
               trackGroupsFuture.setException(e);
               mediaSourceHandler.obtainMessage(MESSAGE_RELEASE).sendToTarget();

library/core/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java

@@ -31,7 +31,16 @@ import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 import java.util.List;
 
-/** An immutable array of {@link TrackGroup}s. */
+/**
+ * An immutable array of {@link TrackGroup}s.
+ *
+ * <p>This class is typically used to represent all of the tracks available in a piece of media.
+ * Tracks that are known to present the same content are grouped together (e.g., the same video feed
+ * provided at different resolutions in an adaptive stream). Tracks that are known to present
+ * different content are in separate track groups (e.g., an audio track will not be in the same
+ * group as a video track, and an audio track in one language will be in a different group to an
+ * audio track in another language).
+ */
 public final class TrackGroupArray implements Bundleable {
 
   private static final String TAG = "TrackGroupArray";

library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java

@@ -82,11 +82,10 @@ import org.checkerframework.checker.nullness.compatqual.NullableType;
  *         .setMaxVideoSizeSd()
  *         .setPreferredAudioLanguage("de")
  *         .build());
- *
  * }</pre>
  *
  * 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:
+ * can be retrieved and modified in a similar way by calling methods directly on this class:
  *
  * <pre>{@code
  * defaultTrackSelector.setParameters(
@@ -94,7 +93,6 @@ import org.checkerframework.checker.nullness.compatqual.NullableType;
  *         .buildUpon()
  *         .setTunnelingEnabled(true)
  *         .build());
- *
  * }</pre>
  */
 public class DefaultTrackSelector extends MappingTrackSelector {