From 25ed6b127d15b17c3f1d74cbf7e34cad78d65295 Mon Sep 17 00:00:00 2001 From: tonihei Date: Wed, 6 Jan 2021 18:20:07 +0000 Subject: [PATCH] Clarify parameter Javadoc for playback speed values. In many cases we just used "playback speed" as a detailed Javadoc parameter or return type definition. This doesn't define which scale the speed is using. PlaybackParameters as the main point to set the speed already uses a more precise wording to describe the value as a factor by which playback will be sped up. This change replaces other usages of "playback speed" with this wording whereever we would usually add a unit, keeping "playback speed" for summary statements etc to reference the general concept that doesn't usually require a unit. PiperOrigin-RevId: 350379139 --- .../google/android/exoplayer2/MediaItem.java | 18 ++++++++++++------ .../google/android/exoplayer2/util/Util.java | 2 +- .../DefaultLivePlaybackSpeedControl.java | 16 ++++++++-------- .../exoplayer2/LivePlaybackSpeedControl.java | 2 +- .../google/android/exoplayer2/LoadControl.java | 4 ++-- .../android/exoplayer2/MediaPeriodHolder.java | 4 ++-- .../google/android/exoplayer2/Renderer.java | 5 ++--- .../exoplayer2/audio/SonicAudioProcessor.java | 2 +- .../mediacodec/MediaCodecRenderer.java | 2 +- .../source/DefaultMediaSourceFactory.java | 8 ++++---- .../trackselection/AdaptiveTrackSelection.java | 2 +- .../trackselection/TrackSelection.java | 2 +- .../manifest/ServiceDescriptionElement.java | 18 ++++++++++++------ 13 files changed, 48 insertions(+), 37 deletions(-) diff --git a/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java b/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java index 12f1951f9f..184c065e8a 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java +++ b/library/common/src/main/java/com/google/android/exoplayer2/MediaItem.java @@ -514,8 +514,8 @@ public final class MediaItem { * *

This value is ignored for other stream types. * - * @param minPlaybackSpeed The minimum playback speed for live streams, or {@link C#RATE_UNSET} - * to use the media-defined default. + * @param minPlaybackSpeed The minimum factor by which playback can be sped up for live streams, + * or {@link C#RATE_UNSET} to use the media-defined default. */ public Builder setLiveMinPlaybackSpeed(float minPlaybackSpeed) { this.liveMinPlaybackSpeed = minPlaybackSpeed; @@ -527,8 +527,8 @@ public final class MediaItem { * *

This value is ignored for other stream types. * - * @param maxPlaybackSpeed The maximum playback speed for live streams, or {@link C#RATE_UNSET} - * to use the media-defined default. + * @param maxPlaybackSpeed The maximum factor by which playback can be sped up for live streams, + * or {@link C#RATE_UNSET} to use the media-defined default. */ public Builder setLiveMaxPlaybackSpeed(float maxPlaybackSpeed) { this.liveMaxPlaybackSpeed = maxPlaybackSpeed; @@ -865,10 +865,16 @@ public final class MediaItem { */ public final long maxOffsetMs; - /** Minimum playback speed, or {@link C#RATE_UNSET} to use the media-defined default. */ + /** + * Minimum factor by which playback can be sped up, or {@link C#RATE_UNSET} to use the + * media-defined default. + */ public final float minPlaybackSpeed; - /** Maximum playback speed, or {@link C#RATE_UNSET} to use the media-defined default. */ + /** + * Maximum factor by which playback can be sped up, or {@link C#RATE_UNSET} to use the + * media-defined default. + */ public final float maxPlaybackSpeed; /** diff --git a/library/common/src/main/java/com/google/android/exoplayer2/util/Util.java b/library/common/src/main/java/com/google/android/exoplayer2/util/Util.java index 69e708c366..c4af6bd2fc 100644 --- a/library/common/src/main/java/com/google/android/exoplayer2/util/Util.java +++ b/library/common/src/main/java/com/google/android/exoplayer2/util/Util.java @@ -1363,7 +1363,7 @@ public final class Util { * Returns the duration of media that will elapse in {@code playoutDuration}. * * @param playoutDuration The duration to scale. - * @param speed The playback speed. + * @param speed The factor by which playback is sped up. * @return The scaled duration, in the same units as {@code playoutDuration}. */ public static long getMediaDurationForPlayoutDuration(long playoutDuration, float speed) { diff --git a/library/core/src/main/java/com/google/android/exoplayer2/DefaultLivePlaybackSpeedControl.java b/library/core/src/main/java/com/google/android/exoplayer2/DefaultLivePlaybackSpeedControl.java index 9291508721..e4fa65c436 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/DefaultLivePlaybackSpeedControl.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/DefaultLivePlaybackSpeedControl.java @@ -48,14 +48,14 @@ import com.google.android.exoplayer2.util.Util; public final class DefaultLivePlaybackSpeedControl implements LivePlaybackSpeedControl { /** - * The default minimum playback speed that should be used if no minimum playback speed is defined - * by the media. + * The default minimum factor by which playback can be sped up that should be used if no minimum + * playback speed is defined by the media. */ public static final float DEFAULT_FALLBACK_MIN_PLAYBACK_SPEED = 0.97f; /** - * The default maximum playback speed that should be used if no maximum playback speed is defined - * by the media. + * The default maximum factor by which playback can be sped up that should be used if no maximum + * playback speed is defined by the media. */ public static final float DEFAULT_FALLBACK_MAX_PLAYBACK_SPEED = 1.03f; @@ -118,7 +118,7 @@ public final class DefaultLivePlaybackSpeedControl implements LivePlaybackSpeedC * *

The default is {@link #DEFAULT_FALLBACK_MIN_PLAYBACK_SPEED}. * - * @param fallbackMinPlaybackSpeed The fallback minimum playback speed. + * @param fallbackMinPlaybackSpeed The fallback minimum factor by which playback can be sped up. * @return This builder, for convenience. */ public Builder setFallbackMinPlaybackSpeed(float fallbackMinPlaybackSpeed) { @@ -133,7 +133,7 @@ public final class DefaultLivePlaybackSpeedControl implements LivePlaybackSpeedC * *

The default is {@link #DEFAULT_FALLBACK_MAX_PLAYBACK_SPEED}. * - * @param fallbackMaxPlaybackSpeed The fallback maximum playback speed. + * @param fallbackMaxPlaybackSpeed The fallback maximum factor by which playback can be sped up. * @return This builder, for convenience. */ public Builder setFallbackMaxPlaybackSpeed(float fallbackMaxPlaybackSpeed) { @@ -160,8 +160,8 @@ public final class DefaultLivePlaybackSpeedControl implements LivePlaybackSpeedC /** * Sets the proportional control factor used to adjust the playback speed. * - *

The adjusted playback speed is calculated as {@code 1.0 + proportionalControlFactor x - * (currentLiveOffsetSec - targetLiveOffsetSec)}. + *

The factor by which playback will be sped up is calculated as {@code 1.0 + + * proportionalControlFactor x (currentLiveOffsetSec - targetLiveOffsetSec)}. * *

The default is {@link #DEFAULT_PROPORTIONAL_CONTROL_FACTOR}. * diff --git a/library/core/src/main/java/com/google/android/exoplayer2/LivePlaybackSpeedControl.java b/library/core/src/main/java/com/google/android/exoplayer2/LivePlaybackSpeedControl.java index 1ffdc82457..57f85486ab 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/LivePlaybackSpeedControl.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/LivePlaybackSpeedControl.java @@ -55,7 +55,7 @@ public interface LivePlaybackSpeedControl { * * @param liveOffsetUs The current live offset, in microseconds. * @param bufferedDurationUs The duration of media that's currently buffered, in microseconds. - * @return The adjusted playback speed. + * @return The adjusted factor by which playback should be sped up. */ float getAdjustedPlaybackSpeed(long liveOffsetUs, long bufferedDurationUs); diff --git a/library/core/src/main/java/com/google/android/exoplayer2/LoadControl.java b/library/core/src/main/java/com/google/android/exoplayer2/LoadControl.java index 2f3a665f75..f04ae8027d 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/LoadControl.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/LoadControl.java @@ -94,7 +94,7 @@ public interface LoadControl { * negative and equal in magnitude to the duration of any media in previous periods still to * be played. * @param bufferedDurationUs The duration of media that's currently buffered. - * @param playbackSpeed The current playback speed. + * @param playbackSpeed The current factor by which playback is sped up. * @return Whether the loading should continue. */ boolean shouldContinueLoading( @@ -107,7 +107,7 @@ public interface LoadControl { * false} until some condition has been met (e.g. a certain amount of media is buffered). * * @param bufferedDurationUs The duration of media that's currently buffered. - * @param playbackSpeed The current playback speed. + * @param playbackSpeed The current factor by which playback is sped up. * @param rebuffering Whether the player is rebuffering. A rebuffer is defined to be caused by * buffer depletion rather than a user action. Hence this parameter is false during initial * buffering and when buffering as a result of a seek operation. diff --git a/library/core/src/main/java/com/google/android/exoplayer2/MediaPeriodHolder.java b/library/core/src/main/java/com/google/android/exoplayer2/MediaPeriodHolder.java index 65f40e9c61..6bbd609dd5 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/MediaPeriodHolder.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/MediaPeriodHolder.java @@ -173,7 +173,7 @@ import org.checkerframework.checker.nullness.compatqual.NullableType; /** * Handles period preparation. * - * @param playbackSpeed The current playback speed. + * @param playbackSpeed The current factor by which playback is sped up. * @param timeline The current {@link Timeline}. * @throws ExoPlaybackException If an error occurs during track selection. */ @@ -224,7 +224,7 @@ import org.checkerframework.checker.nullness.compatqual.NullableType; *

The new track selection needs to be applied with {@link * #applyTrackSelection(TrackSelectorResult, long, boolean)} before taking effect. * - * @param playbackSpeed The current playback speed. + * @param playbackSpeed The current factor by which playback is sped up. * @param timeline The current {@link Timeline}. * @return The {@link TrackSelectorResult}. * @throws ExoPlaybackException If an error occurs during track selection. diff --git a/library/core/src/main/java/com/google/android/exoplayer2/Renderer.java b/library/core/src/main/java/com/google/android/exoplayer2/Renderer.java index 941aef2495..515f723cb9 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/Renderer.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/Renderer.java @@ -399,12 +399,11 @@ public interface Renderer extends PlayerMessage.Target { void resetPosition(long positionUs) throws ExoPlaybackException; /** - * Indicates the player's speed to this renderer, where 1 is the default rate, 2 is twice the - * default rate, 0.5 is half the default rate and so on. + * Indicates the playback speed to this renderer. * *

The default implementation is a no-op. * - * @param playbackSpeed The playback speed. + * @param playbackSpeed The factor by which playback is sped up. * @throws ExoPlaybackException If an error occurs handling the playback speed. */ default void setPlaybackSpeed(float playbackSpeed) throws ExoPlaybackException {} diff --git a/library/core/src/main/java/com/google/android/exoplayer2/audio/SonicAudioProcessor.java b/library/core/src/main/java/com/google/android/exoplayer2/audio/SonicAudioProcessor.java index c31303aa62..bbfd77469d 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/audio/SonicAudioProcessor.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/audio/SonicAudioProcessor.java @@ -79,7 +79,7 @@ public final class SonicAudioProcessor implements AudioProcessor { * processor. The value returned by {@link #isActive()} may change, and the processor must be * {@link #flush() flushed} before queueing more data. * - * @param speed The target playback speed. + * @param speed The target factor by which playback should be sped up. */ public void setSpeed(float speed) { if (this.speed != speed) { diff --git a/library/core/src/main/java/com/google/android/exoplayer2/mediacodec/MediaCodecRenderer.java b/library/core/src/main/java/com/google/android/exoplayer2/mediacodec/MediaCodecRenderer.java index 9877bab2d4..45d9b53d90 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/mediacodec/MediaCodecRenderer.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/mediacodec/MediaCodecRenderer.java @@ -1631,7 +1631,7 @@ public abstract class MediaCodecRenderer extends BaseRenderer { * *

The default implementation returns {@link #CODEC_OPERATING_RATE_UNSET}. * - * @param playbackSpeed The playback speed. + * @param playbackSpeed The factor by which playback is sped up. * @param format The {@link Format} for which the codec is being configured. * @param streamFormats The possible stream formats. * @return The codec operating rate, or {@link #CODEC_OPERATING_RATE_UNSET} if no codec operating diff --git a/library/core/src/main/java/com/google/android/exoplayer2/source/DefaultMediaSourceFactory.java b/library/core/src/main/java/com/google/android/exoplayer2/source/DefaultMediaSourceFactory.java index c0b82781df..b30e7c268a 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/source/DefaultMediaSourceFactory.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/source/DefaultMediaSourceFactory.java @@ -233,8 +233,8 @@ public final class DefaultMediaSourceFactory implements MediaSourceFactory { /** * Sets the minimum playback speed for live streams. * - * @param minSpeed The minimum playback speed for live streams, or {@link C#RATE_UNSET} to use the - * media-defined default. + * @param minSpeed The minimum factor by which playback can be sped up for live streams, or {@link + * C#RATE_UNSET} to use the media-defined default. * @return This factory, for convenience. */ public DefaultMediaSourceFactory setLiveMinSpeed(float minSpeed) { @@ -245,8 +245,8 @@ public final class DefaultMediaSourceFactory implements MediaSourceFactory { /** * Sets the maximum playback speed for live streams. * - * @param maxSpeed The maximum playback speed for live streams, or {@link C#RATE_UNSET} to use the - * media-defined default. + * @param maxSpeed The maximum factor by which playback can be sped up for live streams, or {@link + * C#RATE_UNSET} to use the media-defined default. * @return This factory, for convenience. */ public DefaultMediaSourceFactory setLiveMaxSpeed(float maxSpeed) { diff --git a/library/core/src/main/java/com/google/android/exoplayer2/trackselection/AdaptiveTrackSelection.java b/library/core/src/main/java/com/google/android/exoplayer2/trackselection/AdaptiveTrackSelection.java index e8328a2c42..9d5cc78d0b 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/trackselection/AdaptiveTrackSelection.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/trackselection/AdaptiveTrackSelection.java @@ -413,7 +413,7 @@ public class AdaptiveTrackSelection extends BaseTrackSelection { * @param format The {@link Format} of the candidate track. * @param trackBitrate The estimated bitrate of the track. May differ from {@link Format#bitrate} * if a more accurate estimate of the current track bitrate is available. - * @param playbackSpeed The current playback speed. + * @param playbackSpeed The current factor by which playback is sped up. * @param effectiveBitrate The bitrate available to this selection. * @return Whether this {@link Format} can be selected. */ diff --git a/library/core/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelection.java b/library/core/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelection.java index 5d643bd0eb..5a660a0f11 100644 --- a/library/core/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelection.java +++ b/library/core/src/main/java/com/google/android/exoplayer2/trackselection/TrackSelection.java @@ -184,7 +184,7 @@ public interface TrackSelection { * Called to notify the selection of the current playback speed. The playback speed may affect * adaptive track selection. * - * @param speed The playback speed. + * @param speed The factor by which playback is sped up. */ void onPlaybackSpeed(float speed); diff --git a/library/dash/src/main/java/com/google/android/exoplayer2/source/dash/manifest/ServiceDescriptionElement.java b/library/dash/src/main/java/com/google/android/exoplayer2/source/dash/manifest/ServiceDescriptionElement.java index 51bd365e3c..eec862f4f4 100644 --- a/library/dash/src/main/java/com/google/android/exoplayer2/source/dash/manifest/ServiceDescriptionElement.java +++ b/library/dash/src/main/java/com/google/android/exoplayer2/source/dash/manifest/ServiceDescriptionElement.java @@ -26,9 +26,15 @@ public final class ServiceDescriptionElement { public final long minOffsetMs; /** The maximum live offset in milliseconds, or {@link C#TIME_UNSET} if undefined. */ public final long maxOffsetMs; - /** The minimum playback speed for live speed adjustment, or {@link C#RATE_UNSET} if undefined. */ + /** + * The minimum factor by which playback can be sped up for live speed adjustment, or {@link + * C#RATE_UNSET} if undefined. + */ public final float minPlaybackSpeed; - /** The maximum playback speed for live speed adjustment, or {@link C#RATE_UNSET} if undefined. */ + /** + * The maximum factor by which playback can be sped up for live speed adjustment, or {@link + * C#RATE_UNSET} if undefined. + */ public final float maxPlaybackSpeed; /** @@ -40,10 +46,10 @@ public final class ServiceDescriptionElement { * undefined. * @param maxOffsetMs The maximum live offset in milliseconds, or {@link C#TIME_UNSET} if * undefined. - * @param minPlaybackSpeed The minimum playback speed for live speed adjustment, or {@link - * C#RATE_UNSET} if undefined. - * @param maxPlaybackSpeed The maximum playback speed for live speed adjustment, or {@link - * C#RATE_UNSET} if undefined. + * @param minPlaybackSpeed The minimum factor by which playback can be sped up for live speed + * adjustment, or {@link C#RATE_UNSET} if undefined. + * @param maxPlaybackSpeed The maximum factor by which playback can be sped up for live speed + * adjustment, or {@link C#RATE_UNSET} if undefined. */ public ServiceDescriptionElement( long targetOffsetMs,