Skip to content

Most visited

Recently visited

navigation

AudioTrack

public class AudioTrack
extends Object implements AudioRouting

java.lang.Object
   ↳ android.media.AudioTrack


The AudioTrack class manages and plays a single audio resource for Java applications. It allows streaming of PCM audio buffers to the audio sink for playback. This is achieved by "pushing" the data to the AudioTrack object using one of the write(byte[], int, int), write(short[], int, int), and write(float[], int, int, int) methods.

An AudioTrack instance can operate under two modes: static or streaming.
In Streaming mode, the application writes a continuous stream of data to the AudioTrack, using one of the write() methods. These are blocking and return when the data has been transferred from the Java layer to the native layer and queued for playback. The streaming mode is most useful when playing blocks of audio data that for instance are:

  • too big to fit in memory because of the duration of the sound to play,
  • too big to fit in memory because of the characteristics of the audio data (high sampling rate, bits per sample ...)
  • received or generated while previously queued audio is playing.
The static mode should be chosen when dealing with short sounds that fit in memory and that need to be played with the smallest latency possible. The static mode will therefore be preferred for UI and game sounds that are played often, and with the smallest overhead possible.

Upon creation, an AudioTrack object initializes its associated audio buffer. The size of this buffer, specified during the construction, determines how long an AudioTrack can play before running out of data.
For an AudioTrack using the static mode, this size is the maximum size of the sound that can be played from it.
For the streaming mode, data will be written to the audio sink in chunks of sizes less than or equal to the total buffer size. AudioTrack is not final and thus permits subclasses, but such use is not recommended.

Summary

Nested classes

class AudioTrack.Builder

Builder class for AudioTrack objects. 

interface AudioTrack.OnPlaybackPositionUpdateListener

Interface definition for a callback to be invoked when the playback head position of an AudioTrack has reached a notification marker or has increased by a certain period. 

interface AudioTrack.OnRoutingChangedListener

This interface was deprecated in API level 24. users should switch to the general purpose AudioRouting.OnRoutingChangedListener class instead.  

Constants

int ERROR

Denotes a generic operation failure.

int ERROR_BAD_VALUE

Denotes a failure due to the use of an invalid value.

int ERROR_DEAD_OBJECT

An error code indicating that the object reporting it is no longer valid and needs to be recreated.

int ERROR_INVALID_OPERATION

Denotes a failure due to the improper use of a method.

int MODE_STATIC

Creation mode where audio data is transferred from Java to the native layer only once before the audio starts playing.

int MODE_STREAM

Creation mode where audio data is streamed from Java to the native layer as the audio is playing.

int PLAYSTATE_PAUSED

indicates AudioTrack state is paused

int PLAYSTATE_PLAYING

indicates AudioTrack state is playing

int PLAYSTATE_STOPPED

indicates AudioTrack state is stopped

int STATE_INITIALIZED

State of an AudioTrack that is ready to be used.

int STATE_NO_STATIC_DATA

State of a successfully initialized AudioTrack that uses static data, but that hasn't received that data yet.

int STATE_UNINITIALIZED

State of an AudioTrack that was not successfully initialized upon creation.

int SUCCESS

Denotes a successful operation.

int WRITE_BLOCKING

The write mode indicating the write operation will block until all data has been written, to be used as the actual value of the writeMode parameter in write(byte[], int, int, int), write(short[], int, int, int), write(float[], int, int, int), write(ByteBuffer, int, int), and write(ByteBuffer, int, int, long).

int WRITE_NON_BLOCKING

The write mode indicating the write operation will return immediately after queuing as much audio data for playback as possible without blocking, to be used as the actual value of the writeMode parameter in write(ByteBuffer, int, int), write(short[], int, int, int), write(float[], int, int, int), write(ByteBuffer, int, int), and write(ByteBuffer, int, int, long).

Fields

protected AudioAttributes mAttributes

protected float mAuxEffectSendLevel

protected float mLeftVolume

protected float mRightVolume

Public constructors

AudioTrack(int streamType, int sampleRateInHz, int channelConfig, int audioFormat, int bufferSizeInBytes, int mode)

Class constructor.

AudioTrack(int streamType, int sampleRateInHz, int channelConfig, int audioFormat, int bufferSizeInBytes, int mode, int sessionId)

Class constructor with audio session.

AudioTrack(AudioAttributes attributes, AudioFormat format, int bufferSizeInBytes, int mode, int sessionId)

Class constructor with AudioAttributes and AudioFormat.

Public methods

void addOnRoutingChangedListener(AudioTrack.OnRoutingChangedListener listener, Handler handler)

This method was deprecated in API level 24. users should switch to the general purpose AudioRouting.OnRoutingChangedListener class instead.

void addOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener, Handler handler)

Adds an AudioRouting.OnRoutingChangedListener to receive notifications of routing changes on this AudioTrack.

int attachAuxEffect(int effectId)

Attaches an auxiliary effect to the audio track.

void flush()

Flushes the audio data currently queued for playback.

int getAudioFormat()

Returns the configured audio data encoding.

int getAudioSessionId()

Returns the audio session ID.

int getBufferCapacityInFrames()

Returns the maximum size of the AudioTrack buffer in frames.

int getBufferSizeInFrames()

Returns the effective size of the AudioTrack buffer that the application writes to.

int getChannelConfiguration()

Returns the configured channel position mask.

int getChannelCount()

Returns the configured number of channels.

AudioFormat getFormat()

Returns the configured AudioTrack format.

static float getMaxVolume()

Returns the maximum gain value, which is greater than or equal to 1.0.

static int getMinBufferSize(int sampleRateInHz, int channelConfig, int audioFormat)

Returns the estimated minimum buffer size required for an AudioTrack object to be created in the MODE_STREAM mode.

static float getMinVolume()

Returns the minimum gain value, which is the constant 0.0.

static int getNativeOutputSampleRate(int streamType)

Returns the output sample rate in Hz for the specified stream type.

int getNotificationMarkerPosition()

Returns marker position expressed in frames.

int getPlayState()

Returns the playback state of the AudioTrack instance.

int getPlaybackHeadPosition()

Returns the playback head position expressed in frames.

PlaybackParams getPlaybackParams()

Returns the current playback parameters.

int getPlaybackRate()

Returns the current playback sample rate rate in Hz.

int getPositionNotificationPeriod()

Returns the notification update period expressed in frames.

AudioDeviceInfo getPreferredDevice()

Returns the selected output specified by setPreferredDevice(AudioDeviceInfo).

AudioDeviceInfo getRoutedDevice()

Returns an AudioDeviceInfo identifying the current routing of this AudioTrack.

int getSampleRate()

Returns the configured audio source sample rate in Hz.

int getState()

Returns the state of the AudioTrack instance.

int getStreamType()

Returns the type of audio stream this AudioTrack is configured for.

boolean getTimestamp(AudioTimestamp timestamp)

Poll for a timestamp on demand.

int getUnderrunCount()

Returns the number of underrun occurrences in the application-level write buffer since the AudioTrack was created.

