android.media
Class AudioTrack

java.lang.Object
  android.media.AudioTrack

public class AudioTrack
extends Object

The AudioTrack class manages and plays a single audio resource for Java applications. It allows to stream PCM audio buffers to the audio hardware for playback. This is be achieved by "pushing" the data to the AudioTrack object using the write(byte[], int, int) or write(short[], int, int) method. During construction, an AudioTrack object can be initialized with a given buffer. This size determines how long an AudioTrack can play before running out of data.

Nested Class Summary

static interface	AudioTrack.OnMarkerReachedListener Interface definition for a callback to be invoked when an AudioTrack has reached a notification marker set by setNotificationMarkerPosition().
static interface	AudioTrack.OnPeriodicNotificationListener Interface definition for a callback to be invoked for each periodic AudioTrack update during playback.

Field Summary

static int	ERROR Denotes a generic operation failure.
static int	ERROR_BAD_VALUE Denotes a failure due to the use of an invalid value.
static int	ERROR_INVALID_OPERATION Denotes a failure due to the improper use of a method.
protected int	mAudioFormat The encoding of the audio samples.
protected int	mChannelConfiguration The current audio channel configuration
protected int	mChannelCount The number of input audio channels (1 is mono, 2 is stereo)
protected int	mDataLoadMode The way audio is consumed by the hardware, streaming or static.
protected AudioTrack.OnMarkerReachedListener	mMarkerListener The listener the AudioTrack notifies previously set marker is reached.
protected Object	mMarkerListenerLock Lock to protect marker listener updates against event notifications
protected int	mNativeBufferSizeInBytes Size of the native audio buffer.
protected android.media.AudioTrack.NativeEventHandler	mNativeEventHandler Handler for events coming from the native code
static int	MODE_STATIC Creation mode where audio data is transferred from Java to the native layer only once before the audio starts playing.
static int	MODE_STREAM Creation mode where audio data is streamed from Java to the native layer as the audio is playing.
protected AudioTrack.OnPeriodicNotificationListener	mPeriodicListener The listener the AudioTrack notifies periodically during playback.
protected Object	mPeriodicListenerLock Lock to protect periodic listener updates against event notifications
protected int	mPlayState Indicates the play state of the AudioTrack instance
protected Object	mPlayStateLock Lock to make sure mPlayState updates are reflecting the actual state of the object.
protected int	mSampleRate The audio data sampling rate in Hz.
protected int	mState Indicates the state of the AudioTrack instance
protected int	mStreamType The type of the audio stream to play.
protected static int	NATIVE_EVENT_MARKER Event id for when the playback head has reached a previously set marker.
protected static int	NATIVE_EVENT_NEW_POS Event id for when the previously set update period has passed during playback.
static int	PLAYSTATE_PAUSED state of an AudioTrack this is paused
static int	PLAYSTATE_PLAYING state of an AudioTrack this is playing
static int	PLAYSTATE_STOPPED state of an AudioTrack this is stopped
static int	STATE_INITIALIZED State of an AudioTrack that is ready to be used.
static int	STATE_NO_STATIC_DATA State of a successfully initialized AudioTrack that uses static data, but that hasn't received that data yet.
static int	STATE_UNINITIALIZED State of an AudioTrack that was not successfully initialized upon creation
static int	SUCCESS Denotes a successful operation.

Constructor Summary

AudioTrack(int streamType, int sampleRateInHz, int channelConfig, int audioFormat, int bufferSizeInBytes, int mode)
Class constructor.

Method Summary

