diff --git a/libraries/common/src/main/java/androidx/media3/common/C.java b/libraries/common/src/main/java/androidx/media3/common/C.java index 440292516d..1367f1d024 100644 --- a/libraries/common/src/main/java/androidx/media3/common/C.java +++ b/libraries/common/src/main/java/androidx/media3/common/C.java @@ -1237,7 +1237,8 @@ public final class C { /** * A value indicating the priority of a operation. * - *

Larger values indicate higher priorities. + *

Larger values indicate higher priorities, but values should not exceed {@link + * #PRIORITY_MAX}. * *

The predefined priority values are used by default and it's recommended to align any custom * values relative to these defaults (for example, {@code C.PRIORITY_PLAYBACK - 1}. @@ -1245,7 +1246,11 @@ public final class C { *

Predefined values are (in descending priority order): * *

*/ @@ -1255,14 +1260,42 @@ public final class C { @Target(TYPE_USE) @IntDef( open = true, - value = {PRIORITY_PLAYBACK, PRIORITY_DOWNLOAD}) + value = { + PRIORITY_MAX, + PRIORITY_PLAYBACK, + PRIORITY_DOWNLOAD, + PRIORITY_PLAYBACK_PRELOAD, + PRIORITY_PROCESSING_BACKGROUND, + PRIORITY_PROCESSING_FOREGROUND + }) public @interface Priority {} + /** The maximum supported {@link Priority}. */ + @UnstableApi public static final int PRIORITY_MAX = 0; + /** {@link Priority} for active media playback. */ - @UnstableApi public static final int PRIORITY_PLAYBACK = 0; + @UnstableApi public static final int PRIORITY_PLAYBACK = PRIORITY_MAX - 1000; + + /** + * {@link Priority} for processing media in the foreground (for example, while the user is waiting + * for the processing to complete). + */ + @UnstableApi public static final int PRIORITY_PROCESSING_FOREGROUND = PRIORITY_PLAYBACK - 1000; + + /** + * {@link Priority} for preloading media playback resources before the playback becomes active. + */ + @UnstableApi + public static final int PRIORITY_PLAYBACK_PRELOAD = PRIORITY_PROCESSING_FOREGROUND - 1000; /** {@link Priority} for media downloading unrelated to active playback. */ - @UnstableApi public static final int PRIORITY_DOWNLOAD = PRIORITY_PLAYBACK - 1000; + @UnstableApi public static final int PRIORITY_DOWNLOAD = PRIORITY_PLAYBACK_PRELOAD - 1000; + + /** + * {@link Priority} for processing media in the background (for example, when the user is not + * waiting for the processing to complete). + */ + @UnstableApi public static final int PRIORITY_PROCESSING_BACKGROUND = PRIORITY_DOWNLOAD; /** * Network connection type. One of {@link #NETWORK_TYPE_UNKNOWN}, {@link #NETWORK_TYPE_OFFLINE}, diff --git a/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultDecoderFactory.java b/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultDecoderFactory.java index 37910003f0..90061363b3 100644 --- a/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultDecoderFactory.java +++ b/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultDecoderFactory.java @@ -19,6 +19,7 @@ package androidx.media3.transformer; import static androidx.media3.common.util.Assertions.checkNotNull; import static androidx.media3.common.util.MediaFormatUtil.createMediaFormatFromFormat; import static androidx.media3.common.util.Util.SDK_INT; +import static java.lang.Math.max; import android.annotation.SuppressLint; import android.content.Context; @@ -53,9 +54,6 @@ public final class DefaultDecoderFactory implements Codec.DecoderFactory { private static final String TAG = "DefaultDecoderFactory"; - /** The platform's default value of {@code MediaFormat#KEY_IMPORTANCE}. */ - private static final int DEFAULT_CODEC_IMPORTANCE = 0; - /** Listener for decoder factory events. */ public interface Listener { /** @@ -76,13 +74,13 @@ public final class DefaultDecoderFactory implements Codec.DecoderFactory { private final Context context; private Listener listener; private boolean enableDecoderFallback; - private int codecImportance; + private @C.Priority int codecPriority; /** Creates a new {@link Builder}. */ public Builder(Context context) { this.context = context.getApplicationContext(); listener = (codecName, codecInitializationExceptions) -> {}; - codecImportance = DEFAULT_CODEC_IMPORTANCE; + codecPriority = C.PRIORITY_PROCESSING_FOREGROUND; } /** Sets the {@link Listener}. */ @@ -108,21 +106,25 @@ public final class DefaultDecoderFactory implements Codec.DecoderFactory { } /** - * Sets the codec importance value. + * Sets the codec priority. * - *

Specifying codec importance allows the resource manager in the platform to reclaim less - * important codecs (higher importance values) before more important codecs. For example, codecs - * used for background operations should have higher importance values so they are reclaimed if - * required for foreground operations. + *

Specifying codec priority allows the resource manager in the platform to reclaim less + * important codecs before more important codecs. + * + *

It is recommended to use predefined {@linkplain C.Priority priorities} like {@link + * C#PRIORITY_PROCESSING_FOREGROUND}, {@link C#PRIORITY_PROCESSING_BACKGROUND} or priority + * values defined relative to those defaults. * *

This method is a no-op on API versions before 35. * - *

The default value is {@code 0}. + *

The default value is {@link C#PRIORITY_PROCESSING_FOREGROUND}. + * + * @param codecPriority The {@link C.Priority} for the codec. Should be at most {@link + * C#PRIORITY_MAX}. */ - // TODO: b/333552477 - Link documentation after API35 is released. @CanIgnoreReturnValue - public Builder setCodecImportance(@IntRange(from = 0) int codecImportance) { - this.codecImportance = codecImportance; + public Builder setCodecPriority(@IntRange(to = C.PRIORITY_MAX) @C.Priority int codecPriority) { + this.codecPriority = codecPriority; return this; } @@ -135,7 +137,7 @@ public final class DefaultDecoderFactory implements Codec.DecoderFactory { private final Context context; private final boolean enableDecoderFallback; private final Listener listener; - private final int codecImportance; + private final @C.Priority int codecPriority; /** * @deprecated Use {@link Builder} instead. @@ -166,7 +168,7 @@ public final class DefaultDecoderFactory implements Codec.DecoderFactory { this.context = builder.context; this.enableDecoderFallback = builder.enableDecoderFallback; this.listener = builder.listener; - this.codecImportance = builder.codecImportance; + this.codecPriority = builder.codecPriority; } @Override @@ -224,7 +226,7 @@ public final class DefaultDecoderFactory implements Codec.DecoderFactory { if (SDK_INT >= 35) { // TODO: b/333552477 - Redefinition of MediaFormat.KEY_IMPORTANCE, remove after API35 is // released. - mediaFormat.setInteger("importance", codecImportance); + mediaFormat.setInteger("importance", max(0, -codecPriority)); } return createCodecForMediaFormat(mediaFormat, format, outputSurface); diff --git a/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultEncoderFactory.java b/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultEncoderFactory.java index c958ce8f14..5832e41a28 100644 --- a/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultEncoderFactory.java +++ b/libraries/transformer/src/main/java/androidx/media3/transformer/DefaultEncoderFactory.java @@ -24,6 +24,7 @@ import static androidx.media3.common.util.MediaFormatUtil.createMediaFormatFromF import static androidx.media3.common.util.Util.SDK_INT; import static java.lang.Math.abs; import static java.lang.Math.floor; +import static java.lang.Math.max; import static java.lang.Math.round; import android.content.Context; @@ -34,6 +35,7 @@ import android.util.Pair; import android.util.Size; import androidx.annotation.IntRange; import androidx.annotation.Nullable; +import androidx.media3.common.C; import androidx.media3.common.ColorInfo; import androidx.media3.common.Format; import androidx.media3.common.MimeTypes; @@ -55,9 +57,6 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { /** Best effort, or as-fast-as-possible priority setting for {@link MediaFormat#KEY_PRIORITY}. */ private static final int PRIORITY_BEST_EFFORT = 1; - /** The platform's default value of {@code MediaFormat#KEY_IMPORTANCE}. */ - private static final int DEFAULT_CODEC_IMPORTANCE = 0; - /** A builder for {@link DefaultEncoderFactory} instances. */ public static final class Builder { private final Context context; @@ -65,7 +64,7 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { private EncoderSelector videoEncoderSelector; private VideoEncoderSettings requestedVideoEncoderSettings; private boolean enableFallback; - private int codecImportance; + private @C.Priority int codecPriority; /** Creates a new {@link Builder}. */ public Builder(Context context) { @@ -73,7 +72,7 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { videoEncoderSelector = EncoderSelector.DEFAULT; requestedVideoEncoderSettings = VideoEncoderSettings.DEFAULT; enableFallback = true; - codecImportance = DEFAULT_CODEC_IMPORTANCE; + codecPriority = C.PRIORITY_PROCESSING_FOREGROUND; } /** @@ -129,21 +128,25 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { } /** - * Sets the codec importance value. + * Sets the codec priority. * - *

Specifying codec importance allows the resource manager in the platform to reclaim less - * important codecs (higher importance values) before more important codecs. For example, codecs - * used for background operations should have higher importance values so they are reclaimed if - * required for foreground operations. + *

Specifying codec priority allows the resource manager in the platform to reclaim less + * important codecs before more important codecs. + * + *

It is recommended to use predefined {@linkplain C.Priority priorities} like {@link + * C#PRIORITY_PROCESSING_FOREGROUND}, {@link C#PRIORITY_PROCESSING_BACKGROUND} or priority + * values defined relative to those defaults. * *

This method is a no-op on API versions before 35. * - *

The default value is {@code 0}. + *

The default value is {@link C#PRIORITY_PROCESSING_FOREGROUND}. + * + * @param codecPriority The {@link C.Priority} for the codec. Should be at most {@link + * C#PRIORITY_MAX}. */ - // TODO: b/333552477 - Link documentation after API35 is released. @CanIgnoreReturnValue - public Builder setCodecImportance(@IntRange(from = 0) int codecImportance) { - this.codecImportance = codecImportance; + public Builder setCodecPriority(@IntRange(to = C.PRIORITY_MAX) @C.Priority int codecPriority) { + this.codecPriority = codecPriority; return this; } @@ -157,7 +160,7 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { private final EncoderSelector videoEncoderSelector; private final VideoEncoderSettings requestedVideoEncoderSettings; private final boolean enableFallback; - private final int codecImportance; + private final @C.Priority int codecPriority; /** * @deprecated Use {@link Builder} instead. @@ -200,7 +203,7 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { this.videoEncoderSelector = builder.videoEncoderSelector; this.requestedVideoEncoderSettings = builder.requestedVideoEncoderSettings; this.enableFallback = builder.enableFallback; - this.codecImportance = builder.codecImportance; + this.codecPriority = builder.codecPriority; } @Override @@ -359,7 +362,7 @@ public final class DefaultEncoderFactory implements Codec.EncoderFactory { if (Util.SDK_INT >= 35) { // TODO: b/333552477 - Redefinition of MediaFormat.KEY_IMPORTANCE, remove after API35 is // released. - mediaFormat.setInteger("importance", codecImportance); + mediaFormat.setInteger("importance", max(0, -codecPriority)); } return new DefaultCodec(