void pause()

Pauses the playback of the audio data.

void play()

Starts playing an AudioTrack.

void release()

Releases the native AudioTrack resources.

int reloadStaticData()

Sets the playback head position within the static buffer to zero, that is it rewinds to start of static buffer.

void removeOnRoutingChangedListener(AudioTrack.OnRoutingChangedListener listener)

This method was deprecated in API level 24. users should switch to the general purpose AudioRouting.OnRoutingChangedListener class instead.

void removeOnRoutingChangedListener(AudioRouting.OnRoutingChangedListener listener)

Removes an AudioRouting.OnRoutingChangedListener which has been previously added to receive rerouting notifications.

int setAuxEffectSendLevel(float level)

Sets the send level of the audio track to the attached auxiliary effect attachAuxEffect(int).

int setBufferSizeInFrames(int bufferSizeInFrames)

Limits the effective size of the AudioTrack buffer that the application writes to.

int setLoopPoints(int startInFrames, int endInFrames, int loopCount)

Sets the loop points and the loop count.

int setNotificationMarkerPosition(int markerInFrames)

Sets the position of the notification marker.

int setPlaybackHeadPosition(int positionInFrames)

Sets the playback head position within the static buffer.

void setPlaybackParams(PlaybackParams params)

Sets the playback parameters.

void setPlaybackPositionUpdateListener(AudioTrack.OnPlaybackPositionUpdateListener listener, Handler handler)

Sets the listener the AudioTrack notifies when a previously set marker is reached or for each periodic playback head position update.

void setPlaybackPositionUpdateListener(AudioTrack.OnPlaybackPositionUpdateListener listener)

Sets the listener the AudioTrack notifies when a previously set marker is reached or for each periodic playback head position update.

int setPlaybackRate(int sampleRateInHz)

Sets the playback sample rate for this track.

int setPositionNotificationPeriod(int periodInFrames)

Sets the period for the periodic notification event.

boolean setPreferredDevice(AudioDeviceInfo deviceInfo)

Specifies an audio device (via an AudioDeviceInfo object) to route the output from this AudioTrack.

int setStereoVolume(float leftGain, float rightGain)

This method was deprecated in API level 21. Applications should use setVolume(float) instead, as it more gracefully scales down to mono, and up to multi-channel content beyond stereo.

int setVolume(float gain)

Sets the specified output gain value on all channels of this track.

void stop()

Stops playing the audio data.

int write(float[] audioData, int offsetInFloats, int sizeInFloats, int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode).

int write(short[] audioData, int offsetInShorts, int sizeInShorts)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode).

int write(byte[] audioData, int offsetInBytes, int sizeInBytes)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode).

int write(ByteBuffer audioData, int sizeInBytes, int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode).

int write(ByteBuffer audioData, int sizeInBytes, int writeMode, long timestamp)

Writes the audio data to the audio sink for playback in streaming mode on a HW_AV_SYNC track.

int write(short[] audioData, int offsetInShorts, int sizeInShorts, int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode).

int write(byte[] audioData, int offsetInBytes, int sizeInBytes, int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode).

Protected methods

void finalize()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object.

int getNativeFrameCount()

This method was deprecated in API level 19. Use the identical public method getBufferSizeInFrames() instead.

void setState(int state)

This method was deprecated in API level 19. Only accessible by subclasses, which are not recommended for AudioTrack.

Inherited methods

From class java.lang.Object
From interface android.media.AudioRouting

Constants

ERROR

Added in API level 3
int ERROR

Denotes a generic operation failure.

Constant Value: -1 (0xffffffff)

ERROR_BAD_VALUE

Added in API level 3
int ERROR_BAD_VALUE

Denotes a failure due to the use of an invalid value.

Constant Value: -2 (0xfffffffe)

ERROR_DEAD_OBJECT

Added in API level 24
int ERROR_DEAD_OBJECT

An error code indicating that the object reporting it is no longer valid and needs to be recreated.

Constant Value: -6 (0xfffffffa)

ERROR_INVALID_OPERATION

Added in API level 3
int ERROR_INVALID_OPERATION

Denotes a failure due to the improper use of a method.

Constant Value: -3 (0xfffffffd)

MODE_STATIC

Added in API level 3
int MODE_STATIC

Creation mode where audio data is transferred from Java to the native layer only once before the audio starts playing.

Constant Value: 0 (0x00000000)

MODE_STREAM

Added in API level 3
int MODE_STREAM

Creation mode where audio data is streamed from Java to the native layer as the audio is playing.

Constant Value: 1 (0x00000001)

PLAYSTATE_PAUSED

Added in API level 3
int PLAYSTATE_PAUSED

indicates AudioTrack state is paused

Constant Value: 2 (0x00000002)

PLAYSTATE_PLAYING

Added in API level 3
int PLAYSTATE_PLAYING

indicates AudioTrack state is playing

Constant Value: 3 (0x00000003)

PLAYSTATE_STOPPED

Added in API level 3
int PLAYSTATE_STOPPED

indicates AudioTrack state is stopped

Constant Value: 1 (0x00000001)

STATE_INITIALIZED

Added in API level 3
int STATE_INITIALIZED

State of an AudioTrack that is ready to be used.

Constant Value: 1 (0x00000001)

STATE_NO_STATIC_DATA

Added in API level 3
int STATE_NO_STATIC_DATA

State of a successfully initialized AudioTrack that uses static data, but that hasn't received that data yet.

Constant Value: 2 (0x00000002)

STATE_UNINITIALIZED

Added in API level 3
int STATE_UNINITIALIZED

State of an AudioTrack that was not successfully initialized upon creation.

Constant Value: 0 (0x00000000)

SUCCESS

Added in API level 3
int SUCCESS

Denotes a successful operation.

Constant Value: 0 (0x00000000)

WRITE_BLOCKING

Added in API level 21
int WRITE_BLOCKING

The write mode indicating the write operation will block until all data has been written, to be used as the actual value of the writeMode parameter in write(byte[], int, int, int), write(short[], int, int, int), write(float[], int, int, int), write(ByteBuffer, int, int), and write(ByteBuffer, int, int, long).

Constant Value: 0 (0x00000000)

WRITE_NON_BLOCKING

Added in API level 21
int WRITE_NON_BLOCKING

The write mode indicating the write operation will return immediately after queuing as much audio data for playback as possible without blocking, to be used as the actual value of the writeMode parameter in write(ByteBuffer, int, int), write(short[], int, int, int), write(float[], int, int, int), write(ByteBuffer, int, int), and write(ByteBuffer, int, int, long).

Constant Value: 1 (0x00000001)

Fields

mAttributes

AudioAttributes mAttributes

mAuxEffectSendLevel

float mAuxEffectSendLevel

mLeftVolume

float mLeftVolume

mRightVolume

float mRightVolume

Public constructors

AudioTrack

Added in API level 3
AudioTrack (int streamType, 
                int sampleRateInHz, 
                int channelConfig, 
                int audioFormat, 
                int bufferSizeInBytes, 
                int mode)

