Move muxer initialization off application thread

Problem: We are initialising muxer as soon as we start the transformation. Now the startTransformation() method can be called from main thread, but muxer creation is an I/O operation and should be not be done on main thread.

Solution: Added lazy initialisation of muxer object. The actual transformation happens on background thread so the muxer will be initialised lazily from background thread only.

Another way was to provide an initialize() method on MuxerWrapper which will explicitly initialise muxer object but with this approach the caller need to call the initialise method before calling anything else. With current implementation the renderers are calling MuxerWrapper methods on various callbacks (Not sequentially) and also we are sharing same muxer with multiple renderers so It might become confusing for the caller on when to call the initialise() method. Also there are few methods on MuxerWrapper which dont really need muxer object. So in short it might make MuxerWrapper APIs more confusing.

Validation: Verified the transformation from demo app.
PiperOrigin-RevId: 486735787
(cherry picked from commit eb35765)

Author: SheenaChhabra

libraries/transformer/src/main/java/androidx/media3/transformer/DefaultMuxer.java

@@ -20,7 +20,6 @@
 import androidx.media3.common.Format;
 import androidx.media3.common.util.UnstableApi;
 import com.google.common.collect.ImmutableList;
-import java.io.IOException;
 import java.nio.ByteBuffer;
 
 /** A default {@link Muxer} implementation. */
@@ -53,12 +52,12 @@ public Factory(long maxDelayBetweenSamplesMs) {
     }
 
     @Override