protected void	finalize() Is called before the object's memory is being reclaimed by the VM.
void	flush() Flushes the audio data currently queued for playback.
int	getAudioFormat() Returns the configured audio data format.
int	getChannelConfiguration() Returns the configured channel configuration.
int	getChannelCount() Returns the configured number of channels.
static float	getMaxVolume() Returns the maximum valid volume value.
static float	getMinVolume() Returns the minimum valid volume value.
protected int	getNativeFrameCount() Returns the native frame count used by the hardware
static int	getNativeOutputSampleRate() Returns the hardware output sample rate
int	getNotificationMarkerPosition()
int	getPlaybackHeadPosition()
int	getPlayState() Returns the playback state of the AudioTrack instance.
int	getPositionNotificationPeriod()
int	getSampleRate() Returns the configured audio data 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.
void	pause() Pauses the playback of the audio data.
void	play() Starts playing an AudioTrack.
void	release() Releases the native AudioTrack resources.
int	reloadStaticData() Notifies the native resource to reuse the audio data already loaded in the native layer.
int	setLoopPoints(int startInFrames, int endInFrames, int loopCount) Sets the loop points and the loop count.
void	setMarkerReachedListener(AudioTrack.OnMarkerReachedListener listener) Sets the listener the AudioTrack notifies when a previously set marker is reached.
int	setNotificationMarkerPosition(int markerInFrames)
void	setPeriodicNotificationListener(AudioTrack.OnPeriodicNotificationListener listener) Sets the listener the AudioTrack notifies periodically during playback.
int	setPlaybackHeadPosition(int positionInFrames) Sets the playback head position.
int	setPlaybackRate(int sampleRateInHz) Sets the playback sample rate for this track.
int	setPositionNotificationPeriod(int periodInFrames)
int	setStereoVolume(float leftVolume, float rightVolume) Sets the specified left/right output volume values on the AudioTrack.
void	stop() Stops playing the audio data.
int	write(byte[] audioData, int offsetInBytes, int sizeInBytes) Writes the audio data to the audio hardware for playback.
int	write(short[] audioData, int offsetInShorts, int sizeInShorts) Writes the audio data to the audio hardware for playback.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PLAYSTATE_STOPPED

public static final int PLAYSTATE_STOPPED

state of an AudioTrack this is stopped

See Also:

Constant Field Values

PLAYSTATE_PAUSED

public static final int PLAYSTATE_PAUSED

state of an AudioTrack this is paused

See Also:

Constant Field Values

PLAYSTATE_PLAYING

public static final int PLAYSTATE_PLAYING

state of an AudioTrack this is playing

See Also:

Constant Field Values

MODE_STATIC

public static final int MODE_STATIC

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

See Also:

Constant Field Values

MODE_STREAM

public static final int MODE_STREAM

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

See Also:

Constant Field Values

STATE_UNINITIALIZED

public static final int STATE_UNINITIALIZED

State of an AudioTrack that was not successfully initialized upon creation

See Also:

Constant Field Values

STATE_INITIALIZED

public static final int STATE_INITIALIZED

State of an AudioTrack that is ready to be used.

See Also:

Constant Field Values

STATE_NO_STATIC_DATA

public static final int STATE_NO_STATIC_DATA

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

See Also:

Constant Field Values

SUCCESS

public static final int SUCCESS

Denotes a successful operation.

See Also:

Constant Field Values

ERROR

public static final int ERROR

Denotes a generic operation failure.

See Also:

Constant Field Values

ERROR_BAD_VALUE

public static final int ERROR_BAD_VALUE

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

See Also:

Constant Field Values

ERROR_INVALID_OPERATION

public static final int ERROR_INVALID_OPERATION

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

See Also:

Constant Field Values

NATIVE_EVENT_MARKER

protected static final int NATIVE_EVENT_MARKER

Event id for when the playback head has reached a previously set marker.

See Also:

Constant Field Values

NATIVE_EVENT_NEW_POS

protected static final int NATIVE_EVENT_NEW_POS

Event id for when the previously set update period has passed during playback.

See Also:

Constant Field Values

mState

protected int mState

Indicates the state of the AudioTrack instance

mPlayState

protected int mPlayState

Indicates the play state of the AudioTrack instance

mPlayStateLock

protected final Object mPlayStateLock

Lock to make sure mPlayState updates are reflecting the actual state of the object.

mMarkerListener

protected AudioTrack.OnMarkerReachedListener mMarkerListener

The listener the AudioTrack notifies previously set marker is reached.

See Also:

setMarkerReachedListener(OnMarkerReachedListener)

mMarkerListenerLock

protected final Object mMarkerListenerLock

Lock to protect marker listener updates against event notifications

mPeriodicListener

protected AudioTrack.OnPeriodicNotificationListener mPeriodicListener

The listener the AudioTrack notifies periodically during playback.

See Also:

setPeriodicNotificationListener(OnPeriodicNotificationListener)

mPeriodicListenerLock

protected final Object mPeriodicListenerLock

Lock to protect periodic listener updates against event notifications

mNativeBufferSizeInBytes

protected int mNativeBufferSizeInBytes

Size of the native audio buffer.

mNativeEventHandler

protected android.media.AudioTrack.NativeEventHandler mNativeEventHandler

Handler for events coming from the native code

mSampleRate

protected int mSampleRate

The audio data sampling rate in Hz.

mChannelCount

protected int mChannelCount

