AudioTrack

Denotes a generic operation failure.

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

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

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

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

indicates AudioTrack state is paused

indicates AudioTrack state is playing

indicates AudioTrack state is stopped

State of an AudioTrack that is ready to be used.

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

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

Denotes a successful operation.

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).

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).

Class constructor.

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.

Class constructor with AudioAttributes and AudioFormat.

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

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.

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.

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

Returns the audio session ID.

Returns the frame count of the native AudioTrack buffer.

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 native 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 native 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 native AudioTrack buffer in bytes.

See also getProperty(String) for key PROPERTY_OUTPUT_FRAMES_PER_BUFFER.

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 the configured number of channels.

Returns the configured AudioTrack format.

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 the minimum buffer size required for the successful creation of an AudioTrack object to be created in the MODE_STREAM mode. 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.

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 the output sample rate in Hz for the specified stream type.

Returns marker position expressed in frames.

Returns the playback state of the AudioTrack instance.

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 the current playback parameters. See setPlaybackParams(PlaybackParams) to set playback parameters

Returns the current playback sample rate rate in Hz.

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

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 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 the configured audio data sample rate in Hz

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 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.

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.

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.

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.

Releases the native AudioTrack resources.

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.

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

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)

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.

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

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.

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.

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.

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.

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.

Sets the period for the periodic notification event.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.

Returns the frame count of the native AudioTrack buffer.

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.