Class constructor.

Parameters
streamType int: the type of the audio stream. See STREAM_VOICE_CALL, STREAM_SYSTEM, STREAM_RING, STREAM_MUSIC, STREAM_ALARM, and STREAM_NOTIFICATION.
sampleRateInHz int: the initial source sample rate expressed in Hz. SAMPLE_RATE_UNSPECIFIED means to use a route-dependent value which is usually the sample rate of the sink. getSampleRate() can be used to retrieve the actual sample rate chosen.
channelConfig int: describes the configuration of the audio channels. See CHANNEL_OUT_MONO and CHANNEL_OUT_STEREO
audioFormat int: the format in which the audio data is represented. See ENCODING_PCM_16BIT, ENCODING_PCM_8BIT, and ENCODING_PCM_FLOAT.
bufferSizeInBytes int: the total size (in bytes) of the internal buffer where audio data is read from for playback. This should be a nonzero multiple of the frame size in bytes.

If the track's creation mode is MODE_STATIC, this is the maximum length sample, or audio clip, that can be played by this instance.

If the track's creation mode is MODE_STREAM, this should be the desired buffer size for the AudioTrack to satisfy the application's latency requirements. If bufferSizeInBytes is less than the minimum buffer size for the output sink, it is increased to the minimum buffer size. The method getBufferSizeInFrames() returns the actual size in frames of the buffer created, which determines the minimum frequency to write to the streaming AudioTrack to avoid underrun. See getMinBufferSize(int, int, int) to determine the estimated minimum buffer size for an AudioTrack instance in streaming mode.

mode int: streaming or static buffer. See MODE_STATIC and MODE_STREAM
Throws
IllegalArgumentException

AudioTrack

Added in API level 9
AudioTrack (int streamType, 
                int sampleRateInHz, 
                int channelConfig, 
                int audioFormat, 
                int bufferSizeInBytes, 
                int mode, 
                int sessionId)

Class constructor with audio session. Use this constructor when the AudioTrack must be attached to a particular audio session. The primary use of the audio session ID is to associate audio effects to a particular instance of AudioTrack: if an audio session ID is provided when creating an AudioEffect, this effect will be applied only to audio tracks and media players in the same session and not to the output mix. When an AudioTrack is created without specifying a session, it will create its own session which can be retrieved by calling the getAudioSessionId() method. If a non-zero session ID is provided, this AudioTrack will share effects attached to this session with all other media players or audio tracks in the same session, otherwise a new session will be created for this track if none is supplied.

Parameters
streamType int: the type of the audio stream. See STREAM_VOICE_CALL, STREAM_SYSTEM, STREAM_RING, STREAM_MUSIC, STREAM_ALARM, and STREAM_NOTIFICATION.
sampleRateInHz int: the initial source sample rate expressed in Hz. SAMPLE_RATE_UNSPECIFIED means to use a route-dependent value which is usually the sample rate of the sink.
channelConfig int: describes the configuration of the audio channels. See CHANNEL_OUT_MONO and CHANNEL_OUT_STEREO
audioFormat int: the format in which the audio data is represented. See ENCODING_PCM_16BIT and ENCODING_PCM_8BIT, and ENCODING_PCM_FLOAT.
bufferSizeInBytes int: the total size (in bytes) of the internal buffer where audio data is read from for playback. This should be a nonzero multiple of the frame size in bytes.

If the track's creation mode is MODE_STATIC, this is the maximum length sample, or audio clip, that can be played by this instance.

If the track's creation mode is MODE_STREAM, this should be the desired buffer size for the AudioTrack to satisfy the application's latency requirements. If bufferSizeInBytes is less than the minimum buffer size for the output sink, it is increased to the minimum buffer size. The method getBufferSizeInFrames() returns the actual size in frames of the buffer created, which determines the minimum frequency to write to the streaming AudioTrack to avoid underrun. You can write data into this buffer in smaller chunks than this size. See getMinBufferSize(int, int, int) to determine the estimated minimum buffer size for an AudioTrack instance in streaming mode.

mode int: streaming or static buffer. See MODE_STATIC and MODE_STREAM
sessionId int: Id of audio session the AudioTrack must be attached to
Throws
IllegalArgumentException

AudioTrack

Added in API level 21
AudioTrack (AudioAttributes attributes, 
                AudioFormat format, 
                int bufferSizeInBytes, 
                int mode, 
                int sessionId)

Class constructor with AudioAttributes and AudioFormat.

Parameters
attributes AudioAttributes: a non-null AudioAttributes instance.
format AudioFormat: a non-null AudioFormat instance describing the format of the data that will be played through this AudioTrack. See AudioFormat.Builder for configuring the audio format parameters such as encoding, channel mask and sample rate.
bufferSizeInBytes int: the total size (in bytes) of the internal buffer where audio data is read from for playback. This should be a nonzero multiple of the frame size in bytes.

If the track's creation mode is MODE_STATIC, this is the maximum length sample, or audio clip, that can be played by this instance.

If the track's creation mode is MODE_STREAM, this should be the desired buffer size for the AudioTrack to satisfy the application's latency requirements. If bufferSizeInBytes is less than the minimum buffer size for the output sink, it is increased to the minimum buffer size. The method getBufferSizeInFrames() returns the actual size in frames of the buffer created, which determines the minimum frequency to write to the streaming AudioTrack to avoid underrun. See getMinBufferSize(int, int, int) to determine the estimated minimum buffer size for an AudioTrack instance in streaming mode.

mode int: streaming or static buffer. See MODE_STATIC and MODE_STREAM.
sessionId int: ID of audio session the AudioTrack must be attached to, or AUDIO_SESSION_ID_GENERATE if the session isn't known at construction time. See also generateAudioSessionId() to obtain a session ID before construction.
Throws
IllegalArgumentException

Public methods

addOnRoutingChangedListener

Added in API level 23
void addOnRoutingChangedListener (AudioTrack.OnRoutingChangedListener listener, 
                Handler handler)

This method was deprecated in API level 24.
users should switch to the general purpose AudioRouting.OnRoutingChangedListener class instead.

Adds an AudioTrack.OnRoutingChangedListener to receive notifications of routing changes on this AudioTrack.

Parameters
listener AudioTrack.OnRoutingChangedListener: The AudioTrack.OnRoutingChangedListener interface to receive notifications of rerouting events.
handler Handler: Specifies the Handler object for the thread on which to execute the callback. If null, the Handler associated with the main Looper will be used.

addOnRoutingChangedListener

Added in API level 24
void addOnRoutingChangedListener (AudioRouting.OnRoutingChangedListener listener, 
                Handler handler)

Adds an AudioRouting.OnRoutingChangedListener to receive notifications of routing changes on this AudioTrack.

Parameters
listener AudioRouting.OnRoutingChangedListener: The AudioRouting.OnRoutingChangedListener interface to receive notifications of rerouting events.
handler Handler: Specifies the Handler object for the thread on which to execute the callback. If null, the Handler associated with the main Looper will be used.

