Add field measured throughput (mtp)

Updated `ExoTrackSelection` to provide the most recent bitrate estimate, enabling the inclusion of measured throughput (mtp) as a CMCD-Request field in Common Media Client Data (CMCD) logging. Additionally, made changes to the `checkArgument` methods in `CmcdLog` to prevent the use of default values in certain cases. #minor-release PiperOrigin-RevId: 549369529
SimonHung · Jul 20, 2023 · cdb174c · cdb174c
1 parent 177187e
commit cdb174c
Show file tree

Hide file tree

Showing 14 changed files with 114 additions and 31 deletions.
diff --git a/RELEASENOTES.md b/RELEASENOTES.md
@@ -35,10 +35,9 @@
     *   Allow `MediaItem` updates for all `MediaSource` classes provided by the
         library via `Player.replaceMediaItem(s)`
         (([#33](https://github.com/androidx/media/issues/33)),([#9978](https://github.com/google/ExoPlayer/issues/9978))).
-    *   Add fields streaming format (sf), stream type (st) and version (v) to
-        Common Media Client Data (CMCD) logging.
-    *   Add fields top birate (tb) and object duration (d) to Common Media
-        Client Data (CMCD) logging.
+    *   Add additional fields to Common Media Client Data (CMCD) logging:
+        streaming format (sf), stream type (st), version (v), top birate (tb),
+        object duration (d) and measured throughput (mtp).
 *   Transformer:
     *   Parse EXIF rotation data for image inputs.
     *   Remove `TransformationRequest.HdrMode` annotation type and its

diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MergingMediaPeriod.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MergingMediaPeriod.java
@@ -604,6 +604,11 @@ public boolean isTrackExcluded(int index, long nowMs) {
       return trackSelection.isTrackExcluded(index, nowMs);
     }
 
+    @Override
+    public long getLatestBitrateEstimate() {
+      return trackSelection.getLatestBitrateEstimate();
+    }
+
     @Override
     public boolean equals(@Nullable Object o) {
       if (this == o) {

diff --git a/...player/src/main/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelection.java b/...player/src/main/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelection.java
@@ -319,6 +319,7 @@ protected AdaptiveTrackSelection createAdaptiveTrackSelection(
   private @C.SelectionReason int reason;
   private long lastBufferEvaluationMs;
   @Nullable private MediaChunk lastBufferEvaluationMediaChunk;
+  private long latestBitrateEstimate;
 
   /**
    * @param group The {@link TrackGroup}.
@@ -410,6 +411,7 @@ protected AdaptiveTrackSelection(
     playbackSpeed = 1f;
     reason = C.SELECTION_REASON_UNKNOWN;
     lastBufferEvaluationMs = C.TIME_UNSET;
+    latestBitrateEstimate = Long.MIN_VALUE;
   }
 
   @CallSuper
@@ -543,6 +545,11 @@ public int evaluateQueueSize(long playbackPositionUs, List<? extends MediaChunk>
     return queueSize;
   }
 
+  @Override
+  public long getLatestBitrateEstimate() {
+    return latestBitrateEstimate;
+  }
+
   /**
    * Called when updating the selected track to determine whether a candidate track can be selected.
    *
@@ -681,8 +688,8 @@ private long getAllocatedBandwidth(long chunkDurationUs) {
   }
 
   private long getTotalAllocatableBandwidth(long chunkDurationUs) {
-    long cautiousBandwidthEstimate =
-        (long) (bandwidthMeter.getBitrateEstimate() * bandwidthFraction);
+    latestBitrateEstimate = bandwidthMeter.getBitrateEstimate();
+    long cautiousBandwidthEstimate = (long) (latestBitrateEstimate * bandwidthFraction);
     long timeToFirstByteEstimateUs = bandwidthMeter.getTimeToFirstByteEstimateUs();
     if (timeToFirstByteEstimateUs == C.TIME_UNSET || chunkDurationUs == C.TIME_UNSET) {
       return (long) (cautiousBandwidthEstimate / playbackSpeed);

diff --git a/...s/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/ExoTrackSelection.java b/...s/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/ExoTrackSelection.java
@@ -292,4 +292,14 @@ default boolean shouldCancelChunkLoad(
    *     android.os.SystemClock#elapsedRealtime()}.
    */
   boolean isTrackExcluded(int index, long nowMs);
+
+  /**
+   * Returns the most recent bitrate estimate utilised for track selection.
+   *
+   * <p>The default behavior is to return {@link Long#MIN_VALUE}, indicating that the bitrate
+   * estimate was not computed for the track selection decision.
+   */
+  default long getLatestBitrateEstimate() {
+    return Long.MIN_VALUE;
+  }
 }
diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/upstream/CmcdConfiguration.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/upstream/CmcdConfiguration.java
@@ -65,7 +65,8 @@ public final class CmcdConfiguration {
     KEY_STREAM_TYPE,
     KEY_VERSION,
     KEY_TOP_BITRATE,
-    KEY_OBJECT_DURATION
+    KEY_OBJECT_DURATION,
+    KEY_MEASURED_THROUGHPUT
   })
   @Documented
   @Target(TYPE_USE)
@@ -88,6 +89,7 @@ public final class CmcdConfiguration {
   public static final String KEY_VERSION = "v";
   public static final String KEY_TOP_BITRATE = "tb";
   public static final String KEY_OBJECT_DURATION = "d";
+  public static final String KEY_MEASURED_THROUGHPUT = "mtp";
 
   /**
    * Factory for {@link CmcdConfiguration} instances.
@@ -281,4 +283,12 @@ public boolean isTopBitrateLoggingAllowed() {
   public boolean isObjectDurationLoggingAllowed() {
     return requestConfig.isKeyAllowed(KEY_OBJECT_DURATION);
   }
+
+  /**
+   * Returns whether logging object duration is allowed based on the {@linkplain RequestConfig
+   * request configuration}.
+   */
+  public boolean isMeasuredThroughputLoggingAllowed() {
+    return requestConfig.isKeyAllowed(KEY_MEASURED_THROUGHPUT);
+  }
 }
diff --git a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/upstream/CmcdLog.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/upstream/CmcdLog.java
@@ -81,7 +81,8 @@ public final class CmcdLog {
    * @param trackSelection The {@linkplain ExoTrackSelection track selection}.
    * @param bufferedDurationUs The duration of media currently buffered from the current playback
    *     position, in microseconds.
-   * @param chunkDurationUs The duration of current media chunk being requested, in microseconds.
+   * @param chunkDurationUs The duration of current media chunk being requested, in microseconds. If
+   *     the duration is not known, it can be set to {@link C#TIME_UNSET}.
    * @param streamingFormat The streaming format of the media content. Must be one of the allowed
    *     streaming formats specified by the {@link StreamingFormat} annotation.
    * @param isLive {@code true} if the media content is being streamed live, {@code false}
@@ -112,7 +113,7 @@ public static CmcdLog createInstance(
       }
       cmcdObject.setTopBitrateKbps(topBitrate / 1000);
     }
-    if (cmcdConfiguration.isObjectDurationLoggingAllowed()) {
+    if (cmcdConfiguration.isObjectDurationLoggingAllowed() && chunkDurationUs != C.TIME_UNSET) {
       cmcdObject.setObjectDurationMs(chunkDurationUs / 1000);
     }
 
@@ -122,6 +123,10 @@ public static CmcdLog createInstance(
     if (cmcdConfiguration.isBufferLengthLoggingAllowed()) {
       cmcdRequest.setBufferLengthMs(bufferedDurationUs / 1000);
     }
+    if (cmcdConfiguration.isMeasuredThroughputLoggingAllowed()
+        && trackSelection.getLatestBitrateEstimate() != Long.MIN_VALUE) {
+      cmcdRequest.setMeasuredThroughputInKbps(trackSelection.getLatestBitrateEstimate() / 1000);
+    }
 
     CmcdLog.CmcdSession.Builder cmcdSession =
         new CmcdLog.CmcdSession.Builder()
@@ -212,12 +217,11 @@ public Builder setTopBitrateKbps(int topBitrateKbps) {
       /**
        * Sets the {@link CmcdObject#objectDurationMs}. The default value is {@link C#TIME_UNSET}.
        *
-       * @throws IllegalArgumentException If {@code objectDurationMs} is not equal to {@link
-       *     C#TIME_UNSET} and is non-positive.
+       * @throws IllegalArgumentException If {@code objectDurationMs} is negative.
        */
       @CanIgnoreReturnValue
       public Builder setObjectDurationMs(long objectDurationMs) {
-        checkArgument(objectDurationMs == C.TIME_UNSET || objectDurationMs >= 0);
+        checkArgument(objectDurationMs >= 0);
         this.objectDurationMs = objectDurationMs;
         return this;
       }
@@ -316,25 +320,39 @@ private static final class CmcdRequest {
     /** Builder for {@link CmcdRequest} instances. */
     public static final class Builder {
       private long bufferLengthMs;
+      private long measuredThroughputInKbps;
       @Nullable private String customData;
 
       /** Creates a new instance with default values. */
       public Builder() {
         this.bufferLengthMs = C.TIME_UNSET;
+        this.measuredThroughputInKbps = Long.MIN_VALUE;
       }
 
       /**
        * Sets the {@link CmcdRequest#bufferLengthMs}. Rounded to nearest 100 ms. The default value
        * is {@link C#TIME_UNSET}.
        *
-       * @throws IllegalArgumentException If {@code bufferLengthMs} is not equal to {@link
-       *     C#TIME_UNSET} and is non-positive.
+       * @throws IllegalArgumentException If {@code bufferLengthMs} is negative.
        */
       @CanIgnoreReturnValue
       public Builder setBufferLengthMs(long bufferLengthMs) {
-        checkArgument(bufferLengthMs == C.TIME_UNSET || bufferLengthMs >= 0);
-        this.bufferLengthMs =
-            bufferLengthMs == C.TIME_UNSET ? bufferLengthMs : ((bufferLengthMs + 50) / 100) * 100;
+        checkArgument(bufferLengthMs >= 0);
+        this.bufferLengthMs = ((bufferLengthMs + 50) / 100) * 100;
+        return this;
+      }
+
+      /**
+       * Sets the {@link CmcdRequest#measuredThroughputInKbps}. Rounded to nearest 100 kbps. The
+       * default value is {@link Long#MIN_VALUE}.
+       *
+       * @throws IllegalArgumentException If {@code measuredThroughputInKbps} is negative.
+       */
+      @CanIgnoreReturnValue
+      public Builder setMeasuredThroughputInKbps(long measuredThroughputInKbps) {
+        checkArgument(measuredThroughputInKbps >= 0);
+        this.measuredThroughputInKbps = ((measuredThroughputInKbps + 50) / 100) * 100;
+
         return this;
       }
 
@@ -358,6 +376,19 @@ public CmcdRequest build() {
      */
     public final long bufferLengthMs;
 
+    /**
+     * The throughput between client and server, as measured by the client, or {@link
+     * Long#MIN_VALUE} if unset.
+     *
+     * <p>This value MUST be rounded to the nearest 100 kbps. This value, however derived, SHOULD be
+     * the value that the client is using to make its next Adaptive Bitrate switching decision. If
+     * the client is connected to multiple servers concurrently, it must take care to report only
+     * the throughput measured against the receiving server. If the client has multiple concurrent
+     * connections to the server, then the intent is that this value communicates the aggregate
+     * throughput the client sees across all those connections.
+     */
+    public final long measuredThroughputInKbps;
+
     /**
      * Custom data where the values of the keys vary with each request, or {@code null} if unset.
      *
@@ -368,6 +399,7 @@ public CmcdRequest build() {
 
     private CmcdRequest(Builder builder) {
       this.bufferLengthMs = builder.bufferLengthMs;
+      this.measuredThroughputInKbps = builder.measuredThroughputInKbps;
       this.customData = builder.customData;
     }
 
@@ -384,6 +416,11 @@ public void populateHttpRequestHeaders(
         headerValue.append(
             Util.formatInvariant("%s=%d,", CmcdConfiguration.KEY_BUFFER_LENGTH, bufferLengthMs));
       }
+      if (measuredThroughputInKbps != Long.MIN_VALUE) {
+        headerValue.append(
+            Util.formatInvariant(
+                "%s=%d,", CmcdConfiguration.KEY_MEASURED_THROUGHPUT, measuredThroughputInKbps));
+      }
       if (!TextUtils.isEmpty(customData)) {
         headerValue.append(Util.formatInvariant("%s,", customData));
       }
@@ -580,7 +617,7 @@ public Builder() {
        * The default value is {@link C#RATE_UNSET_INT}.
        *
        * @throws IllegalArgumentException If {@code maximumRequestedThroughputKbps} is not equal to
-       *     {@link C#RATE_UNSET_INT} and is non-positive.
+       *     {@link C#RATE_UNSET_INT} and is negative.
        */
       @CanIgnoreReturnValue
       public Builder setMaximumRequestedThroughputKbps(int maximumRequestedThroughputKbps) {

diff --git a/...er/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java b/...er/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java
@@ -107,6 +107,20 @@ public void initial_updateSelectedTrack_selectsHighestBitrateWithinBandwidthAndT
     assertThat(adaptiveTrackSelection.getSelectionReason()).isEqualTo(C.SELECTION_REASON_INITIAL);
   }
 
+  @Test
+  public void initial_updateSelectedTrack_returnsCorrectLatestBitrateEstimate() {
+    Format format1 = videoFormat(/* bitrate= */ 500, /* width= */ 320, /* height= */ 240);
+    Format format2 = videoFormat(/* bitrate= */ 1000, /* width= */ 640, /* height= */ 480);
+    TrackGroup trackGroup = new TrackGroup(format1, format2);
+
+    when(mockBandwidthMeter.getBitrateEstimate()).thenReturn(2000L);
+    AdaptiveTrackSelection adaptiveTrackSelection =
+        prepareAdaptiveTrackSelectionWithBandwidthFraction(
+            trackGroup, /* bandwidthFraction= */ 0.5f);
+
+    assertThat(adaptiveTrackSelection.getLatestBitrateEstimate()).isEqualTo(2000L);
+  }
+
   @Test
   public void updateSelectedTrackDoNotSwitchUpIfNotBufferedEnough() {
     Format format1 = videoFormat(/* bitrate= */ 500, /* width= */ 320, /* height= */ 240);

diff --git a/libraries/exoplayer/src/test/java/androidx/media3/exoplayer/upstream/CmcdLogTest.java b/libraries/exoplayer/src/test/java/androidx/media3/exoplayer/upstream/CmcdLogTest.java
@@ -61,6 +61,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
     when(trackSelection.getSelectedFormat()).thenReturn(format);
     when(trackSelection.getTrackGroup())
         .thenReturn(new TrackGroup(format, new Format.Builder().setPeakBitrate(1_000_000).build()));
+    when(trackSelection.getLatestBitrateEstimate()).thenReturn(500_000L);
     CmcdLog cmcdLog =
         CmcdLog.createInstance(
             cmcdConfiguration,
@@ -78,7 +79,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
             "CMCD-Object",
             "br=840,tb=1000,d=3000,key1=value1",
             "CMCD-Request",
-            "bl=1800,key2=\"stringValue\"",
+            "bl=1800,mtp=500,key2=\"stringValue\"",
             "CMCD-Session",
             "cid=\"mediaId\",sid=\"sessionId\",sf=d,st=l",
             "CMCD-Status",

diff --git a/...s/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DefaultDashChunkSource.java b/...s/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DefaultDashChunkSource.java
@@ -371,7 +371,7 @@ public void getNextChunk(
         playbackPositionUs, bufferedDurationUs, availableLiveDurationUs, queue, chunkIterators);
 
     int selectedTrackIndex = trackSelection.getSelectedIndex();
-    long chunkDurationUs = 0;
+    long chunkDurationUs = C.TIME_UNSET;
     if (selectedTrackIndex < chunkIterators.length && chunkIterators[selectedTrackIndex].next()) {
       chunkDurationUs =
           chunkIterators[selectedTrackIndex].getChunkEndTimeUs()

diff --git a/...oplayer_dash/src/test/java/androidx/media3/exoplayer/dash/DefaultDashChunkSourceTest.java b/...oplayer_dash/src/test/java/androidx/media3/exoplayer/dash/DefaultDashChunkSourceTest.java
@@ -316,7 +316,7 @@ public void getNextChunk_chunkSourceWithDefaultCmcdConfiguration_setsCmcdLogging
             "CMCD-Object",
             "br=700,tb=1300,d=4000",
             "CMCD-Request",
-            "bl=0",
+            "bl=0,mtp=1000",
             "CMCD-Session",
             "cid=\"mediaId\",sid=\"" + cmcdConfiguration.sessionId + "\",sf=d,st=v");
   }
@@ -361,7 +361,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
             "CMCD-Object",
             "br=700,tb=1300,d=4000",
             "CMCD-Request",
-            "bl=0",
+            "bl=0,mtp=1000",
             "CMCD-Session",
             "cid=\"mediaIdcontentIdSuffix\",sf=d,st=v",
             "CMCD-Status",
@@ -407,7 +407,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
             "CMCD-Object",
             "br=700,tb=1300,d=4000,key1=value1",
             "CMCD-Request",
-            "bl=0,key2=\"stringValue\"",
+            "bl=0,mtp=1000,key2=\"stringValue\"",
             "CMCD-Session",
             "cid=\"mediaId\",sid=\"" + cmcdConfiguration.sessionId + "\",sf=d,st=v,key3=1",
             "CMCD-Status",

diff --git a/libraries/exoplayer_hls/src/main/java/androidx/media3/exoplayer/hls/HlsChunkSource.java b/libraries/exoplayer_hls/src/main/java/androidx/media3/exoplayer/hls/HlsChunkSource.java
@@ -481,7 +481,7 @@ public void getNextChunk(
     seenExpectedPlaylistError = false;
     expectedPlaylistUrl = null;
 
-    long chunkDurationUs = 0;
+    long chunkDurationUs = C.TIME_UNSET;
     if (selectedTrackIndex < mediaChunkIterators.length
         && mediaChunkIterators[selectedTrackIndex].next()) {
       chunkDurationUs =

diff --git a/libraries/exoplayer_hls/src/test/java/androidx/media3/exoplayer/hls/HlsChunkSourceTest.java b/libraries/exoplayer_hls/src/test/java/androidx/media3/exoplayer/hls/HlsChunkSourceTest.java
@@ -210,7 +210,7 @@ public void getNextChunk_chunkSourceWithDefaultCmcdConfiguration_setsCmcdLogging
     assertThat(output.chunk.dataSpec.httpRequestHeaders)
         .containsExactly(
             "CMCD-Object",
-            "br=800,tb=800,d=0",
+            "br=800,tb=800",
             "CMCD-Request",
             "bl=0",
             "CMCD-Session",
@@ -256,7 +256,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
     assertThat(output.chunk.dataSpec.httpRequestHeaders)
         .containsExactly(
             "CMCD-Object",
-            "br=800,tb=800,d=0",
+            "br=800,tb=800",
             "CMCD-Request",
             "bl=0",
             "CMCD-Session",
@@ -303,7 +303,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
     assertThat(output.chunk.dataSpec.httpRequestHeaders)
         .containsExactly(
             "CMCD-Object",
-            "br=800,tb=800,d=0,key1=value1",
+            "br=800,tb=800,key1=value1",
             "CMCD-Request",
             "bl=0,key2=\"stringValue\"",
             "CMCD-Session",

diff --git a/...reaming/src/main/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSource.java b/...reaming/src/main/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSource.java
@@ -280,7 +280,7 @@ public final void getNextChunk(
     int manifestTrackIndex = trackSelection.getIndexInTrackGroup(trackSelectionIndex);
     Uri uri = streamElement.buildRequestUri(manifestTrackIndex, chunkIndex);
 
-    long chunkDurationUs = 0;
+    long chunkDurationUs = C.TIME_UNSET;
     if (trackSelectionIndex < chunkIterators.length && chunkIterators[trackSelectionIndex].next()) {
       chunkDurationUs =
           chunkIterators[trackSelectionIndex].getChunkEndTimeUs()

diff --git a/...ing/src/test/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSourceTest.java b/...ing/src/test/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSourceTest.java
@@ -66,7 +66,7 @@ public void getNextChunk_chunkSourceWithDefaultCmcdConfiguration_setsCmcdLogging
             "CMCD-Object",
             "br=307,tb=1536,d=1968",
             "CMCD-Request",
-            "bl=0",
+            "bl=0,mtp=1000",
             "CMCD-Session",
             "cid=\"mediaId\",sid=\"" + cmcdConfiguration.sessionId + "\",sf=s,st=v");
   }
@@ -111,7 +111,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
             "CMCD-Object",
             "br=307,tb=1536,d=1968",
             "CMCD-Request",
-            "bl=0",
+            "bl=0,mtp=1000",
             "CMCD-Session",
             "cid=\"mediaIdcontentIdSuffix\",sf=s,st=v",
             "CMCD-Status",
@@ -157,7 +157,7 @@ public int getRequestedMaximumThroughputKbps(int throughputKbps) {
             "CMCD-Object",
             "br=307,tb=1536,d=1968,key1=value1",
             "CMCD-Request",
-            "bl=0,key2=\"stringValue\"",
+            "bl=0,mtp=1000,key2=\"stringValue\"",
             "CMCD-Session",
             "cid=\"mediaId\",sid=\"" + cmcdConfiguration.sessionId + "\",sf=s,st=v,key3=1",
             "CMCD-Status",