Add more predefined priority values

Also add documentation that suggests to use them in
PriorityTaskManager and adjust codec priorities in
Transformer's DefaultDe/EncoderFactory accordingly.

PiperOrigin-RevId: 633272667

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.
    *
-   * <p>Larger values indicate higher priorities.
+   * <p>Larger values indicate higher priorities, but values should not exceed {@link
+   * #PRIORITY_MAX}.
    *
    * <p>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 {
    * <p>Predefined values are (in descending priority order):
    *
    * <ul>
+   *   <li>{@link #PRIORITY_MAX}
    *   <li>{@link #PRIORITY_PLAYBACK}
+   *   <li>{@link #PRIORITY_PROCESSING_FOREGROUND}
+   *   <li>{@link #PRIORITY_PLAYBACK_PRELOAD}
+   *   <li>{@link #PRIORITY_PROCESSING_BACKGROUND}
    *   <li>{@link #PRIORITY_DOWNLOAD}
    * </ul>
    */
@@ -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},

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.
      *
-     * <p>Specifying codec importance allows the resource manager in the platform to reclaim less
+     * <p>Specifying codec priority allows the resource manager in the platform to reclaim less
-     * important codecs (higher importance values) before more important codecs. For example, codecs
+     * important codecs before more important codecs.
-     * used for background operations should have higher importance values so they are reclaimed if
+     *
-     * required for foreground operations.
+     * <p>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.
      *
      * <p>This method is a no-op on API versions before 35.
      *
-     * <p>The default value is {@code 0}.
+     * <p>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) {
+    public Builder setCodecPriority(@IntRange(to = C.PRIORITY_MAX) @C.Priority int codecPriority) {
-      this.codecImportance = codecImportance;
+      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);

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.
      *
-     * <p>Specifying codec importance allows the resource manager in the platform to reclaim less
+     * <p>Specifying codec priority allows the resource manager in the platform to reclaim less
-     * important codecs (higher importance values) before more important codecs. For example, codecs
+     * important codecs before more important codecs.
-     * used for background operations should have higher importance values so they are reclaimed if
+     *
-     * required for foreground operations.
+     * <p>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.
      *
      * <p>This method is a no-op on API versions before 35.
      *
-     * <p>The default value is {@code 0}.
+     * <p>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) {
+    public Builder setCodecPriority(@IntRange(to = C.PRIORITY_MAX) @C.Priority int codecPriority) {
-      this.codecImportance = codecImportance;
+      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(