attachAuxEffect

Added in API level 9
int attachAuxEffect (int effectId)

Attaches an auxiliary effect to the audio track. A typical auxiliary effect is a reverberation effect which can be applied on any sound source that directs a certain amount of its energy to this effect. This amount is defined by setAuxEffectSendLevel(). .

After creating an auxiliary effect (e.g. EnvironmentalReverb), retrieve its ID with getId() and use it when calling this method to attach the audio track to the effect.

To detach the effect from the audio track, call this method with a null effect id.

Parameters
effectId int: system wide unique id of the effect to attach
Returns
int error code or success, see SUCCESS, ERROR_INVALID_OPERATION, ERROR_BAD_VALUE

See also:

flush

Added in API level 3
void flush ()

Flushes the audio data currently queued for playback. Any data that has been written but not yet presented will be discarded. No-op if not stopped or paused, or if the track's creation mode is not MODE_STREAM.
Note that although data written but not yet presented is discarded, there is no guarantee that all of the buffer space formerly used by that data is available for a subsequent write. For example, a call to write(byte[], int, int) with sizeInBytes less than or equal to the total buffer size may return a short actual transfer count.

getAudioFormat

Added in API level 3
int getAudioFormat ()

Returns the configured audio data encoding. See ENCODING_PCM_8BIT, ENCODING_PCM_16BIT, and ENCODING_PCM_FLOAT.

Returns
int

getAudioSessionId

Added in API level 9
int getAudioSessionId ()

Returns the audio session ID.

Returns
int the ID of the audio session this AudioTrack belongs to.

getBufferCapacityInFrames

Added in API level 24
int getBufferCapacityInFrames ()

Returns the maximum size of the AudioTrack buffer in frames.

If the track's creation mode is MODE_STATIC, it is equal to the specified bufferSizeInBytes on construction, converted to frame units. A static track's frame count will not change.

If the track's creation mode is MODE_STREAM, it is greater than or equal to the specified bufferSizeInBytes converted to frame units. For streaming tracks, this value may be rounded up to a larger value if needed by the target output sink, and if the track is subsequently routed to a different output sink, the frame count may enlarge to accommodate.

If the AudioTrack encoding indicates compressed data, e.g. ENCODING_AC3, then the frame count returned is the size of the AudioTrack buffer in bytes.

See also getProperty(String) for key PROPERTY_OUTPUT_FRAMES_PER_BUFFER.

Returns
int maximum size in frames of the AudioTrack buffer.
Throws
IllegalStateException if track is not initialized.

getBufferSizeInFrames

Added in API level 23
int getBufferSizeInFrames ()

Returns the effective size of the AudioTrack buffer that the application writes to.

This will be less than or equal to the result of getBufferCapacityInFrames(). It will be equal if setBufferSizeInFrames(int) has never been called.

If the track is subsequently routed to a different output sink, the buffer size and capacity may enlarge to accommodate.

If the AudioTrack encoding indicates compressed data, e.g. ENCODING_AC3, then the frame count returned is the size of the AudioTrack buffer in bytes.

See also getProperty(String) for key PROPERTY_OUTPUT_FRAMES_PER_BUFFER.

Returns
int current size in frames of the AudioTrack buffer.
Throws
IllegalStateException if track is not initialized.

getChannelConfiguration

Added in API level 3
int getChannelConfiguration ()

Returns the configured channel position mask.

For example, refer to CHANNEL_OUT_MONO, CHANNEL_OUT_STEREO, CHANNEL_OUT_5POINT1. This method may return CHANNEL_INVALID if a channel index mask was used. Consider getFormat() instead, to obtain an AudioFormat, which contains both the channel position mask and the channel index mask.

Returns
int

getChannelCount

Added in API level 3
int getChannelCount ()

Returns the configured number of channels.

Returns
int

getFormat

Added in API level 23
AudioFormat getFormat ()

Returns the configured AudioTrack format.

Returns
AudioFormat an AudioFormat containing the AudioTrack parameters at the time of configuration.

getMaxVolume

Added in API level 3
float getMaxVolume ()

Returns the maximum gain value, which is greater than or equal to 1.0. Gain values greater than the maximum will be clamped to the maximum.

The word "volume" in the API name is historical; this is actually a gain. expressed as a linear multiplier on sample values, where a maximum value of 1.0 corresponds to a gain of 0 dB (sample values left unmodified).

Returns
float the maximum value, which is greater than or equal to 1.0.

getMinBufferSize

Added in API level 3
int getMinBufferSize (int sampleRateInHz, 
                int channelConfig, 
                int audioFormat)

Returns the estimated minimum buffer size required for an AudioTrack object to be created in the MODE_STREAM mode. The size is an estimate because it does not consider either the route or the sink, since neither is known yet. Note that this size doesn't guarantee a smooth playback under load, and higher values should be chosen according to the expected frequency at which the buffer will be refilled with additional data to play. For example, if you intend to dynamically set the source sample rate of an AudioTrack to a higher value than the initial source sample rate, be sure to configure the buffer size based on the highest planned sample rate.

Parameters
sampleRateInHz int: the source sample rate expressed in Hz. SAMPLE_RATE_UNSPECIFIED is not permitted.
channelConfig int: describes the configuration of the audio channels. See CHANNEL_OUT_MONO and CHANNEL_OUT_STEREO
audioFormat int: the format in which the audio data is represented. See ENCODING_PCM_16BIT and ENCODING_PCM_8BIT, and ENCODING_PCM_FLOAT.
Returns
int ERROR_BAD_VALUE if an invalid parameter was passed, or ERROR if unable to query for output properties, or the minimum buffer size expressed in bytes.

getMinVolume

Added in API level 3
float getMinVolume ()

Returns the minimum gain value, which is the constant 0.0. Gain values less than 0.0 will be clamped to 0.0.

The word "volume" in the API name is historical; this is actually a linear gain.

Returns
float the minimum value, which is the constant 0.0.

getNativeOutputSampleRate

Added in API level 3
int getNativeOutputSampleRate (int streamType)

Returns the output sample rate in Hz for the specified stream type.

Parameters
streamType int
Returns
int

getNotificationMarkerPosition

Added in API level 3
int getNotificationMarkerPosition ()

Returns marker position expressed in frames.

Returns
int marker position in wrapping frame units similar to getPlaybackHeadPosition(), or zero if marker is disabled.

getPlayState

Added in API level 3
int getPlayState ()

Returns the playback state of the AudioTrack instance.

Returns
int

See also:

getPlaybackHeadPosition

Added in API level 3
int getPlaybackHeadPosition ()

Returns the playback head position expressed in frames. Though the "int" type is signed 32-bits, the value should be reinterpreted as if it is unsigned 32-bits. That is, the next position after 0x7FFFFFFF is (int) 0x80000000. This is a continuously advancing counter. It will wrap (overflow) periodically, for example approximately once every 27:03:11 hours:minutes:seconds at 44.1 kHz. It is reset to zero by flush(), reloadStaticData(), and stop(). If the track's creation mode is MODE_STATIC, the return value indicates the total number of frames played since reset, not the current offset within the buffer.

