From 7eb01e212585204e4e64f1d666a250cab05f28cf Mon Sep 17 00:00:00 2001 From: olly Date: Thu, 17 Mar 2022 13:08:56 +0000 Subject: [PATCH] Move TrackGroupArray back to ExoPlayer PiperOrigin-RevId: 435325454 --- .../google/android/exoplayer2/TracksInfo.java | 26 ++++++++--------- .../android/exoplayer2/source/TrackGroup.java | 16 +++++++++- .../TrackSelectionOverride.java | 21 +++++++++----- .../TrackSelectionParameters.java | 29 +++++++++---------- .../android/exoplayer2/MetadataRetriever.java | 2 +- .../exoplayer2/source/TrackGroupArray.java | 11 ++++++- .../trackselection/DefaultTrackSelector.java | 4 +-- .../source/TrackGroupArrayTest.java | 0 8 files changed, 67 insertions(+), 42 deletions(-) rename library/{common => core}/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java (88%) rename library/{common => core}/src/test/java/com/google/android/exoplayer2/source/TrackGroupArrayTest.java (100%) diff --git a/library/common/src/main/java/com/google/android/exoplayer2/TracksInfo.java b/library/common/src/main/java/com/google/android/exoplayer2/TracksInfo.java index 7cf02eb995..5186849234 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/TracksInfo.java +++ b/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 trackGroupInfos; - /** An {@code TrackInfo} that contains no tracks. */ public static final TracksInfo EMPTY = new TracksInfo(ImmutableList.of()); + private final ImmutableList trackGroupInfos; + /** * Constructs an instance. * diff --git a/library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroup.java b/library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroup.java index 1e75c6f443..418b195e96 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroup.java +++ b/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. + * + *

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. + * + *

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"; diff --git a/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java b/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java index 572dbeea83..c8f8a9e171 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionOverride.java +++ b/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. * - *

If multiple tracks in {@link #trackGroup} are overridden, as many as possible will be selected - * depending on the player capabilities. + *

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. * - *

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. + *

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 { diff --git a/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionParameters.java b/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionParameters.java index 91e80e79f3..d650ee8930 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelectionParameters.java +++ b/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. * - *

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: + *

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: * * 

{@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 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;
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/MetadataRetriever.java b/library/core/src/main/java/com/google/android/exoplayer2/MetadataRetriever.java
index e580fc4ff8..90ba6ef720 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/MetadataRetriever.java
+++ b/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();
diff --git a/library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java b/library/core/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java
similarity index 88%
rename from library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java
rename to library/core/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java
index c00a45e29f..12c79f5da9 100644
--- a/library/common/src/main/java/com/google/android/exoplayer2/source/TrackGroupArray.java
+++ b/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.
+ *
+ * 
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";
diff --git a/library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java b/library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java
index 5f0edeedbf..5896ba579a 100644
--- a/library/core/src/main/java/com/google/android/exoplayer2/trackselection/DefaultTrackSelector.java
+++ b/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());
- *
  * }
* * 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: * * 
{@code
  * defaultTrackSelector.setParameters(
@@ -94,7 +93,6 @@ import org.checkerframework.checker.nullness.compatqual.NullableType;
  *         .buildUpon()
  *         .setTunnelingEnabled(true)
  *         .build());
- *
  * }
*/ public class DefaultTrackSelector extends MappingTrackSelector { diff --git a/library/common/src/test/java/com/google/android/exoplayer2/source/TrackGroupArrayTest.java b/library/core/src/test/java/com/google/android/exoplayer2/source/TrackGroupArrayTest.java similarity index 100% rename from library/common/src/test/java/com/google/android/exoplayer2/source/TrackGroupArrayTest.java rename to library/core/src/test/java/com/google/android/exoplayer2/source/TrackGroupArrayTest.java