-    public Muxer create(String path) throws IOException {
+    public Muxer create(String path) throws MuxerException {
       return new DefaultMuxer(muxerFactory.create(path));
     }
 
     @Override
-    public Muxer create(ParcelFileDescriptor parcelFileDescriptor) throws IOException {
+    public Muxer create(ParcelFileDescriptor parcelFileDescriptor) throws MuxerException {
       return new DefaultMuxer(muxerFactory.create(parcelFileDescriptor));
     }
 

libraries/transformer/src/main/java/androidx/media3/transformer/FrameworkMuxer.java

@@ -63,18 +63,28 @@ public Factory(long maxDelayBetweenSamplesMs) {
     }
 
     @Override
-    public FrameworkMuxer create(String path) throws IOException {
-      MediaMuxer mediaMuxer = new MediaMuxer(path, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4);
+    public FrameworkMuxer create(String path) throws MuxerException {
+      MediaMuxer mediaMuxer;
+      try {
+        mediaMuxer = new MediaMuxer(path, MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4);
+      } catch (IOException e) {
+        throw new MuxerException("Error creating muxer", e);
+      }
       return new FrameworkMuxer(mediaMuxer, maxDelayBetweenSamplesMs);
     }
 
     @RequiresApi(26)
     @Override
-    public FrameworkMuxer create(ParcelFileDescriptor parcelFileDescriptor) throws IOException {
-      MediaMuxer mediaMuxer =
-          new MediaMuxer(
-              parcelFileDescriptor.getFileDescriptor(),
-              MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4);
+    public FrameworkMuxer create(ParcelFileDescriptor parcelFileDescriptor) throws MuxerException {
+      MediaMuxer mediaMuxer;
+      try {
+        mediaMuxer =
+            new MediaMuxer(
+                parcelFileDescriptor.getFileDescriptor(),
+                MediaMuxer.OutputFormat.MUXER_OUTPUT_MPEG_4);
+      } catch (IOException e) {
+        throw new MuxerException("Error creating muxer", e);
+      }
       return new FrameworkMuxer(mediaMuxer, maxDelayBetweenSamplesMs);
     }
 

libraries/transformer/src/main/java/androidx/media3/transformer/Muxer.java

@@ -21,7 +21,6 @@
 import androidx.media3.common.MimeTypes;
 import androidx.media3.common.util.UnstableApi;
 import com.google.common.collect.ImmutableList;
-import java.io.IOException;
 import java.nio.ByteBuffer;
 
 /**
@@ -57,9 +56,9 @@ interface Factory {
      *
      * @param path The path to the output file.
      * @throws IllegalArgumentException If the path is invalid.
-     * @throws IOException If an error occurs opening the output file for writing.
+     * @throws MuxerException If an error occurs opening the output file for writing.
      */
-    Muxer create(String path) throws IOException;
+    Muxer create(String path) throws MuxerException;
 
     /**
      * Returns a new muxer writing to a file descriptor.
@@ -69,9 +68,9 @@ interface Factory {
      *     muxer is released. It is the responsibility of the caller to close the
      *     ParcelFileDescriptor. This can be done after this method returns.
      * @throws IllegalArgumentException If the file descriptor is invalid.
-     * @throws IOException If an error occurs opening the output file descriptor for writing.
+     * @throws MuxerException If an error occurs opening the output file descriptor for writing.
      */
-    Muxer create(ParcelFileDescriptor parcelFileDescriptor) throws IOException;
+    Muxer create(ParcelFileDescriptor parcelFileDescriptor) throws MuxerException;
 
     /**
      * Returns the supported sample {@linkplain MimeTypes MIME types} for the given {@link

libraries/transformer/src/main/java/androidx/media3/transformer/MuxerWrapper.java

@@ -16,11 +16,13 @@
 
 package androidx.media3.transformer;
 
+import static androidx.media3.common.util.Assertions.checkNotNull;
 import static androidx.media3.common.util.Assertions.checkState;
 import static androidx.media3.common.util.Util.maxValue;
 import static androidx.media3.common.util.Util.minValue;
 import static java.util.concurrent.TimeUnit.MILLISECONDS;
 
+import android.os.ParcelFileDescriptor;
 import android.util.SparseIntArray;
 import android.util.SparseLongArray;
 import androidx.annotation.Nullable;
@@ -33,7 +35,9 @@
 import java.util.concurrent.Executors;
 import java.util.concurrent.ScheduledExecutorService;
 import java.util.concurrent.ScheduledFuture;
+import org.checkerframework.checker.nullness.qual.EnsuresNonNull;
 import org.checkerframework.checker.nullness.qual.MonotonicNonNull;
+import org.checkerframework.checker.nullness.qual.RequiresNonNull;
 
 /**
  * A wrapper around a media muxer.
@@ -50,7 +54,8 @@
    */
   private static final long MAX_TRACK_WRITE_AHEAD_US = Util.msToUs(500);
 
-  private final Muxer muxer;
+  @Nullable private final String outputPath;
+  @Nullable private final ParcelFileDescriptor outputParcelFileDescriptor;
   private final Muxer.Factory muxerFactory;
   private final Transformer.AsyncErrorListener asyncErrorListener;
   private final SparseIntArray trackTypeToIndex;
@@ -66,10 +71,19 @@
   private long minTrackTimeUs;
   private @MonotonicNonNull ScheduledFuture abortScheduledFuture;
   private boolean isAborted;
+  private @MonotonicNonNull Muxer muxer;
 
   public MuxerWrapper(
-      Muxer muxer, Muxer.Factory muxerFactory, Transformer.AsyncErrorListener asyncErrorListener) {
-    this.muxer = muxer;
+      @Nullable String outputPath,
+      @Nullable ParcelFileDescriptor outputParcelFileDescriptor,
+      Muxer.Factory muxerFactory,
+      Transformer.AsyncErrorListener asyncErrorListener) {
+    if (outputPath == null && outputParcelFileDescriptor == null) {
+      throw new NullPointerException("Both output path and ParcelFileDescriptor are null");
+    }
+
+    this.outputPath = outputPath;
+    this.outputParcelFileDescriptor = outputParcelFileDescriptor;
     this.muxerFactory = muxerFactory;
     this.asyncErrorListener = asyncErrorListener;
 
@@ -135,6 +149,8 @@ public void addTrackFormat(Format format) throws Muxer.MuxerException {
         trackTypeToIndex.get(trackType, /* valueIfKeyNotFound= */ C.INDEX_UNSET) == C.INDEX_UNSET,
         "There is already a track of type " + trackType);
 
+    ensureMuxerInitialized();
+
     int trackIndex = muxer.addTrack(format);
     trackTypeToIndex.put(trackType, trackIndex);
     trackTypeToSampleCount.put(trackType, 0);
@@ -181,6 +197,7 @@ public boolean writeSample(
       trackTypeToTimeUs.put(trackType, presentationTimeUs);
     }
 
+    checkNotNull(muxer);
     resetAbortTimer();
     muxer.writeSampleData(trackIndex, data, isKeyFrame, presentationTimeUs);
     previousTrackType = trackType;
@@ -213,7 +230,9 @@ public void endTrack(@C.TrackType int trackType) {
   public void release(boolean forCancellation) throws Muxer.MuxerException {
     isReady = false;
     abortScheduledExecutorService.shutdownNow();
-    muxer.release(forCancellation);
+    if (muxer != null) {
+      muxer.release(forCancellation);
+    }
   }
 
   /** Returns the number of {@link #registerTrack() registered} tracks. */
@@ -276,6 +295,7 @@ private boolean canWriteSampleOfType(int trackType) {
     return trackTimeUs - minTrackTimeUs <= MAX_TRACK_WRITE_AHEAD_US;
   }
 
+  @RequiresNonNull("muxer")
   private void resetAbortTimer() {
     long maxDelayBetweenSamplesMs = muxer.getMaxDelayBetweenSamplesMs();
     if (maxDelayBetweenSamplesMs == C.TIME_UNSET) {
@@ -302,4 +322,16 @@ private void resetAbortTimer() {
             maxDelayBetweenSamplesMs,
             MILLISECONDS);
   }
+
+  @EnsuresNonNull("muxer")
+  private void ensureMuxerInitialized() throws Muxer.MuxerException {
+    if (muxer == null) {
+      if (outputPath != null) {
+        muxer = muxerFactory.create(outputPath);
+      } else {
+        checkNotNull(outputParcelFileDescriptor);
+        muxer = muxerFactory.create(outputParcelFileDescriptor);
+      }
+    }
+  }
 }

libraries/transformer/src/main/java/androidx/media3/transformer/Transformer.java

@@ -677,7 +677,7 @@ public void removeAllListeners() {
    * @throws IllegalArgumentException If the path is invalid.
    * @throws IllegalStateException If this method is called from the wrong thread.
    * @throws IllegalStateException If a transformation is already in progress.
-   * @throws IOException If an error occurs opening the output file for writing.
+   * @throws IOException If {@link MediaItem} is not supported.
    */
   public void startTransformation(MediaItem mediaItem, String path) throws IOException {
     if (!mediaItem.clippingConfiguration.equals(MediaItem.ClippingConfiguration.UNSET)
@@ -688,7 +688,7 @@ public void startTransformation(MediaItem mediaItem, String path) throws IOExcep
     }
     this.outputPath = path;
     this.outputParcelFileDescriptor = null;
-    startTransformation(mediaItem, muxerFactory.create(path));
+    startTransformationInternal(mediaItem);
   }
 
   /**
@@ -711,24 +711,26 @@ public void startTransformation(MediaItem mediaItem, String path) throws IOExcep
    * @throws IllegalArgumentException If the file descriptor is invalid.
    * @throws IllegalStateException If this method is called from the wrong thread.
    * @throws IllegalStateException If a transformation is already in progress.
-   * @throws IOException If an error occurs opening the output file for writing.
    */
   @RequiresApi(26)
-  public void startTransformation(MediaItem mediaItem, ParcelFileDescriptor parcelFileDescriptor)
-      throws IOException {
+  public void startTransformation(MediaItem mediaItem, ParcelFileDescriptor parcelFileDescriptor) {
     this.outputParcelFileDescriptor = parcelFileDescriptor;
     this.outputPath = null;
-    startTransformation(mediaItem, muxerFactory.create(parcelFileDescriptor));
+    startTransformationInternal(mediaItem);
   }
 
-  private void startTransformation(MediaItem mediaItem, Muxer muxer) {
+  private void startTransformationInternal(MediaItem mediaItem) {
     verifyApplicationThread();
     if (player != null) {
       throw new IllegalStateException("There is already a transformation in progress.");
     }
     TransformerPlayerListener playerListener = new TransformerPlayerListener(mediaItem, looper);
     MuxerWrapper muxerWrapper =
-        new MuxerWrapper(muxer, muxerFactory, /* asyncErrorListener= */ playerListener);
+        new MuxerWrapper(
+            outputPath,
+            outputParcelFileDescriptor,
+            muxerFactory,
+            /* asyncErrorListener= */ playerListener);
     this.muxerWrapper = muxerWrapper;
     DefaultTrackSelector trackSelector = new DefaultTrackSelector(context);
     trackSelector.setParameters(

libraries/transformer/src/test/java/androidx/media3/transformer/TestMuxer.java

@@ -18,7 +18,6 @@
 import androidx.media3.common.Format;
 import androidx.media3.test.utils.DumpableFormat;
 import androidx.media3.test.utils.Dumper;
-import java.io.IOException;
 import java.nio.ByteBuffer;
 import java.util.ArrayList;
 import java.util.Arrays;
@@ -35,7 +34,7 @@ public final class TestMuxer implements Muxer, Dumper.Dumpable {
   private final List<Dumper.Dumpable> dumpables;
 
   /** Creates a new test muxer. */
-  public TestMuxer(String path, Muxer.Factory muxerFactory) throws IOException {
+  public TestMuxer(String path, Muxer.Factory muxerFactory) throws MuxerException {
     muxer = muxerFactory.create(path);
     dumpables = new ArrayList<>();
   }

libraries/transformer/src/test/java/androidx/media3/transformer/TransformerEndToEndTest.java

@@ -912,13 +912,13 @@ public TestMuxerFactory(long maxDelayBetweenSamplesMs) {
     }
 
     @Override
-    public Muxer create(String path) throws IOException {
+    public Muxer create(String path) throws Muxer.MuxerException {
       testMuxer = new TestMuxer(path, defaultMuxerFactory);
       return testMuxer;
     }
 
     @Override
-    public Muxer create(ParcelFileDescriptor parcelFileDescriptor) throws IOException {
+    public Muxer create(ParcelFileDescriptor parcelFileDescriptor) throws Muxer.MuxerException {
       testMuxer = new TestMuxer("FD:" + parcelFileDescriptor.getFd(), defaultMuxerFactory);
       return testMuxer;
     }