Returns
int

getPlaybackParams

Added in API level 23
PlaybackParams getPlaybackParams ()

Returns the current playback parameters. See setPlaybackParams(PlaybackParams) to set playback parameters

Returns
PlaybackParams current PlaybackParams.
Throws
IllegalStateException if track is not initialized.

getPlaybackRate

Added in API level 3
int getPlaybackRate ()

Returns the current playback sample rate rate in Hz.

Returns
int

getPositionNotificationPeriod

Added in API level 3
int getPositionNotificationPeriod ()

Returns the notification update period expressed in frames. Zero means that no position update notifications are being delivered.

Returns
int

getPreferredDevice

Added in API level 23
AudioDeviceInfo getPreferredDevice ()

Returns the selected output specified by setPreferredDevice(AudioDeviceInfo). Note that this is not guaranteed to correspond to the actual device being used for playback.

Returns
AudioDeviceInfo

getRoutedDevice

Added in API level 23
AudioDeviceInfo getRoutedDevice ()

Returns an AudioDeviceInfo identifying the current routing of this AudioTrack. Note: The query is only valid if the AudioTrack is currently playing. If it is not, getRoutedDevice() will return null.

Returns
AudioDeviceInfo

getSampleRate

Added in API level 3
int getSampleRate ()

Returns the configured audio source sample rate in Hz. The initial source sample rate depends on the constructor parameters, but the source sample rate may change if setPlaybackRate(int) is called. If the constructor had a specific sample rate, then the initial sink sample rate is that value. If the constructor had SAMPLE_RATE_UNSPECIFIED, then the initial sink sample rate is a route-dependent default value based on the source [sic].

Returns
int

getState

Added in API level 3
int getState ()

Returns the state of the AudioTrack instance. This is useful after the AudioTrack instance has been created to check if it was initialized properly. This ensures that the appropriate resources have been acquired.

Returns
int

See also:

getStreamType

Added in API level 3
int getStreamType ()

Returns the type of audio stream this AudioTrack is configured for. Compare the result against STREAM_VOICE_CALL, STREAM_SYSTEM, STREAM_RING, STREAM_MUSIC, STREAM_ALARM, STREAM_NOTIFICATION, or STREAM_DTMF.

Returns
int

getTimestamp

Added in API level 19
boolean getTimestamp (AudioTimestamp timestamp)

Poll for a timestamp on demand.

If you need to track timestamps during initial warmup or after a routing or mode change, you should request a new timestamp periodically until the reported timestamps show that the frame position is advancing, or until it becomes clear that timestamps are unavailable for this route.

After the clock is advancing at a stable rate, query for a new timestamp approximately once every 10 seconds to once per minute. Calling this method more often is inefficient. It is also counter-productive to call this method more often than recommended, because the short-term differences between successive timestamp reports are not meaningful. If you need a high-resolution mapping between frame position and presentation time, consider implementing that at application level, based on low-resolution timestamps.

The audio data at the returned position may either already have been presented, or may have not yet been presented but is committed to be presented. It is not possible to request the time corresponding to a particular position, or to request the (fractional) position corresponding to a particular time. If you need such features, consider implementing them at application level.

Parameters
timestamp AudioTimestamp: a reference to a non-null AudioTimestamp instance allocated and owned by caller.
Returns
boolean true if a timestamp is available, or false if no timestamp is available. If a timestamp if available, the AudioTimestamp instance is filled in with a position in frame units, together with the estimated time when that frame was presented or is committed to be presented. In the case that no timestamp is available, any supplied instance is left unaltered. A timestamp may be temporarily unavailable while the audio clock is stabilizing, or during and immediately after a route change. A timestamp is permanently unavailable for a given route if the route does not support timestamps. In this case, the approximate frame position can be obtained using getPlaybackHeadPosition(). However, it may be useful to continue to query for timestamps occasionally, to recover after a route change.

getUnderrunCount

Added in API level 24
int getUnderrunCount ()

Returns the number of underrun occurrences in the application-level write buffer since the AudioTrack was created. An underrun occurs if the application does not write audio data quickly enough, causing the buffer to underflow and a potential audio glitch or pop.

Underruns are less likely when buffer sizes are large. It may be possible to eliminate underruns by recreating the AudioTrack with a larger buffer. Or by using setBufferSizeInFrames(int) to dynamically increase the effective size of the buffer.

Returns
int

pause

Added in API level 3
void pause ()

Pauses the playback of the audio data. Data that has not been played back will not be discarded. Subsequent calls to play() will play this data back. See flush() to discard this data.

Throws
IllegalStateException

play

Added in API level 3
void play ()

Starts playing an AudioTrack.

If track's creation mode is MODE_STATIC, you must have called one of the write methods (write(byte[], int, int), write(byte[], int, int, int), write(short[], int, int), write(short[], int, int, int), write(float[], int, int, int), or write(ByteBuffer, int, int)) prior to play().

If the mode is MODE_STREAM, you can optionally prime the data path prior to calling play(), by writing up to bufferSizeInBytes (from constructor). If you don't call write() first, or if you call write() but with an insufficient amount of data, then the track will be in underrun state at play(). In this case, playback will not actually start playing until the data path is filled to a device-specific minimum level. This requirement for the path to be filled to a minimum level is also true when resuming audio playback after calling stop(). Similarly the buffer will need to be filled up again after the track underruns due to failure to call write() in a timely manner with sufficient data. For portability, an application should prime the data path to the maximum allowed by writing data until the write() method returns a short transfer count. This allows play() to start immediately, and reduces the chance of underrun.

Throws
IllegalStateException if the track isn't properly initialized

release

Added in API level 3
void release ()

Releases the native AudioTrack resources.

reloadStaticData

Added in API level 3
int reloadStaticData ()

Sets the playback head position within the static buffer to zero, that is it rewinds to start of static buffer. The track must be stopped or paused, and the track's creation mode must be MODE_STATIC.

As of M, also resets the value returned by getPlaybackHeadPosition() to zero. For earlier API levels, the reset behavior is unspecified.

Use setPlaybackHeadPosition(int) with a zero position if the reset of getPlaybackHeadPosition() is not needed.

Returns
int error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION

removeOnRoutingChangedListener

Added in API level 23
void removeOnRoutingChangedListener (AudioTrack.OnRoutingChangedListener listener)

This method was deprecated in API level 24.
users should switch to the general purpose AudioRouting.OnRoutingChangedListener class instead.

Removes an AudioTrack.OnRoutingChangedListener which has been previously added to receive rerouting notifications.

Parameters
listener AudioTrack.OnRoutingChangedListener: The previously added AudioTrack.OnRoutingChangedListener interface to remove.

removeOnRoutingChangedListener

Added in API level 24
void removeOnRoutingChangedListener (AudioRouting.OnRoutingChangedListener listener)

Removes an AudioRouting.OnRoutingChangedListener which has been previously added to receive rerouting notifications.

