Update Composition javadoc for expanded audio support.

PiperOrigin-RevId: 550922961
SimonHung · Aug 1, 2023 · b7d7027 · b7d7027
1 parent 782f5b2
commit b7d7027
Show file tree

Hide file tree

Showing 2 changed files with 25 additions and 9 deletions.
diff --git a/libraries/transformer/src/main/java/androidx/media3/transformer/EditedMediaItem.java b/libraries/transformer/src/main/java/androidx/media3/transformer/EditedMediaItem.java
@@ -158,6 +158,8 @@ public Builder setFrameRate(@IntRange(from = 0) int frameRate) {
     /**
      * Sets the {@link Effects} to apply to the {@link MediaItem}.
      *
+     * <p>Callers should not interact with underlying {@link Effects#audioProcessors}.
+     *
      * <p>The default value is {@link Effects#EMPTY}.
      *
      * @param effects The {@link Effects} to apply.

diff --git a/libraries/transformer/src/main/java/androidx/media3/transformer/Transformer.java b/libraries/transformer/src/main/java/androidx/media3/transformer/Transformer.java
@@ -34,6 +34,9 @@
 import androidx.media3.common.MimeTypes;
 import androidx.media3.common.VideoFrameProcessor;
 import androidx.media3.common.audio.AudioProcessor;
+import androidx.media3.common.audio.AudioProcessor.AudioFormat;
+import androidx.media3.common.audio.ChannelMixingAudioProcessor;
+import androidx.media3.common.audio.SonicAudioProcessor;
 import androidx.media3.common.util.Clock;
 import androidx.media3.common.util.HandlerWrapper;
 import androidx.media3.common.util.ListenerSet;
@@ -748,23 +751,34 @@ public void removeAllListeners() {
    * EditedMediaItemSequence}, while the audio format will be determined by the {@code
    * AudioMediaItem} in the second {@code EditedMediaItemSequence}.
    *
-   * <p>This method is under implementation. Only the {@linkplain Composition compositions} meeting
-   * the below conditions are supported:
+   * <p>This method is under development. A {@link Composition} must meet the following conditions:
    *
    * <ul>
-   *   <li>There must be no overlapping track corresponding to the same track type in the output.
-   *       More precisely, the composition must either contain a single {@linkplain
-   *       EditedMediaItemSequence sequence}, or contain one audio-only sequence and one
-   *       video/image-only sequence.
-   *   <li>A sequence cannot contain both HDR and SDR video input.
-   *   <li>A sequence cannot have gaps in its video or image samples. In other words, if a sequence
-   *       contains video or image data, it must contain this type of data in the entire sequence.
+   *   <li>The composition must have at most one {@linkplain EditedMediaItemSequence sequence} with
+   *       video/image data. There are no restrictions on the number of audio sequences.
    *   <li>The {@linkplain Composition#effects composition effects} must contain no {@linkplain
    *       Effects#audioProcessors audio effects}.
    *   <li>The composition effects must either contain no {@linkplain Effects#videoEffects video
    *       effects}, or exactly one {@link Presentation}.
    * </ul>
    *
+   * <p>{@linkplain EditedMediaItemSequence Sequences} within the {@link Composition} must meet the
+   * following conditions:
+   *
+   * <ul>
+   *   <li>A sequence cannot contain both HDR and SDR video input.
+   *   <li>If an {@link EditedMediaItem} in a sequence contains data of a given {@linkplain
+   *       C.TrackType track}, so must all items in that sequence.
+   *       <ul>
+   *         <li>For audio, this condition can be removed by setting an experimental {@link
+   *             Composition.Builder#experimentalSetForceAudioTrack(boolean) flag}.
+   *       </ul>
+   *   <li>All sequences containing audio data must output audio with the same {@linkplain
+   *       AudioFormat properties}. This can be done by adding {@linkplain EditedMediaItem#effects
+   *       item specific effects}, such as {@link SonicAudioProcessor} and {@link
+   *       ChannelMixingAudioProcessor}.
+   * </ul>
+   *
    * <p>The export state is notified through the {@linkplain Builder#addListener(Listener)
    * listener}.
    *