@UnstableApi
class Mp4Muxer : AutoCloseable

A muxer for creating an MP4 container file.

Muxer supports muxing of:

  • Video Codecs:
    • AV1
    • MPEG-4
    • H.263
    • H.264 (AVC)
    • H.265 (HEVC)
    • VP9
    • APV
  • Audio Codecs:
    • AAC
    • AMR-NB (Narrowband AMR)
    • AMR-WB (Wideband AMR)
    • Opus
    • Vorbis
  • Metadata

All the operations are performed on the caller thread.

To create an MP4 container file, the caller must:

  • Add tracks using addTrack which will return a track id.
  • Use the associated track id when writing samples for that track.
  • close the muxer when all data has been written.

Some key points:

  • Tracks can be added at any point, even after writing some samples to other tracks.
  • The caller is responsible for ensuring that samples of different track types are well interleaved by calling writeSampleData in an order that interleaves samples from different tracks.
  • When writing a file, if an error occurs and the muxer is not closed, then the output MP4 file may still have some partial data.

Summary

Nested types

A builder for Mp4Muxer instances.
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation Mp4Muxer.FileFormat

The specific MP4 file format.
@Documented
@Retention(value = RetentionPolicy.SOURCE)
@Target(value = TYPE_USE)
@IntDef(value = )
annotation Mp4Muxer.LastSampleDurationBehavior

Behavior for the duration of the last sample.

Parameters for FILE_FORMAT_MP4_WITH_AUXILIARY_TRACKS_EXTENSION.

Provides temporary cache files to be used by the muxer.

Constants
const Int

The default MP4 format.
const Int

The MP4 With Auxiliary Tracks Extension (MP4-AT) file format.
const Int

Use the end of stream sample to set the duration of the last sample.
const Int

The duration of the last sample is set to 0.
const ImmutableList<String!>!

A list of supported audio sample MIME types.
const ImmutableList<String!>!

A list of supported video sample MIME types.

Public functions
Unit

Adds metadata about the output file.
Int
addTrack(format: Format!)

Adds a track of the given media format.
Int
addTrack(sortKey: Int, format: Format!)

Adds a track of the given media format.
Unit

Closes the file.
Unit
writeSampleData(
    trackId: Int,
    byteBuffer: ByteBuffer!,
    bufferInfo: MediaCodec.BufferInfo!
)

Writes encoded sample data.

Constants

FILE_FORMAT_DEFAULT

const val FILE_FORMAT_DEFAULT = 0: Int

The default MP4 format.

FILE_FORMAT_MP4_WITH_AUXILIARY_TRACKS_EXTENSION

const val FILE_FORMAT_MP4_WITH_AUXILIARY_TRACKS_EXTENSION = 1: Int

The MP4 With Auxiliary Tracks Extension (MP4-AT) file format. In this file format all the tracks with auxiliaryTrackType set to AUXILIARY_TRACK_TYPE_ORIGINAL, AUXILIARY_TRACK_TYPE_DEPTH_LINEAR, AUXILIARY_TRACK_TYPE_DEPTH_INVERSE, or AUXILIARY_TRACK_TYPE_DEPTH_METADATA are written in the Auxiliary Tracks MP4 (axte box). The rest of the tracks are written as usual.

See the file format at https://developer.android.com/media/platform/mp4-at-file-format.

LAST_SAMPLE_DURATION_BEHAVIOR_SET_FROM_END_OF_STREAM_BUFFER_OR_DUPLICATE_PREVIOUS

const val LAST_SAMPLE_DURATION_BEHAVIOR_SET_FROM_END_OF_STREAM_BUFFER_OR_DUPLICATE_PREVIOUS = 1: Int

Use the end of stream sample to set the duration of the last sample.

After writing all the samples for a track, the app must write an empty sample with flag BUFFER_FLAG_END_OF_STREAM. The timestamp of this sample should be equal to the desired track duration.

Once a sample with flag BUFFER_FLAG_END_OF_STREAM is written, no more samples can be written for that track.

If no explicit BUFFER_FLAG_END_OF_STREAM sample is passed, then the duration of the last sample will be same as that of the sample before that.

LAST_SAMPLE_DURATION_BEHAVIOR_SET_TO_ZERO

const val LAST_SAMPLE_DURATION_BEHAVIOR_SET_TO_ZERO = 0: Int

The duration of the last sample is set to 0.

SUPPORTED_AUDIO_SAMPLE_MIME_TYPES

const val SUPPORTED_AUDIO_SAMPLE_MIME_TYPES: ImmutableList<String!>!

A list of supported audio sample MIME types.

SUPPORTED_VIDEO_SAMPLE_MIME_TYPES

const val SUPPORTED_VIDEO_SAMPLE_MIME_TYPES: ImmutableList<String!>!

A list of supported video sample MIME types.

Public functions

addMetadataEntry

fun addMetadataEntry(metadataEntry: Metadata.Entry!): Unit

Adds metadata about the output file.

List of supported metadata entries:

Parameters
metadataEntry: Metadata.Entry!

The metadata. An is thrown if the metadata is not supported.

addTrack

fun addTrack(format: Format!): Int

Adds a track of the given media format.

Tracks can be added at any point before the muxer is closed, even after writing samples to other tracks.

The order of tracks remains same in which they are added.

Parameters
format: Format!

The Format for the track.
Returns
Int

A unique track id. The track id is non-negative. It should be used in writeSampleData.
Throws
androidx.media3.muxer.MuxerException

If an error occurs while adding track.

addTrack

fun addTrack(sortKey: Int, format: Format!): Int

Adds a track of the given media format.

Tracks can be added at any point before the muxer is closed, even after writing samples to other tracks.

The final order of tracks is determined by the provided sort key. Tracks with a lower sort key will be written before tracks with a higher sort key. Ordering between tracks with the same sort key is not specified.

Parameters
sortKey: Int

The key used for sorting the track list.
format: Format!

The Format for the track.
Returns
Int

A unique track id. The track id is non-negative. It should be used in writeSampleData.
Throws
androidx.media3.muxer.MuxerException

If an error occurs while adding track.

close

fun close(): Unit

Closes the file.

The muxer cannot be used anymore once this method returns.

Throws
androidx.media3.muxer.MuxerException

If the muxer fails to finish writing the output.

writeSampleData

fun writeSampleData(
    trackId: Int,
    byteBuffer: ByteBuffer!,
    bufferInfo: MediaCodec.BufferInfo!
): Unit

Writes encoded sample data.

Parameters
trackId: Int

The track id for which this sample is being written.
byteBuffer: ByteBuffer!

The encoded sample. The muxer takes ownership of the buffer if sample copying is disabled. Otherwise, the position of the buffer is updated but the caller retains ownership.
bufferInfo: MediaCodec.BufferInfo!

The BufferInfo related to this sample.
Throws
androidx.media3.muxer.MuxerException

If an error occurs while writing data to the output file.