Parameters
listener AudioRouting.OnRoutingChangedListener: The previously added AudioRouting.OnRoutingChangedListener interface to remove.

setAuxEffectSendLevel

Added in API level 9
int setAuxEffectSendLevel (float level)

Sets the send level of the audio track to the attached auxiliary effect attachAuxEffect(int). Effect levels are clamped to the closed interval [0.0, max] where max is the value of getMaxVolume(). A value of 0.0 results in no effect, and a value of 1.0 is full send.

By default the send level is 0.0f, so even if an effect is attached to the player this method must be called for the effect to be applied.

Note that the passed level value is a linear scalar. UI controls should be scaled logarithmically: the gain applied by audio framework ranges from -72dB to at least 0dB, so an appropriate conversion from linear UI input x to level is: x == 0 -> level = 0 0 < x <= R -> level = 10^(72*(x-R)/20/R)

Parameters
level float: linear send level
Returns
int error code or success, see SUCCESS, ERROR_INVALID_OPERATION, ERROR

setBufferSizeInFrames

Added in API level 24
int setBufferSizeInFrames (int bufferSizeInFrames)

Limits the effective size of the AudioTrack buffer that the application writes to.

A write to this AudioTrack will not fill the buffer beyond this limit. If a blocking write is used then the write will block until the data can fit within this limit.

Changing this limit modifies the latency associated with the buffer for this track. A smaller size will give lower latency but there may be more glitches due to buffer underruns.

The actual size used may not be equal to this requested size. It will be limited to a valid range with a maximum of getBufferCapacityInFrames(). It may also be adjusted slightly for internal reasons. If bufferSizeInFrames is less than zero then ERROR_BAD_VALUE will be returned.

This method is only supported for PCM audio. It is not supported for compressed audio tracks.

Parameters
bufferSizeInFrames int: requested buffer size in frames
Returns
int the actual buffer size in frames or an error code, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION
Throws
IllegalStateException if track is not initialized.

setLoopPoints

Added in API level 3
int setLoopPoints (int startInFrames, 
                int endInFrames, 
                int loopCount)

Sets the loop points and the loop count. The loop can be infinite. Similarly to setPlaybackHeadPosition, the track must be stopped or paused for the loop points to be changed, and must use the MODE_STATIC mode.

Parameters
startInFrames int: loop start marker expressed in frames. Zero corresponds to start of buffer. The start marker must not be greater than or equal to the buffer size in frames, or negative.
endInFrames int: loop end marker expressed in frames. The total buffer size in frames corresponds to end of buffer. The end marker must not be greater than the buffer size in frames. For looping, the end marker must not be less than or equal to the start marker, but to disable looping it is permitted for start marker, end marker, and loop count to all be 0. If any input parameters are out of range, this method returns ERROR_BAD_VALUE. If the loop period (endInFrames - startInFrames) is too small for the implementation to support, ERROR_BAD_VALUE is returned. The loop range is the interval [startInFrames, endInFrames).
As of M, the position is left unchanged, unless it is greater than or equal to the loop end marker, in which case it is forced to the loop start marker. For earlier API levels, the effect on position is unspecified.
loopCount int: the number of times the loop is looped; must be greater than or equal to -1. A value of -1 means infinite looping, and 0 disables looping. A value of positive N means to "loop" (go back) N times. For example, a value of one means to play the region two times in total.
Returns
int error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION

setNotificationMarkerPosition

Added in API level 3
int setNotificationMarkerPosition (int markerInFrames)

Sets the position of the notification marker. At most one marker can be active.

Parameters
markerInFrames int: marker position in wrapping frame units similar to getPlaybackHeadPosition(), or zero to disable the marker. To set a marker at a position which would appear as zero due to wraparound, a workaround is to use a non-zero position near zero, such as -1 or 1.
Returns
int error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION

setPlaybackHeadPosition

Added in API level 3
int setPlaybackHeadPosition (int positionInFrames)

Sets the playback head position within the static buffer. The track must be stopped or paused for the position to be changed, and must use the MODE_STATIC mode.

Parameters
positionInFrames int: playback head position within buffer, expressed in frames. Zero corresponds to start of buffer. The position must not be greater than the buffer size in frames, or negative. Though this method and getPlaybackHeadPosition() have similar names, the position values have different meanings.
If looping is currently enabled and the new position is greater than or equal to the loop end marker, the behavior varies by API level: as of M, the looping is first disabled and then the position is set. For earlier API levels, the behavior is unspecified.
Returns
int error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION

setPlaybackParams

Added in API level 23
void setPlaybackParams (PlaybackParams params)

Sets the playback parameters. This method returns failure if it cannot apply the playback parameters. One possible cause is that the parameters for speed or pitch are out of range. Another possible cause is that the AudioTrack is streaming (see MODE_STREAM) and the buffer size is too small. For speeds greater than 1.0f, the AudioTrack buffer on configuration must be larger than the speed multiplied by the minimum size getMinBufferSize(int, int, int)) to allow proper playback.

Parameters
params PlaybackParams: see PlaybackParams. In particular, speed, pitch, and audio mode should be set.
Throws
IllegalArgumentException if the parameters are invalid or not accepted.
IllegalStateException if track is not initialized.

setPlaybackPositionUpdateListener

Added in API level 3
void setPlaybackPositionUpdateListener (AudioTrack.OnPlaybackPositionUpdateListener listener, 
                Handler handler)

Sets the listener the AudioTrack notifies when a previously set marker is reached or for each periodic playback head position update. Use this method to receive AudioTrack events in the Handler associated with another thread than the one in which you created the AudioTrack instance.

Parameters
handler Handler: the Handler that will receive the event notification messages.

setPlaybackPositionUpdateListener

Added in API level 3
void setPlaybackPositionUpdateListener (AudioTrack.OnPlaybackPositionUpdateListener listener)

Sets the listener the AudioTrack notifies when a previously set marker is reached or for each periodic playback head position update. Notifications will be received in the same thread as the one in which the AudioTrack instance was created.

setPlaybackRate

Added in API level 3
int setPlaybackRate (int sampleRateInHz)

Sets the playback sample rate for this track. This sets the sampling rate at which the audio data will be consumed and played back (as set by the sampleRateInHz parameter in the AudioTrack(int, int, int, int, int, int) constructor), not the original sampling rate of the content. For example, setting it to half the sample rate of the content will cause the playback to last twice as long, but will also result in a pitch shift down by one octave. The valid sample rate range is from 1 Hz to twice the value returned by getNativeOutputSampleRate(int). Use setPlaybackParams(PlaybackParams) for speed control.

This method may also be used to repurpose an existing AudioTrack for playback of content of differing sample rate, but with identical encoding and channel mask.

Parameters
sampleRateInHz int: the sample rate expressed in Hz
Returns
int error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION

setPositionNotificationPeriod

Added in API level 3
int setPositionNotificationPeriod (int periodInFrames)

Sets the period for the periodic notification event.

