Add API to reserve free space after ftyp

PiperOrigin-RevId: 761536934

Author: SheenaChhabra

libraries/muxer/src/main/java/androidx/media3/muxer/Mp4Muxer.java

@@ -208,6 +208,7 @@ public static final class Builder {
     private boolean attemptStreamableOutputEnabled;
     private @FileFormat int outputFileFormat;
     @Nullable private Mp4AtFileParameters mp4AtFileParameters;
+    private int freeSpaceAfterFtypInBytes;
 
     /**
      * Creates a {@link Builder} instance with default values.
@@ -326,6 +327,27 @@ public Mp4Muxer.Builder setMp4AtFileParameters(Mp4AtFileParameters mp4AtFilePara
       return this;
     }
 
+    /**
+     * Sets the amount of free space (in bytes) to be reserved immediately after the {@code ftyp}
+     * box (File Type box) in the MP4 file.
+     *
+     * <p>The {@code moov} box (Movie Box) is written in the reserved space if {@link
+     * #setAttemptStreamableOutputEnabled(boolean)} is set to {@code true}, and the size of the
+     * {@code moov} box is not greater than {@code bytes}. Otherwise, a {@code free} box of the
+     * requested size is written.
+     *
+     * <p>By default 400_000 bytes are reserved if {@link
+     * #setAttemptStreamableOutputEnabled(boolean)} is set to {@code true}.
+     *
+     * <p>This method is experimental and will be renamed or removed in a future release.
+     */
+    @CanIgnoreReturnValue
+    public Mp4Muxer.Builder experimentalSetFreeSpaceAfterFileTypeBox(int bytes) {
+      checkArgument(bytes >= 0);
+      this.freeSpaceAfterFtypInBytes = bytes;
+      return this;
+    }
+
     /** Builds an {@link Mp4Muxer} instance. */
     public Mp4Muxer build() {
       checkArgument(
@@ -341,7 +363,8 @@ public Mp4Muxer build() {
           sampleBatchingEnabled,
           attemptStreamableOutputEnabled,
           outputFileFormat,
-          mp4AtFileParameters);
+          mp4AtFileParameters,
+          freeSpaceAfterFtypInBytes);
     }
   }
 
@@ -379,6 +402,7 @@ public Mp4Muxer build() {
   private final boolean sampleCopyEnabled;
   private final boolean sampleBatchingEnabled;
   private final boolean attemptStreamableOutputEnabled;
+  private final int freeSpaceAfterFtypInBytes;
   private final @FileFormat int outputFileFormat;
   @Nullable private final Mp4AtFileParameters mp4AtFileParameters;
   private final MetadataCollector metadataCollector;
@@ -401,7 +425,8 @@ private Mp4Muxer(
       boolean sampleBatchingEnabled,
       boolean attemptStreamableOutputEnabled,
       @FileFormat int outputFileFormat,
-      @Nullable Mp4AtFileParameters mp4AtFileParameters) {
+      @Nullable Mp4AtFileParameters mp4AtFileParameters,
+      int freeSpaceAfterFtypInBytes) {
     this.outputStream = outputStream;
     outputChannel = outputStream.getChannel();
     this.lastSampleDurationBehavior = lastFrameDurationBehavior;
@@ -411,6 +436,7 @@ private Mp4Muxer(
     this.attemptStreamableOutputEnabled = attemptStreamableOutputEnabled;
     this.outputFileFormat = outputFileFormat;
     this.mp4AtFileParameters = mp4AtFileParameters;
+    this.freeSpaceAfterFtypInBytes = freeSpaceAfterFtypInBytes;
     metadataCollector = new MetadataCollector();
     mp4Writer =
         new Mp4Writer(
@@ -420,7 +446,8 @@ private Mp4Muxer(
             lastFrameDurationBehavior,
             sampleCopyEnabled,
             sampleBatchingEnabled,
-            attemptStreamableOutputEnabled);
+            attemptStreamableOutputEnabled,
+            freeSpaceAfterFtypInBytes);
     trackIdToTrack = new ArrayList<>();
     auxiliaryTracks = new ArrayList<>();
   }
@@ -588,7 +615,8 @@ private void ensureSetupForAuxiliaryTracks() throws FileNotFoundException {
               lastSampleDurationBehavior,
               sampleCopyEnabled,
               sampleBatchingEnabled,
-              attemptStreamableOutputEnabled);
+              attemptStreamableOutputEnabled,
+              freeSpaceAfterFtypInBytes);
     }
   }
 

libraries/muxer/src/main/java/androidx/media3/muxer/Mp4Writer.java

@@ -60,6 +60,7 @@
   private final List<Track> auxiliaryTracks;
   private final AtomicBoolean hasWrittenSamples;
   private final LinearByteBufferAllocator linearByteBufferAllocator;
+  private final int freeSpaceAfterFtypInBytes;
 
   // Stores location of the space reserved for the moov box at the beginning of the file (after ftyp
   // box)
@@ -88,6 +89,7 @@
    * @param sampleCopyEnabled Whether sample copying is enabled.
    * @param sampleBatchingEnabled Whether sample batching is enabled.
    * @param attemptStreamableOutputEnabled Whether to attempt to write a streamable output.
