Muxer.java
/*
* Copyright 2021 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.media3.transformer;
import android.os.ParcelFileDescriptor;
import androidx.annotation.Nullable;
import androidx.media3.common.C;
import androidx.media3.common.Format;
import androidx.media3.common.MimeTypes;
import com.google.common.collect.ImmutableList;
import java.io.IOException;
import java.nio.ByteBuffer;
/**
* Abstracts media muxing operations.
*
* <p>Query whether {@linkplain Factory#supportsOutputMimeType(String) container MIME type} and
* {@linkplain Factory#supportsSampleMimeType(String, String) sample MIME types} are supported and
* {@linkplain #addTrack(Format) add all tracks}, then {@linkplain #writeSampleData(int, ByteBuffer,
* boolean, long) write sample data} to mux samples. Once any sample data has been written, it is
* not possible to add tracks. After writing all sample data, {@linkplain #release(boolean) release}
* the instance to finish writing to the output and return any resources to the system.
*/
/* package */ interface Muxer {
/** Thrown when a muxing failure occurs. */
/* package */ final class MuxerException extends Exception {
/**
* Creates an instance.
*
* @param message See {@link #getMessage()}.
* @param cause See {@link #getCause()}.
*/
public MuxerException(String message, Throwable cause) {
super(message, cause);
}
}
/** Factory for muxers. */
interface Factory {
/**
* Returns a new muxer writing to a file.
*
* @param path The path to the output file.
* @param outputMimeType The container {@linkplain MimeTypes MIME type} of the output file.
* @throws IllegalArgumentException If the path is invalid or the MIME type is not supported.
* @throws IOException If an error occurs opening the output file for writing.
*/
Muxer create(String path, String outputMimeType) throws IOException;
/**
* Returns a new muxer writing to a file descriptor.
*
* @param parcelFileDescriptor A readable and writable {@link ParcelFileDescriptor} of the
* output. The file referenced by this ParcelFileDescriptor should not be used before the
* muxer is released. It is the responsibility of the caller to close the
* ParcelFileDescriptor. This can be done after this method returns.
* @param outputMimeType The {@linkplain MimeTypes MIME type} of the output.
* @throws IllegalArgumentException If the file descriptor is invalid or the MIME type is not
* supported.
* @throws IOException If an error occurs opening the output file descriptor for writing.
*/
Muxer create(ParcelFileDescriptor parcelFileDescriptor, String outputMimeType)
throws IOException;
/**
* Returns whether the {@linkplain MimeTypes MIME type} provided is a supported output format.
*/
boolean supportsOutputMimeType(String mimeType);
/**
* Returns whether the sample {@linkplain MimeTypes MIME type} is supported with the given
* container {@linkplain MimeTypes MIME type}.
*/
boolean supportsSampleMimeType(@Nullable String sampleMimeType, String containerMimeType);
/**
* Returns the supported sample {@linkplain MimeTypes MIME types} for the given {@link
* C.TrackType} and container {@linkplain MimeTypes MIME type}.
*/
ImmutableList<String> getSupportedSampleMimeTypes(
@C.TrackType int trackType, String containerMimeType);
}
/**
* Adds a track with the specified format, and returns its index (to be passed in subsequent calls
* to {@link #writeSampleData(int, ByteBuffer, boolean, long)}).
*
* @param format The {@link Format} of the track.
* @throws MuxerException If the muxer encounters a problem while adding the track.
*/
int addTrack(Format format) throws MuxerException;
/**
* Writes the specified sample.
*
* @param trackIndex The index of the track, previously returned by {@link #addTrack(Format)}.
* @param data Buffer containing the sample data to write to the container.
* @param isKeyFrame Whether the sample is a key frame.
* @param presentationTimeUs The presentation time of the sample in microseconds.
* @throws MuxerException If the muxer fails to write the sample.
*/
void writeSampleData(int trackIndex, ByteBuffer data, boolean isKeyFrame, long presentationTimeUs)
throws MuxerException;
/**
* Releases any resources associated with muxing.
*
* @param forCancellation Whether the reason for releasing the resources is the transformation
* cancellation.
* @throws MuxerException If the muxer fails to stop or release resources and {@code
* forCancellation} is false.
*/
void release(boolean forCancellation) throws MuxerException;
}