Parameters
periodInFrames int: update period expressed in frames. Zero period means no position updates. A negative period is not allowed.
Returns
int error code or success, see SUCCESS, ERROR_INVALID_OPERATION

setPreferredDevice

Added in API level 23
boolean setPreferredDevice (AudioDeviceInfo deviceInfo)

Specifies an audio device (via an AudioDeviceInfo object) to route the output from this AudioTrack.

Parameters
deviceInfo AudioDeviceInfo: The AudioDeviceInfo specifying the audio sink. If deviceInfo is null, default routing is restored.
Returns
boolean true if succesful, false if the specified AudioDeviceInfo is non-null and does not correspond to a valid audio output device.

setStereoVolume

Added in API level 3
int setStereoVolume (float leftGain, 
                float rightGain)

This method was deprecated in API level 21.
Applications should use setVolume(float) instead, as it more gracefully scales down to mono, and up to multi-channel content beyond stereo.

Sets the specified left and right output gain values on the AudioTrack.

Gain values are clamped to the closed interval [0.0, max] where max is the value of getMaxVolume(). A value of 0.0 results in zero gain (silence), and a value of 1.0 means unity gain (signal unchanged). The default value is 1.0 meaning unity gain.

The word "volume" in the API name is historical; this is actually a linear gain.

Parameters
leftGain float: output gain for the left channel.
rightGain float: output gain for the right channel
Returns
int error code or success, see SUCCESS, ERROR_INVALID_OPERATION

setVolume

Added in API level 21
int setVolume (float gain)

Sets the specified output gain value on all channels of this track.

Gain values are clamped to the closed interval [0.0, max] where max is the value of getMaxVolume(). A value of 0.0 results in zero gain (silence), and a value of 1.0 means unity gain (signal unchanged). The default value is 1.0 meaning unity gain.

This API is preferred over setStereoVolume(float, float), as it more gracefully scales down to mono, and up to multi-channel content beyond stereo.

The word "volume" in the API name is historical; this is actually a linear gain.

Parameters
gain float: output gain for all channels.
Returns
int error code or success, see SUCCESS, ERROR_INVALID_OPERATION

stop

Added in API level 3
void stop ()

Stops playing the audio data. When used on an instance created in MODE_STREAM mode, audio will stop playing after the last buffer that was written has been played. For an immediate stop, use pause(), followed by flush() to discard audio data that hasn't been played back yet.

Throws
IllegalStateException

write

Added in API level 21
int write (float[] audioData, 
                int offsetInFloats, 
                int sizeInFloats, 
                int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode). The format specified in the AudioTrack constructor should be ENCODING_PCM_FLOAT to correspond to the data in the array.

In streaming mode, the blocking behavior depends on the write mode. If the write mode is WRITE_BLOCKING, the write will normally block until all the data has been enqueued for playback, and will return a full transfer count. However, if the write mode is WRITE_NON_BLOCKING, or the track is stopped or paused on entry, or another thread interrupts the write by calling stop or pause, or an I/O error occurs during the write, then the write may return a short transfer count.

In static buffer mode, copies the data to the buffer starting at offset 0, and the write mode is ignored. Note that the actual playback of this data might occur after this function returns.

Parameters
audioData float: the array that holds the data to write. The implementation does not clip for sample values within the nominal range [-1.0f, 1.0f], provided that all gains in the audio pipeline are less than or equal to unity (1.0f), and in the absence of post-processing effects that could add energy, such as reverb. For the convenience of applications that compute samples using filters with non-unity gain, sample values +3 dB beyond the nominal range are permitted. However such values may eventually be limited or clipped, depending on various gains and later processing in the audio path. Therefore applications are encouraged to provide samples values within the nominal range.
offsetInFloats int: the offset, expressed as a number of floats, in audioData where the data to write starts. Must not be negative, or cause the data access to go out of bounds of the array.
sizeInFloats int: the number of floats to write in audioData after the offset. Must not be negative, or cause the data access to go out of bounds of the array.
writeMode int: one of WRITE_BLOCKING, WRITE_NON_BLOCKING. It has no effect in static mode.
With WRITE_BLOCKING, the write will block until all data has been written to the audio sink.
With WRITE_NON_BLOCKING, the write will return immediately after queuing as much audio data for playback as possible without blocking.
Returns
int zero or the positive number of floats that were written, or one of the following error codes. The number of floats will be a multiple of the channel count not to exceed sizeInFloats.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error

write

Added in API level 3
int write (short[] audioData, 
                int offsetInShorts, 
                int sizeInShorts)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode). The format specified in the AudioTrack constructor should be ENCODING_PCM_16BIT to correspond to the data in the array.

In streaming mode, the write will normally block until all the data has been enqueued for playback, and will return a full transfer count. However, if the track is stopped or paused on entry, or another thread interrupts the write by calling stop or pause, or an I/O error occurs during the write, then the write may return a short transfer count.

In static buffer mode, copies the data to the buffer starting at offset 0. Note that the actual playback of this data might occur after this function returns.

Parameters
audioData short: the array that holds the data to play.
offsetInShorts int: the offset expressed in shorts in audioData where the data to play starts. Must not be negative, or cause the data access to go out of bounds of the array.
sizeInShorts int: the number of shorts to read in audioData after the offset. Must not be negative, or cause the data access to go out of bounds of the array.
Returns
int zero or the positive number of shorts that were written, or one of the following error codes. The number of shorts will be a multiple of the channel count not to exceed sizeInShorts.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error
This is equivalent to write(short[], int, int, int) with writeMode set to WRITE_BLOCKING.

write

Added in API level 3
int write (byte[] audioData, 
                int offsetInBytes, 
                int sizeInBytes)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode). The format specified in the AudioTrack constructor should be ENCODING_PCM_8BIT to correspond to the data in the array. The format can be ENCODING_PCM_16BIT, but this is deprecated.

In streaming mode, the write will normally block until all the data has been enqueued for playback, and will return a full transfer count. However, if the track is stopped or paused on entry, or another thread interrupts the write by calling stop or pause, or an I/O error occurs during the write, then the write may return a short transfer count.

In static buffer mode, copies the data to the buffer starting at offset 0. Note that the actual playback of this data might occur after this function returns.

Parameters
audioData byte: the array that holds the data to play.
offsetInBytes int: the offset expressed in bytes in audioData where the data to write starts. Must not be negative, or cause the data access to go out of bounds of the array.
sizeInBytes int: the number of bytes to write in audioData after the offset. Must not be negative, or cause the data access to go out of bounds of the array.
Returns
int zero or the positive number of bytes that were written, or one of the following error codes. The number of bytes will be a multiple of the frame size in bytes not to exceed sizeInBytes.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error
This is equivalent to write(byte[], int, int, int) with writeMode set to WRITE_BLOCKING.

write

Added in API level 21
int write (ByteBuffer audioData, 
                int sizeInBytes, 
                int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode). The audioData in ByteBuffer should match the format specified in the AudioTrack constructor.

