diff --git a/RELEASENOTES.md b/RELEASENOTES.md index f82427b76f..386cfabf93 100644 --- a/RELEASENOTES.md +++ b/RELEASENOTES.md @@ -12,6 +12,9 @@ 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). * Audio Offload: * Prepend Ogg ID Header and Comment Header Pages to bitstream for offloaded Opus playback in accordance with RFC 7845. 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 index 53e579070c..9f52b32bbe 100644 --- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MergingMediaPeriod.java +++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/source/MergingMediaPeriod.java @@ -605,6 +605,11 @@ import org.checkerframework.checker.nullness.qual.MonotonicNonNull; 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/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelection.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelection.java index dd9ccf6e9f..8387c81da5 100644 --- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelection.java +++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelection.java @@ -319,6 +319,7 @@ public class AdaptiveTrackSelection extends BaseTrackSelection { private @C.SelectionReason int reason; private long lastBufferEvaluationMs; @Nullable private MediaChunk lastBufferEvaluationMediaChunk; + private long latestBitrateEstimate; /** * @param group The {@link TrackGroup}. @@ -410,6 +411,7 @@ public class AdaptiveTrackSelection extends BaseTrackSelection { playbackSpeed = 1f; reason = C.SELECTION_REASON_UNKNOWN; lastBufferEvaluationMs = C.TIME_UNSET; + latestBitrateEstimate = Long.MIN_VALUE; } @CallSuper @@ -543,6 +545,11 @@ public class AdaptiveTrackSelection extends BaseTrackSelection { 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 @@ public class AdaptiveTrackSelection extends BaseTrackSelection { } 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/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/ExoTrackSelection.java b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/ExoTrackSelection.java index 4b32ff66e4..fdc0547b67 100644 --- a/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/ExoTrackSelection.java +++ b/libraries/exoplayer/src/main/java/androidx/media3/exoplayer/trackselection/ExoTrackSelection.java @@ -290,4 +290,14 @@ public interface ExoTrackSelection extends TrackSelection { * android.os.SystemClock#elapsedRealtime()}. */ boolean isTrackExcluded(int index, long nowMs); + + /** + * Returns the most recent bitrate estimate utilised for track selection. + * + *
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 index 2b88501168..195b73b385 100644 --- 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. @@ -279,4 +281,12 @@ public final class CmcdConfiguration { 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 index 93766934b4..999edd615b 100644 --- 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 final class CmcdLog { } cmcdObject.setTopBitrateKbps(topBitrate / 1000); } - if (cmcdConfiguration.isObjectDurationLoggingAllowed()) { + if (cmcdConfiguration.isObjectDurationLoggingAllowed() && chunkDurationUs != C.TIME_UNSET) { cmcdObject.setObjectDurationMs(chunkDurationUs / 1000); } @@ -122,6 +123,10 @@ public final class CmcdLog { 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 final class CmcdLog { /** * 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; } @@ -315,25 +319,39 @@ public final class CmcdLog { /** 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; } @@ -356,6 +374,19 @@ public final class CmcdLog { *
This value MUST be rounded to the nearest 100 ms. */ public final long bufferLengthMs; + /** + * The throughput between client and server, as measured by the client, or {@link + * Long#MIN_VALUE} if unset. + * + *
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. * @@ -366,6 +397,7 @@ public final class CmcdLog { private CmcdRequest(Builder builder) { this.bufferLengthMs = builder.bufferLengthMs; + this.measuredThroughputInKbps = builder.measuredThroughputInKbps; this.customData = builder.customData; } @@ -382,6 +414,11 @@ public final class CmcdLog { 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)); } @@ -576,7 +613,7 @@ public final class CmcdLog { * 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/libraries/exoplayer/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java b/libraries/exoplayer/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java index 6c7061b414..4197917c4d 100644 --- a/libraries/exoplayer/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java +++ b/libraries/exoplayer/src/test/java/androidx/media3/exoplayer/trackselection/AdaptiveTrackSelectionTest.java @@ -107,6 +107,20 @@ public final class AdaptiveTrackSelectionTest { 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 index 9de7bf660c..fc7fbd1fda 100644 --- 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 class CmcdLogTest { 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 class CmcdLogTest { "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/libraries/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DefaultDashChunkSource.java b/libraries/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DefaultDashChunkSource.java index 71e7bb2a65..9194e1ca7d 100644 --- a/libraries/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DefaultDashChunkSource.java +++ b/libraries/exoplayer_dash/src/main/java/androidx/media3/exoplayer/dash/DefaultDashChunkSource.java @@ -371,7 +371,7 @@ public class DefaultDashChunkSource implements DashChunkSource { 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/libraries/exoplayer_dash/src/test/java/androidx/media3/exoplayer/dash/DefaultDashChunkSourceTest.java b/libraries/exoplayer_dash/src/test/java/androidx/media3/exoplayer/dash/DefaultDashChunkSourceTest.java index d9bc88301c..bd913aa183 100644 --- a/libraries/exoplayer_dash/src/test/java/androidx/media3/exoplayer/dash/DefaultDashChunkSourceTest.java +++ b/libraries/exoplayer_dash/src/test/java/androidx/media3/exoplayer/dash/DefaultDashChunkSourceTest.java @@ -316,7 +316,7 @@ public class DefaultDashChunkSourceTest { "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 class DefaultDashChunkSourceTest { "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 class DefaultDashChunkSourceTest { "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 index 0e81d3509f..0d09d98664 100644 --- 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 @@ -479,7 +479,7 @@ import org.checkerframework.checker.nullness.qual.MonotonicNonNull; 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 index 1f6e243e11..41d47fc41d 100644 --- 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 class HlsChunkSourceTest { 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 class HlsChunkSourceTest { 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 class HlsChunkSourceTest { 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/libraries/exoplayer_smoothstreaming/src/main/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSource.java b/libraries/exoplayer_smoothstreaming/src/main/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSource.java index 3871bb7644..886589a88b 100644 --- a/libraries/exoplayer_smoothstreaming/src/main/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSource.java +++ b/libraries/exoplayer_smoothstreaming/src/main/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSource.java @@ -280,7 +280,7 @@ public class DefaultSsChunkSource implements SsChunkSource { 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/libraries/exoplayer_smoothstreaming/src/test/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSourceTest.java b/libraries/exoplayer_smoothstreaming/src/test/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSourceTest.java index fa8a7d43a8..7a22a9d435 100644 --- a/libraries/exoplayer_smoothstreaming/src/test/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSourceTest.java +++ b/libraries/exoplayer_smoothstreaming/src/test/java/androidx/media3/exoplayer/smoothstreaming/DefaultSsChunkSourceTest.java @@ -66,7 +66,7 @@ public class DefaultSsChunkSourceTest { "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 class DefaultSsChunkSourceTest { "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 class DefaultSsChunkSourceTest { "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",