AudioManager.OnAudioFocusChangeListener
AudioRecord.OnRecordPositionUpdateListener
AudioTrack.OnPlaybackPositionUpdateListener
JetPlayer.OnJetEventListener
MediaPlayer.OnBufferingUpdateListener
MediaPlayer.OnCompletionListener
MediaPlayer.OnErrorListener
MediaPlayer.OnInfoListener
MediaPlayer.OnPreparedListener
MediaPlayer.OnSeekCompleteListener
MediaPlayer.OnVideoSizeChangedListener
MediaRecorder.OnErrorListener
MediaRecorder.OnInfoListener
MediaScannerConnection.MediaScannerConnectionClient
MediaScannerConnection.OnScanCompletedListener
SoundPool.OnLoadCompleteListener
Classes
AsyncPlayer
AudioFormat
AudioManager
AudioRecord
AudioTrack
CamcorderProfile
CameraProfile
ExifInterface
FaceDetector
FaceDetector.Face
JetPlayer
MediaMetadataRetriever
MediaPlayer
MediaRecorder
MediaRecorder.AudioEncoder
MediaRecorder.AudioSource
MediaRecorder.OutputFormat
MediaRecorder.VideoEncoder
MediaRecorder.VideoSource
MediaScannerConnection
Ringtone
RingtoneManager
SoundPool
ThumbnailUtils
ToneGenerator
Class Overview
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
achieved by "pushing" the data to the AudioTrack object using one of the
write(byte[], int, int)
and
write(short[], 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 is to be chosen when dealing with short sounds that fit in memory and
that need to be played with the smallest latency possible. AudioTrack instances in static mode
can play the sound without the need to transfer the audio data from Java to native layer
each time the sound is to be played. 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 hardware in chunks of
sizes inferior to the total buffer size.
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.
MODE_STATIC
Creation mode where audio data is transferred from Java to the native layer
only once before the audio starts playing.
STATE_NO_STATIC_DATA
State of a successfully initialized AudioTrack that uses static data,
but that hasn't received that data yet.
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.
getMinBufferSize
(int sampleRateInHz, int channelConfig, int audioFormat)
Returns the minimum buffer size required for the successful creation of an AudioTrack
object to be created in the
MODE_STREAM
mode.
reloadStaticData
()
Notifies the native resource to reuse the audio data already loaded in the native
layer.
setAuxEffectSendLevel
(float level)
Sets the send level of the audio track to the attached auxiliary effect
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.
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.
wait
(long millis, int nanos)
Causes the calling thread to wait until another thread calls the
notify()
or
notifyAll()
method of this object or until the
specified timeout expires.
wait
(long millis)
Causes the calling thread to wait until another thread calls the
notify()
or
notifyAll()
method of this object or until the
specified timeout expires.
the type of the audio stream. See
STREAM_VOICE_CALL
,
STREAM_SYSTEM
,
STREAM_RING
,
STREAM_MUSIC
and
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
CHANNEL_OUT_MONO
and
CHANNEL_OUT_STEREO
audioFormat
the format in which the audio data is represented.
See
ENCODING_PCM_16BIT
and
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.
See
getMinBufferSize(int, int, int)
to determine the minimum required buffer size
for the successful creation of an AudioTrack instance in streaming mode. Using values
smaller than getMinBufferSize() will result in an initialization failure.
streaming or static buffer. See
MODE_STATIC
and
MODE_STREAM
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 retreived by calling the
getAudioSessionId()
method.
If a 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.
Parameters
streamType
the type of the audio stream. See
STREAM_VOICE_CALL
,
STREAM_SYSTEM
,
STREAM_RING
,
STREAM_MUSIC
and
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
CHANNEL_OUT_MONO
and
CHANNEL_OUT_STEREO
audioFormat
the format in which the audio data is represented.
See
ENCODING_PCM_16BIT
and
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.
See
getMinBufferSize(int, int, int)
to determine the minimum required buffer size
for the successful creation of an AudioTrack instance in streaming mode. Using values
smaller than getMinBufferSize() will result in an initialization failure.
streaming or static buffer. See
MODE_STATIC
and
MODE_STREAM
sessionId
Id of audio session the AudioTrack must be attached to
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
system wide unique id of the effect to attach
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.
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.
Parameters
sampleRateInHz
the sample rate expressed in Hertz.
channelConfig
describes the configuration of the audio channels.
See
CHANNEL_OUT_MONO
and
CHANNEL_OUT_STEREO
audioFormat
the format in which the audio data is represented.
See
ENCODING_PCM_16BIT
and
ENCODING_PCM_8BIT
Returns
-
ERROR_BAD_VALUE
if an invalid parameter was passed,
or
ERROR
if the implementation was unable to query the hardware for its output
properties,
or the minimum buffer size expressed in bytes.
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.
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.
See Also
-
STATE_INITIALIZED
-
STATE_NO_STATIC_DATA
-
STATE_UNINITIALIZED
Returns the type of audio stream this AudioTrack is configured for.
Compare the result against
STREAM_VOICE_CALL
,
STREAM_SYSTEM
,
STREAM_RING
,
STREAM_MUSIC
or
STREAM_ALARM
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
Sets the send level of the audio track to the attached auxiliary effect
. The level value range is 0 to 1.0.
By default the send level is 0, 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 raw scalar. UI controls should be scaled
logarithmically: the gain applied by audio framework ranges from -72dB to 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
send level scalar
Sets the playback head position. The track must be stopped for the position to be changed.
Parameters
positionInFrames
playback head position expressed in frames
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 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
the Handler that will receive the event notification messages.
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 in a negative pitch shift.
The valid sample rate range if from 1Hz to twice the value returned by
getNativeOutputSampleRate(int)
.
Parameters
sampleRateInHz
the sample rate expressed in Hz
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
-
the number of shorts that were written or
ERROR_INVALID_OPERATION
if the object wasn't properly initialized, or
ERROR_BAD_VALUE
if
the parameters don't resolve to valid data and indexes.
Returns
-
the number of bytes that were written or
ERROR_INVALID_OPERATION
if the object wasn't properly initialized, or
ERROR_BAD_VALUE
if
the parameters don't resolve to valid data and indexes.
Called before the object's memory is reclaimed by the VM. This
can only happen once the garbage collector has detected 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.
Sets the initialization state of the instance. To be used in an AudioTrack subclass
constructor to set a subclass-specific post-initialization state.
Parameters
state
the state of the AudioTrack instance
Except as noted, this content is licensed under
Apache 2.0
.
For details and restrictions, see the
Content License
.
Android 2.3 r1 - 12 Nov 2011 9:28