In streaming mode, the blocking behavior depends on the write mode. If the write mode is WRITE_BLOCKING, the write will normally block until all the data has been enqueued for playback, and will return a full transfer count. However, if the write mode is WRITE_NON_BLOCKING, or the track is stopped or paused on entry, or another thread interrupts the write by calling stop or pause, or an I/O error occurs during the write, then the write may return a short transfer count.

In static buffer mode, copies the data to the buffer starting at offset 0, and the write mode is ignored. Note that the actual playback of this data might occur after this function returns.

Parameters
audioData ByteBuffer: the buffer that holds the data to write, starting at the position reported by audioData.position().
Note that upon return, the buffer position (audioData.position()) will have been advanced to reflect the amount of data that was successfully written to the AudioTrack.
sizeInBytes int: number of bytes to write. It is recommended but not enforced that the number of bytes requested be a multiple of the frame size (sample size in bytes multiplied by the channel count).
Note this may differ from audioData.remaining(), but cannot exceed it.
writeMode int: one of WRITE_BLOCKING, WRITE_NON_BLOCKING. It has no effect in static mode.
With WRITE_BLOCKING, the write will block until all data has been written to the audio sink.
With WRITE_NON_BLOCKING, the write will return immediately after queuing as much audio data for playback as possible without blocking.
Returns
int zero or the positive number of bytes that were written, or one of the following error codes.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error

write

Added in API level 23
int write (ByteBuffer audioData, 
                int sizeInBytes, 
                int writeMode, 
                long timestamp)

Writes the audio data to the audio sink for playback in streaming mode on a HW_AV_SYNC track. The blocking behavior will depend on the write mode.

Parameters
audioData ByteBuffer: the buffer that holds the data to write, starting at the position reported by audioData.position().
Note that upon return, the buffer position (audioData.position()) will have been advanced to reflect the amount of data that was successfully written to the AudioTrack.
sizeInBytes int: number of bytes to write. It is recommended but not enforced that the number of bytes requested be a multiple of the frame size (sample size in bytes multiplied by the channel count).
Note this may differ from audioData.remaining(), but cannot exceed it.
writeMode int: one of WRITE_BLOCKING, WRITE_NON_BLOCKING.
With WRITE_BLOCKING, the write will block until all data has been written to the audio sink.
With WRITE_NON_BLOCKING, the write will return immediately after queuing as much audio data for playback as possible without blocking.
timestamp long: The timestamp of the first decodable audio frame in the provided audioData.
Returns
int zero or the positive number of bytes that were written, or one of the following error codes.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error

write

Added in API level 23
int write (short[] audioData, 
                int offsetInShorts, 
                int sizeInShorts, 
                int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode). The format specified in the AudioTrack constructor should be ENCODING_PCM_16BIT to correspond to the data in the array.

In streaming mode, the blocking behavior depends on the write mode. If the write mode is WRITE_BLOCKING, the write will normally block until all the data has been enqueued for playback, and will return a full transfer count. However, if the write mode is WRITE_NON_BLOCKING, or the track is stopped or paused on entry, or another thread interrupts the write by calling stop or pause, or an I/O error occurs during the write, then the write may return a short transfer count.

In static buffer mode, copies the data to the buffer starting at offset 0. Note that the actual playback of this data might occur after this function returns.

Parameters
audioData short: the array that holds the data to write.
offsetInShorts int: the offset expressed in shorts in audioData where the data to write starts. Must not be negative, or cause the data access to go out of bounds of the array.
sizeInShorts int: the number of shorts to read in audioData after the offset. Must not be negative, or cause the data access to go out of bounds of the array.
writeMode int: one of WRITE_BLOCKING, WRITE_NON_BLOCKING. It has no effect in static mode.
With WRITE_BLOCKING, the write will block until all data has been written to the audio sink.
With WRITE_NON_BLOCKING, the write will return immediately after queuing as much audio data for playback as possible without blocking.
Returns
int zero or the positive number of shorts that were written, or one of the following error codes. The number of shorts will be a multiple of the channel count not to exceed sizeInShorts.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error

write

Added in API level 23
int write (byte[] audioData, 
                int offsetInBytes, 
                int sizeInBytes, 
                int writeMode)

Writes the audio data to the audio sink for playback (streaming mode), or copies audio data for later playback (static buffer mode). The format specified in the AudioTrack constructor should be ENCODING_PCM_8BIT to correspond to the data in the array. The format can be ENCODING_PCM_16BIT, but this is deprecated.

In streaming mode, the blocking behavior depends on the write mode. If the write mode is WRITE_BLOCKING, the write will normally block until all the data has been enqueued for playback, and will return a full transfer count. However, if the write mode is WRITE_NON_BLOCKING, or the track is stopped or paused on entry, or another thread interrupts the write by calling stop or pause, or an I/O error occurs during the write, then the write may return a short transfer count.

In static buffer mode, copies the data to the buffer starting at offset 0, and the write mode is ignored. Note that the actual playback of this data might occur after this function returns.

Parameters
audioData byte: the array that holds the data to play.
offsetInBytes int: the offset expressed in bytes in audioData where the data to write starts. Must not be negative, or cause the data access to go out of bounds of the array.
sizeInBytes int: the number of bytes to write in audioData after the offset. Must not be negative, or cause the data access to go out of bounds of the array.
writeMode int: one of WRITE_BLOCKING, WRITE_NON_BLOCKING. It has no effect in static mode.
With WRITE_BLOCKING, the write will block until all data has been written to the audio sink.
With WRITE_NON_BLOCKING, the write will return immediately after queuing as much audio data for playback as possible without blocking.
Returns
int zero or the positive number of bytes that were written, or one of the following error codes. The number of bytes will be a multiple of the frame size in bytes not to exceed sizeInBytes.
  • ERROR_INVALID_OPERATION if the track isn't properly initialized
  • ERROR_BAD_VALUE if the parameters don't resolve to valid data and indexes
  • ERROR_DEAD_OBJECT if the AudioTrack is not valid anymore and needs to be recreated. The dead object error code is not returned if some data was successfully transferred. In this case, the error is returned at the next write()
  • ERROR in case of other error

Protected methods

finalize

Added in API level 3
void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the JavaTM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.

getNativeFrameCount

Added in API level 3
int getNativeFrameCount ()

This method was deprecated in API level 19.
Use the identical public method getBufferSizeInFrames() instead.

Returns the frame count of the native AudioTrack buffer.

Returns
int current size in frames of the AudioTrack buffer.
Throws
IllegalStateException

setState

Added in API level 3
void setState (int state)

This method was deprecated in API level 19.
Only accessible by subclasses, which are not recommended for AudioTrack.

Sets the initialization state of the instance. This method was originally intended to be used in an AudioTrack subclass constructor to set a subclass-specific post-initialization state. However, subclasses of AudioTrack are no longer recommended, so this method is obsolete.

Parameters
state int: the state of the AudioTrack instance
This site uses cookies to store your preferences for site-specific language and display options.

Hooray!

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a one-minute survey?
Help us improve Android tools and documentation.