The number of input audio channels (1 is mono, 2 is stereo)

mStreamType

protected int mStreamType

The type of the audio stream to play. See AudioManager.STREAM_VOICE_CALL, AudioManager.STREAM_SYSTEM, AudioManager.STREAM_RING, AudioManager.STREAM_MUSIC and AudioManager.STREAM_ALARM

mDataLoadMode

protected int mDataLoadMode

The way audio is consumed by the hardware, streaming or static.

mChannelConfiguration

protected int mChannelConfiguration

The current audio channel configuration

mAudioFormat

protected int mAudioFormat

The encoding of the audio samples.

See Also:

#AudioFormat.ENCODING_PCM_8BIT, #AudioFormat.ENCODING_PCM_16BIT

Constructor Detail

AudioTrack

public AudioTrack(int streamType,
                  int sampleRateInHz,
                  int channelConfig,
                  int audioFormat,
                  int bufferSizeInBytes,
                  int mode)
           throws IllegalArgumentException

Class constructor.

Parameters:

streamType - the type of the audio stream. See AudioSystem.STREAM_VOICE_CALL, AudioSystem.STREAM_SYSTEM, AudioSystem.STREAM_RING, AudioSystem.STREAM_MUSIC and AudioSystem.STREAM_ALARM

sampleRateInHz - the sample rate expressed in Hertz. Examples of rates are (but not limited to) 44100, 22050 and 11025.

channelConfig - describes the configuration of the audio channels. See AudioFormat.CHANNEL_CONFIGURATION_MONO and AudioFormat.CHANNEL_CONFIGURATION_STEREO

audioFormat - the format in which the audio data is represented. See AudioFormat.ENCODING_PCM_16BIT and AudioFormat.ENCODING_PCM_8BIT

bufferSizeInBytes - the total size (in bytes) of the buffer where audio data is read from for playback. If using the AudioTrack in streaming mode, you can write data into this buffer in smaller chunks than this size. If using the AudioTrack in static mode, this is the maximum size of the sound that will be played for this instance.

mode - streaming or static buffer. See MODE_STATIC and MODE_STREAM

Throws:

IllegalArgumentException

Method Detail

release

public void release()

Releases the native AudioTrack resources.

finalize

protected void finalize()

Description copied from class: Object

Is called before the object's memory is being reclaimed by the VM. This can only happen once the VM has detected, during a run of the garbage collector, that the object is no longer reachable by any thread of the running application.

The method can be used to free system resources or perform other cleanup before the object is garbage collected. The default implementation of the method is empty, which is also expected by the VM, but subclasses can override finalize() as required. Uncaught exceptions which are thrown during the execution of this method cause it to terminate immediately but are otherwise ignored.

Note that the VM does guarantee that finalize() is called at most once for any object, but it doesn't guarantee when (if at all) finalize() will be called. For example, object B's finalize() can delay the execution of object A's finalize() method and therefore it can delay the reclamation of A's memory. To be safe, use a ReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.

Overrides:

finalize in class Object

getMinVolume

public static float getMinVolume()

Returns the minimum valid volume value. Volume values set under this one will be clamped at this value.

Returns:

the minimum volume expressed as a linear attenuation.

getMaxVolume

public static float getMaxVolume()

Returns the maximum valid volume value. Volume values set above this one will be clamped at this value.

Returns:

the maximum volume expressed as a linear attenuation.

getSampleRate

public int getSampleRate()

Returns the configured audio data sample rate in Hz

getAudioFormat

public int getAudioFormat()

Returns the configured audio data format. See #AudioFormat.ENCODING_PCM_16BIT and #AudioFormat.ENCODING_PCM_8BIT.

getStreamType

public int getStreamType()

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

getChannelConfiguration

public int getChannelConfiguration()

Returns the configured channel configuration. See #AudioFormat.CHANNEL_CONFIGURATION_MONO and #AudioFormat.CHANNEL_CONFIGURATION_STEREO.

getChannelCount

public int getChannelCount()

Returns the configured number of channels.

getState

public 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 hardware resources have been acquired.

getPlayState

public int getPlayState()

Returns the playback state of the AudioTrack instance.

See Also:

AudioTrack.PLAYSTATE_STOPPED, AudioTrack.PLAYSTATE_PAUSED, AudioTrack.PLAYSTATE_PLAYING

getNativeFrameCount

protected int getNativeFrameCount()

Returns the native frame count used by the hardware

getNotificationMarkerPosition

