Address API review comments on custom track format comparator

Author: tonihei

RELEASENOTES.md

@@ -55,6 +55,10 @@
 *   Transformer:
     *   Fix an issue where `ExportResult.fileSizeBytes` may be over-reported.
 *   Track selection:
+    *   Expose `BaseTrackSelection.DEFAULT_FORMAT_COMPARATOR` and add
+        `AdaptiveTrackSelection.Factory.setTrackFormatComparator` to allow
+        custom format ordering and ABR selection priority beyond bitrate-only
+        ordering.
 *   Extractors:
     *   MP4: Add support for extracting ITU-T T.35 (`it35`) timed metadata
         tracks.

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

@@ -38,6 +38,7 @@
 import com.google.common.collect.Iterables;
 import com.google.common.collect.Multimap;
 import com.google.common.collect.MultimapBuilder;
+import com.google.errorprone.annotations.CanIgnoreReturnValue;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Comparator;
@@ -237,19 +238,18 @@ public Factory(
      * Sets the comparator used to order formats in adaptive track selections. The comparator order
      * controls which formats are considered first during adaptation.
      *
+     * <p>The default is {@link BaseTrackSelection#DEFAULT_FORMAT_COMPARATOR}, which decides the
+     * priority based on the bitrate.
+     *
      * @param trackFormatComparator Comparator used to order selected formats.
      * @return This factory, for convenience.
      */
+    @CanIgnoreReturnValue
     public Factory setTrackFormatComparator(Comparator<Format> trackFormatComparator) {
       this.trackFormatComparator = checkNotNull(trackFormatComparator);
       return this;
     }
 
-    /** Returns the comparator used to order formats in adaptive track selections. */
-    protected final Comparator<Format> getTrackFormatComparator() {
-      return trackFormatComparator;
-    }
-
     @Override
     public final @NullableType ExoTrackSelection[] createTrackSelections(
         @NullableType Definition[] definitions,
@@ -311,7 +311,7 @@ protected AdaptiveTrackSelection createAdaptiveTrackSelection(
           bufferedFractionToLiveEdgeForQualityIncrease,
           adaptationCheckpoints,
           clock,
-          getTrackFormatComparator());
+          trackFormatComparator);
     }
   }
 

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

@@ -36,7 +36,8 @@
 @UnstableApi
 public abstract class BaseTrackSelection implements ExoTrackSelection {
 
-  static final Comparator<Format> DEFAULT_FORMAT_COMPARATOR =
+  /** The default {@link Format} comparator, which sorts formats by bitrate in descending order. */
+  public static final Comparator<Format> DEFAULT_FORMAT_COMPARATOR =
       (firstFormat, secondFormat) -> Integer.compare(secondFormat.bitrate, firstFormat.bitrate);
 
   /** The selected {@link TrackGroup}. */
@@ -87,7 +88,8 @@ public BaseTrackSelection(TrackGroup group, int[] tracks, @Type int type) {
    * @param tracks The indices of the selected tracks within the {@link TrackGroup}. Must not be
    *     null or empty. May be in any order.
    * @param type The type that will be returned from {@link TrackSelection#getType()}.
-   * @param formatComparator Comparator that determines the order of selected {@link Format}s.
+   * @param formatComparator Comparator that determines the order of selected {@linkplain Format
+   *     formats}.
    */
   protected BaseTrackSelection(
       TrackGroup group, int[] tracks, @Type int type, Comparator<Format> formatComparator) {

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

@@ -31,8 +31,8 @@
  * A track selection consisting of a static subset of selected tracks belonging to a {@link
  * TrackGroup}.
  *
- * <p>Tracks belonging to the subset are exposed in selection order, which by default is decreasing
- * bandwidth order.
+ * <p>Tracks belonging to the subset are exposed in selection order with the highest priority track
+ * first, for example in decreasing bandwidth order.
  */
 @UnstableApi
 public interface TrackSelection {

libraries/exoplayer/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.exoplayer.trackselection;
 
+import static com.google.common.base.Preconditions.checkState;
 import static com.google.common.truth.Truth.assertThat;
 import static org.mockito.Mockito.when;
 
@@ -588,7 +589,7 @@ public void updateSelectedTrack_withCustomFormatOrder_defersSwitchDownWhenBuffer
         /* playbackPositionUs= */ 0,
         /* bufferedDurationUs= */ 25_000_000,
         /* availableDurationUs= */ C.TIME_UNSET,
-        /* queue= */ Collections.emptyList(),
+        /* queue= */ ImmutableList.of(),
         createMediaChunkIterators(trackGroup, TEST_CHUNK_DURATION_US));
 
     // With sufficient buffer (bufferedDurationUs >= maxDurationForQualityDecreaseUs), the
@@ -1029,6 +1030,7 @@ private static Comparator<Format> formatComparatorInOrder(List<Format> orderedFo
 
   private static int getFormatOrderIndex(List<Format> orderedFormats, Format format) {
     int index = orderedFormats.indexOf(format);
-    return index == C.INDEX_UNSET ? Integer.MAX_VALUE : index;
+    checkState(index != C.INDEX_UNSET);
+    return index;
   }
 }