Stabilize AudioOutput(Provider)

And some elements of AudioTrackAudioOutputProvider needed to instantiate,
customize and wrap the default instance.

Also stabilize the Forwarding classes for easier customizability.

PiperOrigin-RevId: 828009918

Author: tonihei

api.txt

@@ -173,7 +173,6 @@ private C() {}
    * {@link #ENCODING_DTS}, {@link #ENCODING_DTS_HD}, {@link #ENCODING_DOLBY_TRUEHD} or {@link
    * #ENCODING_OPUS}.
    */
-  @UnstableApi
   @Documented
   @Retention(RetentionPolicy.SOURCE)
   @Target(TYPE_USE)
@@ -233,79 +232,79 @@ private C() {}
   public @interface PcmEncoding {}
 
   /** See {@link AudioFormat#ENCODING_INVALID}. */
-  @UnstableApi public static final int ENCODING_INVALID = AudioFormat.ENCODING_INVALID;
+  public static final int ENCODING_INVALID = AudioFormat.ENCODING_INVALID;
 
   /** See {@link AudioFormat#ENCODING_PCM_8BIT}. */
-  @UnstableApi public static final int ENCODING_PCM_8BIT = AudioFormat.ENCODING_PCM_8BIT;
+  public static final int ENCODING_PCM_8BIT = AudioFormat.ENCODING_PCM_8BIT;
 
   /** See {@link AudioFormat#ENCODING_PCM_16BIT}. */
-  @UnstableApi public static final int ENCODING_PCM_16BIT = AudioFormat.ENCODING_PCM_16BIT;
+  public static final int ENCODING_PCM_16BIT = AudioFormat.ENCODING_PCM_16BIT;
 
   /** Like {@link #ENCODING_PCM_16BIT}, but with the bytes in big endian order. */
   @UnstableApi public static final int ENCODING_PCM_16BIT_BIG_ENDIAN = 0x10000000;
 
   /** PCM encoding with 24 bits per sample. */
-  @UnstableApi public static final int ENCODING_PCM_24BIT = AudioFormat.ENCODING_PCM_24BIT_PACKED;
+  public static final int ENCODING_PCM_24BIT = AudioFormat.ENCODING_PCM_24BIT_PACKED;
 
   /** Like {@link #ENCODING_PCM_24BIT} but with the bytes in big endian order. */
   @UnstableApi public static final int ENCODING_PCM_24BIT_BIG_ENDIAN = 0x50000000;
 
   /** PCM encoding with 32 bits per sample. */
-  @UnstableApi public static final int ENCODING_PCM_32BIT = AudioFormat.ENCODING_PCM_32BIT;
+  public static final int ENCODING_PCM_32BIT = AudioFormat.ENCODING_PCM_32BIT;
 
   /** Like {@link #ENCODING_PCM_32BIT} but with the bytes in big endian order. */
   @UnstableApi public static final int ENCODING_PCM_32BIT_BIG_ENDIAN = 0x60000000;
 
   /** See {@link AudioFormat#ENCODING_PCM_FLOAT}. */
-  @UnstableApi public static final int ENCODING_PCM_FLOAT = AudioFormat.ENCODING_PCM_FLOAT;
+  public static final int ENCODING_PCM_FLOAT = AudioFormat.ENCODING_PCM_FLOAT;
 
   /** See {@link AudioFormat#ENCODING_MP3}. */
-  @UnstableApi public static final int ENCODING_MP3 = AudioFormat.ENCODING_MP3;
+  public static final int ENCODING_MP3 = AudioFormat.ENCODING_MP3;
 
   /** See {@link AudioFormat#ENCODING_AAC_LC}. */
-  @UnstableApi public static final int ENCODING_AAC_LC = AudioFormat.ENCODING_AAC_LC;
+  public static final int ENCODING_AAC_LC = AudioFormat.ENCODING_AAC_LC;
 
   /** See {@link AudioFormat#ENCODING_AAC_HE_V1}. */
-  @UnstableApi public static final int ENCODING_AAC_HE_V1 = AudioFormat.ENCODING_AAC_HE_V1;
+  public static final int ENCODING_AAC_HE_V1 = AudioFormat.ENCODING_AAC_HE_V1;
 
   /** See {@link AudioFormat#ENCODING_AAC_HE_V2}. */
-  @UnstableApi public static final int ENCODING_AAC_HE_V2 = AudioFormat.ENCODING_AAC_HE_V2;
+  public static final int ENCODING_AAC_HE_V2 = AudioFormat.ENCODING_AAC_HE_V2;
 
   /** See {@link AudioFormat#ENCODING_AAC_XHE}. */
-  @UnstableApi public static final int ENCODING_AAC_XHE = AudioFormat.ENCODING_AAC_XHE;
+  public static final int ENCODING_AAC_XHE = AudioFormat.ENCODING_AAC_XHE;
 
   /** See {@link AudioFormat#ENCODING_AAC_ELD}. */
-  @UnstableApi public static final int ENCODING_AAC_ELD = AudioFormat.ENCODING_AAC_ELD;
+  public static final int ENCODING_AAC_ELD = AudioFormat.ENCODING_AAC_ELD;
 
   /** AAC Error Resilient Bit-Sliced Arithmetic Coding. */
   @UnstableApi public static final int ENCODING_AAC_ER_BSAC = 0x40000000;
 
   /** See {@link AudioFormat#ENCODING_AC3}. */
-  @UnstableApi public static final int ENCODING_AC3 = AudioFormat.ENCODING_AC3;
+  public static final int ENCODING_AC3 = AudioFormat.ENCODING_AC3;
 
   /** See {@link AudioFormat#ENCODING_E_AC3}. */
-  @UnstableApi public static final int ENCODING_E_AC3 = AudioFormat.ENCODING_E_AC3;
+  public static final int ENCODING_E_AC3 = AudioFormat.ENCODING_E_AC3;
 
   /** See {@link AudioFormat#ENCODING_E_AC3_JOC}. */
-  @UnstableApi public static final int ENCODING_E_AC3_JOC = AudioFormat.ENCODING_E_AC3_JOC;
+  public static final int ENCODING_E_AC3_JOC = AudioFormat.ENCODING_E_AC3_JOC;
 
   /** See {@link AudioFormat#ENCODING_AC4}. */
-  @UnstableApi public static final int ENCODING_AC4 = AudioFormat.ENCODING_AC4;
+  public static final int ENCODING_AC4 = AudioFormat.ENCODING_AC4;
 
   /** See {@link AudioFormat#ENCODING_DTS}. */
-  @UnstableApi public static final int ENCODING_DTS = AudioFormat.ENCODING_DTS;
+  public static final int ENCODING_DTS = AudioFormat.ENCODING_DTS;
 
   /** See {@link AudioFormat#ENCODING_DTS_HD}. */
-  @UnstableApi public static final int ENCODING_DTS_HD = AudioFormat.ENCODING_DTS_HD;
+  public static final int ENCODING_DTS_HD = AudioFormat.ENCODING_DTS_HD;
 
   /** See {@link AudioFormat#ENCODING_DTS_UHD_P2}. */
-  @UnstableApi public static final int ENCODING_DTS_UHD_P2 = AudioFormat.ENCODING_DTS_UHD_P2;
+  public static final int ENCODING_DTS_UHD_P2 = AudioFormat.ENCODING_DTS_UHD_P2;
 
   /** See {@link AudioFormat#ENCODING_DOLBY_TRUEHD}. */
-  @UnstableApi public static final int ENCODING_DOLBY_TRUEHD = AudioFormat.ENCODING_DOLBY_TRUEHD;
+  public static final int ENCODING_DOLBY_TRUEHD = AudioFormat.ENCODING_DOLBY_TRUEHD;
 
   /** See {@link AudioFormat#ENCODING_OPUS}. */
-  @UnstableApi public static final int ENCODING_OPUS = AudioFormat.ENCODING_OPUS;
+  public static final int ENCODING_OPUS = AudioFormat.ENCODING_OPUS;
 
   /**
    * Represents the behavior affecting whether spatialization will be used. One of {@link

libraries/common/src/main/java/androidx/media3/common/C.java

@@ -25,7 +25,6 @@
 import java.nio.ByteBuffer;
 
 /** An interface to wrap an object that can play audio, like an {@link AudioTrack}. */
-@UnstableApi
 public interface AudioOutput {
 
   /** Listener for {@link AudioOutput} events. */
@@ -168,14 +167,15 @@ boolean write(ByteBuffer buffer, int encodedAccessUnitCount, long presentationTi
   void setOffloadEndOfStream();
 
   /** Sets the {@link PlayerId} on the audio output. */
-  void setPlayerId(PlayerId playerId);
+  @UnstableApi
+  default void setPlayerId(PlayerId playerId) {}
 
   /** Attaches an auxiliary effect to the output. */
   void attachAuxEffect(int effectId);
 
   /** Sets the send level for the auxiliary effect. */
   void setAuxEffectSendLevel(float level);
 
-  /** Sets the preferred audio device for routing. */
+  /** Sets the preferred audio device for routing, or null for no preference. */
   void setPreferredDevice(@Nullable AudioDeviceInfo preferredDevice);
 }

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/audio/AudioOutput.java

@@ -15,6 +15,7 @@
  */
 package androidx.media3.exoplayer.audio;
 
+import static androidx.core.util.Preconditions.checkNotNull;
 import static java.lang.annotation.ElementType.TYPE_USE;
 
 import android.media.AudioDeviceInfo;
@@ -33,7 +34,6 @@
 import java.util.Objects;
 
 /** A provider for {@link AudioOutput} instances and for querying their support. */
-@UnstableApi
 public interface AudioOutputProvider {
 
   /** Listener for {@link AudioOutputProvider} events. */
@@ -54,7 +54,7 @@ final class FormatConfig {
     /** The {@link AudioAttributes} to use for playback. */
     public final AudioAttributes audioAttributes;
 
-    /** The preferred {@link AudioDeviceInfo} for audio output. */
+    /** The preferred {@link AudioDeviceInfo} for audio output, or null for no preference. */
     @Nullable public final AudioDeviceInfo preferredDevice;
 
     /** Sets whether to enable high resolution PCM output with more than 16 bits. */
@@ -168,7 +168,7 @@ public Builder setAudioAttributes(AudioAttributes audioAttributes) {
         return this;
       }
 
-      /** Sets the preferred {@link AudioDeviceInfo}. */
+      /** Sets the preferred {@link AudioDeviceInfo}, or null for no preference. */
       @CanIgnoreReturnValue
       public Builder setPreferredDevice(@Nullable AudioDeviceInfo preferredDevice) {
         this.preferredDevice = preferredDevice;
@@ -274,10 +274,10 @@ final class OutputConfig {
     public final int sampleRate;
 
     /**
-     * The channel configuration of the output. See {@code AudioFormat.CHANNEL_OUT_XXX} constants
-     * like {@link android.media.AudioFormat#CHANNEL_OUT_5POINT1}.
+     * The channel mask of the output. See {@code AudioFormat.CHANNEL_OUT_XXX} constants like {@link
+     * android.media.AudioFormat#CHANNEL_OUT_5POINT1}.
      */
-    public final int channelConfig;
+    public final int channelMask;
 
     /** Whether tunneling is enabled for this output. */
     public final boolean isTunneling;
@@ -309,7 +309,7 @@ final class OutputConfig {
     private OutputConfig(Builder builder) {
       this.encoding = builder.encoding;
       this.sampleRate = builder.sampleRate;
-      this.channelConfig = builder.channelConfig;
+      this.channelMask = builder.channelMask;
       this.isTunneling = builder.isTunneling;
       this.isOffload = builder.isOffload;
       this.bufferSize = builder.bufferSize;
@@ -336,7 +336,7 @@ public boolean equals(@Nullable Object o) {
       OutputConfig that = (OutputConfig) o;
       return encoding == that.encoding
           && sampleRate == that.sampleRate
-          && channelConfig == that.channelConfig
+          && channelMask == that.channelMask
           && isTunneling == that.isTunneling
           && isOffload == that.isOffload
           && bufferSize == that.bufferSize
@@ -352,7 +352,7 @@ public int hashCode() {
       return Objects.hash(
           encoding,
           sampleRate,
-          channelConfig,
+          channelMask,
           isTunneling,
           isOffload,
           bufferSize,
@@ -367,7 +367,7 @@ public int hashCode() {
     public static final class Builder {
       private @C.Encoding int encoding;
       private int sampleRate;
-      private int channelConfig;
+      private int channelMask;
       private boolean isTunneling;
       private boolean isOffload;
       private int bufferSize;
@@ -387,7 +387,7 @@ public Builder() {
       private Builder(OutputConfig config) {
         this.encoding = config.encoding;
         this.sampleRate = config.sampleRate;
-        this.channelConfig = config.channelConfig;
+        this.channelMask = config.channelMask;
         this.isTunneling = config.isTunneling;
         this.isOffload = config.isOffload;
         this.bufferSize = config.bufferSize;
@@ -412,10 +412,15 @@ public Builder setSampleRate(int sampleRate) {
         return this;
       }
 
-      /** Sets the channel configuration of the output. */
+      /**
+       * Sets the channel mask of the output.
+       *
+       * <p>See {@code AudioFormat.CHANNEL_OUT_XXX} constants like {@link
+       * android.media.AudioFormat#CHANNEL_OUT_5POINT1}.
+       */
       @CanIgnoreReturnValue
-      public Builder setChannelConfig(int channelConfig) {
-        this.channelConfig = channelConfig;
+      public Builder setChannelMask(int channelMask) {
+        this.channelMask = channelMask;
         return this;
       }
 
@@ -600,15 +605,20 @@ final class ConfigurationException extends Exception {
 
     /** Creates a new configuration exception with the specified {@code message}. */
     public ConfigurationException(String message) {
-      super(message);
+      super(checkNotNull(message));
     }
   }
 
   /** Thrown when a failure occurs initializing the output. */
   final class InitializationException extends Exception {
 
+    /** Creates a new initialization exception with no specified cause. */
+    public InitializationException() {
+      super();
+    }
+
     /** Creates a new initialization exception with the specified {@code cause}. */
-    public InitializationException(@Nullable Throwable cause) {
+    public InitializationException(Throwable cause) {
       super(cause);
     }
   }
@@ -675,7 +685,8 @@ public InitializationException(@Nullable Throwable cause) {
   void removeListener(Listener listener);
 
   /** Sets the {@link Clock} to use in the provider. */
-  void setClock(Clock clock);
+  @UnstableApi
+  default void setClock(Clock clock) {}
 
   /** Releases resources held by the provider. */
   void release();

libraries/exoplayer/src/main/java/androidx/media3/exoplayer/audio/AudioOutputProvider.java

@@ -44,7 +44,6 @@
 import java.util.concurrent.ScheduledExecutorService;
 
 /** A default implementation of {@link AudioOutput} that wraps an {@link AudioTrack}. */
-@UnstableApi
 public final class AudioTrackAudioOutput implements AudioOutput {
 
   /** Listener for potential capability change events. */
@@ -128,7 +127,7 @@ public AudioTrackAudioOutput(
 
     isOutputPcm = Util.isEncodingLinearPcm(config.encoding);
     if (isOutputPcm) {
-      int channelCount = Integer.bitCount(config.channelConfig);
+      int channelCount = Integer.bitCount(config.channelMask);
       pcmFrameSize = Util.getPcmFrameSize(config.encoding, channelCount);
     } else {
       pcmFrameSize = C.LENGTH_UNSET;
@@ -340,6 +339,7 @@ public void setOffloadEndOfStream() {
     audioTrackPositionTracker.expectRawPlaybackHeadReset();
   }
 
+  @UnstableApi
   @Override
   public void setPlayerId(PlayerId playerId) {
     if (SDK_INT < 31) {
@@ -553,6 +553,7 @@ public void onPositionAdvancing(long playoutStartSystemTimeMs) {
    * Thrown when the audio track has provided a spurious timestamp, if {@link
    * AudioTrackAudioOutputProvider#failOnSpuriousAudioTimestamp} is set.
    */
+  @UnstableApi
   public static final class InvalidAudioTrackTimestampException extends RuntimeException {
 
     /**