@UnstableApi
public interface Codec

Known direct subclasses
DefaultCodec

A default Codec implementation that uses MediaCodec.

Provides a layer of abstraction for interacting with decoders and encoders.

DecoderInputBuffers are used as both decoders' and encoders' input buffers.

Summary

Nested types
public interface Codec.DecoderFactory

A factory for decoder instances.
public interface Codec.EncoderFactory

A factory for encoder instances.

Public methods
abstract Format

Returns the Format used for configuring the Codec.
abstract Surface

Returns the input Surface of an underlying video encoder.
default int

Returns the maximum number of frames that may be pending in the output Codec at a time, or 5 as a default value.
abstract String

Returns the name of the underlying codec.
abstract @Nullable ByteBuffer

Returns the current output ByteBuffer, or null if unavailable.
abstract @Nullable MediaCodec.BufferInfo

Returns the BufferInfo associated with the current output buffer, or null if there is no output buffer available.
abstract @Nullable Format

Returns the current output format, or null if unavailable.
abstract boolean

Returns whether the Codec's output stream has ended, and no more data can be dequeued.
abstract boolean

Dequeues a writable input buffer, if available.
abstract void

Queues an input buffer to the Codec.
abstract void

Releases the Codec.
abstract void
releaseOutputBuffer(boolean render)

Releases the current output buffer.
abstract void
releaseOutputBuffer(long renderPresentationTimeUs)

Renders and releases the current output buffer.
abstract void

Signals end-of-stream on input to a video encoder.

Public methods

getConfigurationFormat

abstract Format getConfigurationFormat()

Returns the Format used for configuring the Codec.

The configuration Format is the input Format used by the or output Format used by the EncoderFactory for selecting and configuring the underlying decoder or encoder.

getInputSurface

abstract Surface getInputSurface()

Returns the input Surface of an underlying video encoder.

This method must only be called on video encoders because audio/video decoders and audio encoders don't use a Surface as input.

getMaxPendingFrameCount

default int getMaxPendingFrameCount()

Returns the maximum number of frames that may be pending in the output Codec at a time, or 5 as a default value.

getName

abstract String getName()

Returns the name of the underlying codec.

getOutputBuffer

abstract @Nullable ByteBuffer getOutputBuffer()

Returns the current output ByteBuffer, or null if unavailable.

This method must not be called on video decoders because they must output to a .

Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

getOutputBufferInfo

abstract @Nullable MediaCodec.BufferInfo getOutputBufferInfo()

Returns the BufferInfo associated with the current output buffer, or null if there is no output buffer available.

This method returns null if and only if getOutputBuffer returns null.

Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

getOutputFormat

abstract @Nullable Format getOutputFormat()

Returns the current output format, or null if unavailable.

Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

isEnded

abstract boolean isEnded()

Returns whether the Codec's output stream has ended, and no more data can be dequeued.

maybeDequeueInputBuffer

abstract boolean maybeDequeueInputBuffer(DecoderInputBuffer inputBuffer)

Dequeues a writable input buffer, if available.

This method must not be called from video encoders because they must use a Surface to receive input.

Parameters
DecoderInputBuffer inputBuffer

The buffer where the dequeued buffer data is stored, at inputBuffer.data.
Returns
boolean

Whether an input buffer is ready to be used.
Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

queueInputBuffer

abstract void queueInputBuffer(DecoderInputBuffer inputBuffer)

Queues an input buffer to the Codec. No buffers may be queued after end of stream buffer has been queued.

This method must not be called from video encoders because they must use a Surface to receive input.

Parameters
DecoderInputBuffer inputBuffer

The input buffer.
Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

release

abstract void release()

Releases the Codec.

releaseOutputBuffer

abstract void releaseOutputBuffer(boolean render)

Releases the current output buffer.

Only set render to true when the Codec is a video decoder. Setting render to true will first render the buffer to the output surface. In this case, the surface will release the buffer back to the Codec once it is no longer used/displayed.

This should be called after the buffer has been processed. The next output buffer will not be available until the current output buffer has been released.

Calling this method with render set to true is equivalent to calling releaseOutputBuffer with the presentation timestamp of the output buffer info.

Parameters
boolean render

Whether the buffer needs to be rendered to the output Surface.
Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

releaseOutputBuffer

abstract void releaseOutputBuffer(long renderPresentationTimeUs)

Renders and releases the current output buffer.

This method must only be called on video decoders.

This method will first render the buffer to the output surface. The surface will then release the buffer back to the Codec once it is no longer used/displayed.

This should be called after the buffer has been processed. The next output buffer will not be available until the current output buffer has been released.

Parameters
long renderPresentationTimeUs

The presentation timestamp to associate with this buffer, in microseconds.
Throws
androidx.media3.transformer.ExportException

If the underlying decoder or encoder encounters a problem.

signalEndOfInputStream

abstract void signalEndOfInputStream()

Signals end-of-stream on input to a video encoder.

This method must only be called on video encoders because they must use a Surface as input. For audio/video decoders or audio encoders, the BUFFER_FLAG_END_OF_STREAM flag should be set on the last input buffer queued.

Throws
androidx.media3.transformer.ExportException

If the underlying video encoder encounters a problem.