AudioProcessingPipeline


@UnstableApi
class AudioProcessingPipeline


Handles passing buffers through multiple AudioProcessor instances.

Two instances of AudioProcessingPipeline are considered equal if they have the same underlying AudioProcessor references, in the same order.

To make use of this class, the caller must:

  • Initialize an instance, passing in all audio processors that may be used for processing.
  • Call configure with the AudioFormat of the input data. This method will give back the AudioFormat that will be output from the pipeline when this configuration is in use.
  • Call flush to apply the pending configuration.
  • Check if the pipeline isOperational. If not, then the pipeline can not be used to process buffers in the current configuration. This is because none of the underlying AudioProcessor instances are active.
  • If the pipeline isOperational, queueInput then getOutput to process buffers.
  • queueEndOfStream to inform the pipeline the current input stream is at an end.
  • Repeatedly call getOutput and handle those buffers until isEnded returns true.
  • When finished with the pipeline, call reset to release underlying resources.

If underlying AudioProcessor instances have pending configuration changes, or the AudioFormat of the input is changing:

Summary

Public constructors

Creates an instance.

Public functions

AudioProcessor.AudioFormat!

Configures the pipeline to process input audio with the specified format.

Boolean
equals(o: Any?)

Indicates whether some other object is "equal to" this one.

Unit

Clears any buffered data and pending output.

ByteBuffer!

Returns a ByteBuffer containing processed output data between its position and limit.

Int
Boolean

Returns whether the pipeline has ended.

Boolean

Whether the pipeline can be used for processing buffers.

Unit

Queues an end of stream signal.

Unit
queueInput(inputBuffer: ByteBuffer!)

Queues audio data between the position and limit of the inputBuffer for processing.

Unit

Resets the pipeline and its underlying AudioProcessor instances to their unconfigured state, releasing any resources.

Public properties

AudioProcessor.AudioFormat!

The AudioFormat currently being output by the pipeline.

Public constructors

AudioProcessingPipeline

AudioProcessingPipeline(audioProcessors: ImmutableList<AudioProcessor!>!)

Creates an instance.

Parameters
audioProcessors: ImmutableList<AudioProcessor!>!

The AudioProcessor instances to be used for processing buffers.

Public functions

configure

@CanIgnoreReturnValue
fun configure(inputAudioFormat: AudioProcessor.AudioFormat!): AudioProcessor.AudioFormat!

Configures the pipeline to process input audio with the specified format. Returns the configured output audio format.

To apply the new configuration for use, the pipeline must be flushed. Before applying the new configuration, it is safe to queue input and get output in the old input/output formats/configuration. Call queueEndOfStream when no more input will be supplied for processing in the old configuration.

Parameters
inputAudioFormat: AudioProcessor.AudioFormat!

The format of audio that will be queued after the next call to flush.

Returns
AudioProcessor.AudioFormat!

The configured output audio format.

Throws
androidx.media3.common.audio.AudioProcessor.UnhandledAudioFormatException

If the specified format is not supported by the pipeline.

equals

fun equals(o: Any?): Boolean

Indicates whether some other object is "equal to" this one.

Two instances of AudioProcessingPipeline are considered equal if they have the same underlying AudioProcessor references in the same order.

flush

fun flush(): Unit

Clears any buffered data and pending output. If any underlying audio processors are active, this also prepares them to receive a new stream of input in the last configured (pending) format.

configure must have been called at least once since the last call to reset before calling this.

getOutput

fun getOutput(): ByteBuffer!

Returns a ByteBuffer containing processed output data between its position and limit. The buffer will be empty if no output is available.

Buffers returned from this method are retained by pipeline, and it is necessary to consume the data (or copy it into another buffer) to allow the pipeline to progress.

Returns
ByteBuffer!

A buffer containing processed output data between its position and limit.

hashCode

fun hashCode(): Int

isEnded

fun isEnded(): Boolean

Returns whether the pipeline has ended.

The pipeline is considered ended when:

isOperational

fun isOperational(): Boolean

Whether the pipeline can be used for processing buffers.

For this to happen the pipeline must be configured, flushed and have activeunderlying audio processors that are ready to process buffers with the current configuration.

queueEndOfStream

fun queueEndOfStream(): Unit

Queues an end of stream signal. After this method has been called, queueInput should not be called until after the next call to flush. Calling getOutput will return any remaining output data. Multiple calls may be required to read all of the remaining output data. isEnded will return true once all remaining output data has been read.

queueInput

fun queueInput(inputBuffer: ByteBuffer!): Unit

Queues audio data between the position and limit of the inputBuffer for processing. After calling this method, processed output may be available via getOutput.

Parameters
inputBuffer: ByteBuffer!

The input buffer to process. It must be a direct ByteBuffer with native byte order. Its contents are treated as read-only. Its position will be advanced by the number of bytes consumed (which may be zero). The caller retains ownership of the provided buffer.

reset

fun reset(): Unit

Resets the pipeline and its underlying AudioProcessor instances to their unconfigured state, releasing any resources.

Public properties

outputAudioFormat

val outputAudioFormatAudioProcessor.AudioFormat!

The AudioFormat currently being output by the pipeline.