public class SoundPool extends Object
A SoundPool is a collection of samples that can be loaded into memory from a resource inside the APK or from a file in the file system. The SoundPool library uses the MediaPlayer service to decode the audio into a raw 16-bit PCM mono or stereo stream. This allows applications to ship with compressed streams without having to suffer the CPU load and latency of decompressing during playback.
In addition to low-latency playback, SoundPool can also manage the number of audio streams being rendered at once. When the SoundPool object is constructed, the maxStreams parameter sets the maximum number of streams that can be played at a time from this single SoundPool. SoundPool tracks the number of active streams. If the maximum number of streams is exceeded, SoundPool will automatically stop a previously playing stream based first on priority and then by age within that priority. Limiting the maximum number of streams helps to cap CPU loading and reducing the likelihood that audio mixing will impact visuals or UI performance.
Sounds can be looped by setting a non-zero loop value. A value of -1 causes the sound to loop forever. In this case, the application must explicitly call the stop() function to stop the sound. Any other non-zero value will cause the sound to repeat the specified number of times, e.g. a value of 3 causes the sound to play a total of 4 times.
The playback rate can also be changed. A playback rate of 1.0 causes the sound to play at its original frequency (resampled, if necessary, to the hardware output frequency). A playback rate of 2.0 causes the sound to play at twice its original frequency, and a playback rate of 0.5 causes it to play at half its original frequency. The playback rate range is 0.5 to 2.0.
Priority runs low to high, i.e. higher numbers are higher priority. Priority is used when a call to play() would cause the number of active streams to exceed the value established by the maxStreams parameter when the SoundPool was created. In this case, the stream allocator will stop the lowest priority stream. If there are multiple streams with the same low priority, it will choose the oldest stream to stop. In the case where the priority of the new stream is lower than all the active streams, the new sound will not play and the play() function will return a streamID of zero.
Let's examine a typical use case: A game consists of several levels of play. For each level, there is a set of unique sounds that are used only by that level. In this case, the game logic should create a new SoundPool object when the first level is loaded. The level data itself might contain the list of sounds to be used by this level. The loading logic iterates through the list of sounds calling the appropriate SoundPool.load() function. This should typically be done early in the process to allow time for decompressing the audio to raw PCM format before they are needed for playback.
Once the sounds are loaded and play has started, the application can trigger sounds by calling SoundPool.play(). Playing streams can be paused or resumed, and the application can also alter the pitch by adjusting the playback rate in real-time for doppler or synthesis effects.
Note that since streams can be stopped due to resource constraints, the streamID is a reference to a particular instance of a stream. If the stream is stopped to allow a higher priority stream to play, the stream is no longer be valid. However, the application is allowed to call methods on the streamID without error. This may help simplify program logic since the application need not concern itself with the stream lifecycle.
In our example, when the player has completed the level, the game logic should call SoundPool.release() to release all the native resources in use and then set the SoundPool reference to null. If the player starts another level, a new SoundPool is created, sounds are loaded, and play resumes.
Modifier and Type | Class and Description |
---|---|
static class |
SoundPool.Builder
Builder class for
SoundPool objects. |
static interface |
SoundPool.OnLoadCompleteListener |
Constructor and Description |
---|
SoundPool(int maxStreams,
int streamType,
int srcQuality)
Deprecated.
use
SoundPool.Builder instead to create and configure a
SoundPool instance |
Modifier and Type | Method and Description |
---|---|
void |
autoPause()
Pause all active streams.
|
void |
autoResume()
Resume all previously active streams.
|
protected void |
finalize()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
|
int |
load(AssetFileDescriptor afd,
int priority)
Load the sound from an asset file descriptor.
|
int |
load(Context context,
int resId,
int priority)
Load the sound from the specified APK resource.
|
int |
load(FileDescriptor fd,
long offset,
long length,
int priority)
Load the sound from a FileDescriptor.
|
int |
load(String path,
int priority)
Load the sound from the specified path.
|
void |
pause(int streamID)
Pause a playback stream.
|
int |
play(int soundID,
float leftVolume,
float rightVolume,
int priority,
int loop,
float rate)
Play a sound from a sound ID.
|
void |
release()
Release the SoundPool resources.
|
void |
resume(int streamID)
Resume a playback stream.
|
void |
setLoop(int streamID,
int loop)
Set loop mode.
|
void |
setOnLoadCompleteListener(SoundPool.OnLoadCompleteListener listener)
Sets the callback hook for the OnLoadCompleteListener.
|
void |
setPriority(int streamID,
int priority)
Change stream priority.
|
void |
setRate(int streamID,
float rate)
Change playback rate.
|
void |
setVolume(int streamID,
float volume)
Similar, except set volume of all channels to same value.
|
void |
setVolume(int streamID,
float leftVolume,
float rightVolume)
Set stream volume.
|
void |
stop(int streamID)
Stop a playback stream.
|
boolean |
unload(int soundID)
Unload a sound from a sound ID.
|
public SoundPool(int maxStreams, int streamType, int srcQuality)
SoundPool.Builder
instead to create and configure a
SoundPool instancemaxStreams
- the maximum number of simultaneous streams for this
SoundPool objectstreamType
- the audio stream type as described in AudioManager
For example, game applications will normally use
AudioManager.STREAM_MUSIC
.srcQuality
- the sample-rate converter quality. Currently has no
effect. Use 0 for the default.public final void release()
protected void finalize()
Object
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.
public int load(String path, int priority)
path
- the path to the audio filepriority
- the priority of the sound. Currently has no effect. Use
a value of 1 for future compatibility.public int load(Context context, int resId, int priority)
context
- the application contextresId
- the resource IDpriority
- the priority of the sound. Currently has no effect. Use
a value of 1 for future compatibility.public int load(AssetFileDescriptor afd, int priority)
afd
- an asset file descriptorpriority
- the priority of the sound. Currently has no effect. Use
a value of 1 for future compatibility.public int load(FileDescriptor fd, long offset, long length, int priority)
fd
- a FileDescriptor objectoffset
- offset to the start of the soundlength
- length of the soundpriority
- the priority of the sound. Currently has no effect. Use
a value of 1 for future compatibility.public final boolean unload(int soundID)
soundID
- a soundID returned by the load() functionpublic final int play(int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate)
soundID
- a soundID returned by the load() functionleftVolume
- left volume value (range = 0.0 to 1.0)rightVolume
- right volume value (range = 0.0 to 1.0)priority
- stream priority (0 = lowest priority)loop
- loop mode (0 = no loop, -1 = loop forever)rate
- playback rate (1.0 = normal playback, range 0.5 to 2.0)public final void pause(int streamID)
streamID
- a streamID returned by the play() functionpublic final void resume(int streamID)
streamID
- a streamID returned by the play() functionpublic final void autoPause()
public final void autoResume()
public final void stop(int streamID)
streamID
- a streamID returned by the play() functionpublic final void setVolume(int streamID, float leftVolume, float rightVolume)
streamID
- a streamID returned by the play() functionleftVolume
- left volume value (range = 0.0 to 1.0)rightVolume
- right volume value (range = 0.0 to 1.0)public void setVolume(int streamID, float volume)
public final void setPriority(int streamID, int priority)
streamID
- a streamID returned by the play() functionpublic final void setLoop(int streamID, int loop)
streamID
- a streamID returned by the play() functionloop
- loop mode (0 = no loop, -1 = loop forever)public final void setRate(int streamID, float rate)
streamID
- a streamID returned by the play() functionrate
- playback rate (1.0 = normal playback, range 0.5 to 2.0)public void setOnLoadCompleteListener(SoundPool.OnLoadCompleteListener listener)