public int getNotificationMarkerPosition()

Returns:

marker position in frames

getPositionNotificationPeriod

public int getPositionNotificationPeriod()

Returns:

update period in frames

getPlaybackHeadPosition

public int getPlaybackHeadPosition()

Returns:

playback head position in frames

getNativeOutputSampleRate

public static int getNativeOutputSampleRate()

Returns the hardware output sample rate

setMarkerReachedListener

public void setMarkerReachedListener(AudioTrack.OnMarkerReachedListener listener)

Sets the listener the AudioTrack notifies when a previously set marker is reached.

Parameters:

listener -

setPeriodicNotificationListener

public void setPeriodicNotificationListener(AudioTrack.OnPeriodicNotificationListener listener)

Sets the listener the AudioTrack notifies periodically during playback.

Parameters:

listener -

setStereoVolume

public int setStereoVolume(float leftVolume,
                           float rightVolume)
                    throws IllegalStateException

Sets the specified left/right output volume values on the AudioTrack. Values are clamped to the (getMinVolume(), getMaxVolume()) interval if outside this range.

Parameters:

leftVolume - output attenuation for the left channel. A value of 0.0f is silence, a value of 1.0f is no attenuation.

rightVolume - output attenuation for the right channel

Returns:

SUCCESS

Throws:

IllegalStateException

setPlaybackRate

public 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, not the original sampling rate of the content. Setting it to half the sample rate of the content will cause the playback to last twice as long, but will also result result in a negative pitch shift. The current implementation supports a maximum sample rate of twice the hardware output sample rate (see getNativeOutputSampleRate()). Use getSampleRate() to check the rate actually used in hardware after potential clamping.

Parameters:

sampleRateInHz -

Returns:

SUCCESS

setNotificationMarkerPosition

public int setNotificationMarkerPosition(int markerInFrames)

Parameters:

markerInFrames - marker in frames

Returns:

error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION

setPositionNotificationPeriod

public int setPositionNotificationPeriod(int periodInFrames)

Parameters:

periodInFrames - update period in frames

Returns:

error code or success, see SUCCESS, ERROR_INVALID_OPERATION

setPlaybackHeadPosition

public int setPlaybackHeadPosition(int positionInFrames)
                            throws IllegalStateException

Sets the playback head position. The track must be stopped for the position to be changed.

Parameters:

positionInFrames - playback head position in frames

Returns:

error code or success, see SUCCESS, ERROR_BAD_VALUE

Throws:

IllegalStateException - if the track is not in the PLAYSTATE_STOPPED state.

setLoopPoints

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

Sets the loop points and the loop count. The loop can be infinite.

Parameters:

startInFrames - loop start marker in frames

endInFrames - loop end marker in frames

loopCount - the number of times the loop is looped. A value of -1 means infinite looping.

Returns:

error code or success, see SUCCESS, ERROR_BAD_VALUE

play

public void play()
          throws IllegalStateException

Starts playing an AudioTrack.

Throws:

IllegalStateException

stop

public void stop()
          throws IllegalStateException

Stops playing the audio data.

Throws:

IllegalStateException

pause

public void pause()
           throws IllegalStateException

Pauses the playback of the audio data.

Throws:

IllegalStateException

flush

public void flush()
           throws IllegalStateException

Flushes the audio data currently queued for playback.

Throws:

IllegalStateException

write

public int write(byte[] audioData,
                 int offsetInBytes,
                 int sizeInBytes)
          throws IllegalStateException

Writes the audio data to the audio hardware for playback.

Parameters:

audioData - the array that holds the data to play.

offsetInBytes - the offset in audioData where the data to play starts.

sizeInBytes - the number of bytes to read in audioData after the offset.

Returns:

the number of bytes that were written.

Throws:

IllegalStateException

write

public int write(short[] audioData,
                 int offsetInShorts,
                 int sizeInShorts)
          throws IllegalStateException

Writes the audio data to the audio hardware for playback.

Parameters:

audioData - the array that holds the data to play.

offsetInShorts - the offset in audioData where the data to play starts.

sizeInShorts - the number of bytes to read in audioData after the offset.

Returns:

the number of shorts that were written.

Throws:

IllegalStateException

reloadStaticData

public int reloadStaticData()

Notifies the native resource to reuse the audio data already loaded in the native layer. This call is only valid with AudioTrack instances that don't use the streaming model.

Returns:

error code or success, see SUCCESS, ERROR_BAD_VALUE, ERROR_INVALID_OPERATION