+   * @param freeSpaceAfterFtypInBytes Free space to be reserved (in bytes) after the ftyp box.
    */
   public Mp4Writer(
       FileChannel fileChannel,
@@ -96,13 +98,18 @@ public Mp4Writer(
       @Mp4Muxer.LastSampleDurationBehavior int lastSampleDurationBehavior,
       boolean sampleCopyEnabled,
       boolean sampleBatchingEnabled,
-      boolean attemptStreamableOutputEnabled) {
+      boolean attemptStreamableOutputEnabled,
+      int freeSpaceAfterFtypInBytes) {
     this.outputFileChannel = fileChannel;
     this.metadataCollector = metadataCollector;
     this.annexBToAvccConverter = annexBToAvccConverter;
     this.lastSampleDurationBehavior = lastSampleDurationBehavior;
     this.sampleCopyEnabled = sampleCopyEnabled;
     this.sampleBatchingEnabled = sampleBatchingEnabled;
+    this.freeSpaceAfterFtypInBytes =
+        freeSpaceAfterFtypInBytes > 0
+            ? freeSpaceAfterFtypInBytes
+            : (attemptStreamableOutputEnabled ? DEFAULT_MOOV_BOX_SIZE_BYTES : 0);
     tracks = new ArrayList<>();
     auxiliaryTracks = new ArrayList<>();
     hasWrittenSamples = new AtomicBoolean(false);
@@ -308,11 +315,10 @@ private void writeHeader() throws IOException {
     outputFileChannel.position(0L);
     outputFileChannel.write(Boxes.ftyp());
 
-    if (canWriteMoovAtStart) {
-      // Reserve some space for moov box by adding a free box.
+    if (freeSpaceAfterFtypInBytes > 0) {
       reservedMoovSpaceStart = outputFileChannel.position();
       outputFileChannel.write(
-          BoxUtils.wrapIntoBox(FREE_BOX_TYPE, ByteBuffer.allocate(DEFAULT_MOOV_BOX_SIZE_BYTES)));
+          BoxUtils.wrapIntoBox(FREE_BOX_TYPE, ByteBuffer.allocate(freeSpaceAfterFtypInBytes)));
       reservedMoovSpaceEnd = outputFileChannel.position();
     }
 

libraries/muxer/src/test/java/androidx/media3/muxer/Mp4MuxerEndToEndTest.java

@@ -926,6 +926,38 @@ public void createMp4File_withSampleBatchingAndAttemptStreamableOutputDisabled_m
             "sample_batching_and_attempt_streamable_output_disabled_" + H265_HDR10_MP4));
   }
 
+  @Test
+  public void
+      writeMp4File_withSomeFreeSpaceAfterFileTypeBoxAndAttemptStreamableOutputDisabled_reservesExpectedFreeSpace()
+          throws Exception {
+    String outputFilePath = temporaryFolder.newFile().getPath();
+    Mp4Muxer muxer =
+        new Mp4Muxer.Builder(new FileOutputStream(outputFilePath))
+            .experimentalSetFreeSpaceAfterFileTypeBox(500)
+            .setAttemptStreamableOutputEnabled(false)
+            .build();
+    Pair<ByteBuffer, BufferInfo> sampleAndSampleInfo =
+        getFakeSampleAndSampleInfo(/* presentationTimeUs= */ 0L);
+
+    try {
+      muxer.addMetadataEntry(
+          new Mp4TimestampData(
+              /* creationTimestampSeconds= */ 1_000_000L,
+              /* modificationTimestampSeconds= */ 5_000_000L));
+      int trackId = muxer.addTrack(FAKE_VIDEO_FORMAT);
+      muxer.writeSampleData(trackId, sampleAndSampleInfo.first, sampleAndSampleInfo.second);
+    } finally {
+      muxer.close();
+    }
+
+    DumpableMp4Box dumpableBox =
+        new DumpableMp4Box(ByteBuffer.wrap(TestUtil.getByteArrayFromFilePath(outputFilePath)));
+    DumpFileAsserts.assertOutput(
+        context,
+        dumpableBox,
+        MuxerTestUtil.getExpectedDumpFilePath("mp4_with_some_free_space_after_ftyp.mp4"));
+  }
+
   private static void writeFakeSamples(Mp4Muxer muxer, int trackId, int sampleCount)
       throws MuxerException {
     for (int i = 0; i < sampleCount; i++) {

libraries/test_data/src/test/assets/muxerdumps/mp4_with_some_free_space_after_ftyp.mp4.dump

@@ -0,0 +1,35 @@
+ftyp (28 bytes):
+  Data = length 20, hash EF896440
+free (508 bytes):
+  Data = length 500, hash 96A2F981
+mdat (72 bytes):
+  Data = length 56, hash DB5662FB
+moov (658 bytes):
+  mvhd (108 bytes):
+    Data = length 100, hash 2613A5C
+  trak (542 bytes):
+    tkhd (92 bytes):
+      Data = length 84, hash 3D79758F
+    mdia (442 bytes):
+      mdhd (32 bytes):
+        Data = length 24, hash 41542D81
+      hdlr (44 bytes):
+        Data = length 36, hash A0852FF2
+      minf (358 bytes):
+        vmhd (20 bytes):
+          Data = length 12, hash EE830681
+        dinf (36 bytes):
+          Data = length 28, hash D535436B
+        stbl (294 bytes):
+          stsd (166 bytes):
+            Data = length 158, hash 11532063
+          stts (24 bytes):
+            Data = length 16, hash E4FC6483
+          stsz (24 bytes):
+            Data = length 16, hash 50B7F5BA
+          stsc (28 bytes):
+            Data = length 20, hash 8F6E8285
+          co64 (24 bytes):
+            Data = length 16, hash E4EE4D68
+          stss (20 bytes):
+            Data = length 12, hash EE911E03