SoundPoolpublic class SoundPool extends Object | The SoundPool class manages and plays audio resources for applications.
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. |
| Fields Summary |
|---|
| private static final String | TAG | | private int | mNativeContext |
| Constructors Summary |
|---|
public SoundPool(int maxStreams, int streamType, int srcQuality)Constructor. Constructs a SoundPool object with the following
characteristics: // accessed by native methods
native_setup(new WeakReference<SoundPool>(this), maxStreams, streamType, srcQuality);
|
| Methods Summary |
|---|
| private final native int | _load(java.lang.String uri, int priority)
| | private final native int | _load(java.io.FileDescriptor fd, long offset, long length, int priority)
| | protected void | finalize() release();
| | public int | load(java.lang.String path, int priority)Load the sound from the specified path.
// pass network streams to player
if (path.startsWith("http:"))
return _load(path, priority);
// try local path
int id = 0;
try {
File f = new File(path);
if (f != null) {
ParcelFileDescriptor fd = ParcelFileDescriptor.open(f, ParcelFileDescriptor.MODE_READ_ONLY);
if (fd != null) {
id = _load(fd.getFileDescriptor(), 0, f.length(), priority);
//Log.v(TAG, "close fd");
fd.close();
}
}
} catch (java.io.IOException e) {}
return id;
| | public int | load(android.content.Context context, int resId, int priority)Load the sound from the specified APK resource.
Note that the extension is dropped. For example, if you want to load
a sound from the raw resource file "explosion.mp3", you would specify
"R.raw.explosion" as the resource ID. Note that this means you cannot
have both an "explosion.wav" and an "explosion.mp3" in the res/raw
directory.
AssetFileDescriptor afd = context.getResources().openRawResourceFd(resId);
int id = 0;
if (afd != null) {
id = _load(afd.getFileDescriptor(), afd.getStartOffset(), afd.getLength(), priority);
try {
//Log.v(TAG, "close fd");
afd.close();
} catch (java.io.IOException ex) {
//Log.d(TAG, "close failed:", ex);
}
}
return id;
| | public int | load(android.content.res.AssetFileDescriptor afd, int priority)Load the sound from an asset file descriptor.
if (afd != null) {
long len = afd.getLength();
if (len < 0) {
throw new AndroidRuntimeException("no length for fd");
}
return _load(afd.getFileDescriptor(), afd.getStartOffset(), len, priority);
} else {
return 0;
}
| | public int | load(java.io.FileDescriptor fd, long offset, long length, int priority)Load the sound from a FileDescriptor.
This version is useful if you store multiple sounds in a single
binary. The offset specifies the offset from the start of the file
and the length specifies the length of the sound within the file.
return _load(fd, offset, length, priority);
| | private final native void | native_setup(java.lang.Object mediaplayer_this, int maxStreams, int streamType, int srcQuality)
| | public final native void | pause(int streamID)Pause a playback stream.
Pause the stream specified by the streamID. This is the
value returned by the play() function. If the stream is
playing, it will be paused. If the stream is not playing
(e.g. is stopped or was previously paused), calling this
function will have no effect.
| | public final native int | play(int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate)Play a sound from a sound ID.
Play the sound specified by the soundID. This is the value
returned by the load() function. Returns a non-zero streamID
if successful, zero if it fails. The streamID can be used to
further control playback. Note that calling play() may cause
another sound to stop playing if the maximum number of active
streams is exceeded. A loop value of -1 means loop forever,
a value of 0 means don't loop, other values indicate the
number of repeats, e.g. a value of 1 plays the audio twice.
The playback rate allows the application to vary the playback
rate (pitch) of the sound. A value of 1.0 means play back at
the original frequency. A value of 2.0 means play back twice
as fast, and a value of 0.5 means playback at half speed.
| | public final native void | release()Release the SoundPool resources.
Release all memory and native resources used by the SoundPool
object. The SoundPool can no longer be used and the reference
should be set to null.
| | public final native void | resume(int streamID)Resume a playback stream.
Resume the stream specified by the streamID. This
is the value returned by the play() function. If the stream
is paused, this will resume playback. If the stream was not
previously paused, calling this function will have no effect.
| | public final native void | setLoop(int streamID, int loop)Set loop mode.
Change the loop mode. A loop value of -1 means loop forever,
a value of 0 means don't loop, other values indicate the
number of repeats, e.g. a value of 1 plays the audio twice.
If the stream does not exist, it will have no effect.
| | public final native void | setPriority(int streamID, int priority)Change stream priority.
Change the priority of the stream specified by the streamID.
This is the value returned by the play() function. Affects the
order in which streams are re-used to play new sounds. If the
stream does not exist, it will have no effect.
| | public final native void | setRate(int streamID, float rate)Change playback rate.
The playback rate allows the application to vary the playback
rate (pitch) of the sound. A value of 1.0 means playback at
the original frequency. A value of 2.0 means playback twice
as fast, and a value of 0.5 means playback at half speed.
If the stream does not exist, it will have no effect.
| | public final native void | setVolume(int streamID, float leftVolume, float rightVolume)Set stream volume.
Sets the volume on the stream specified by the streamID.
This is the value returned by the play() function. The
value must be in the range of 0.0 to 1.0. If the stream does
not exist, it will have no effect.
| | public final native void | stop(int streamID)Stop a playback stream.
Stop the stream specified by the streamID. This
is the value returned by the play() function. If the stream
is playing, it will be stopped. It also releases any native
resources associated with this stream. If the stream is not
playing, it will have no effect.
| | public final native boolean | unload(int soundID)Unload a sound from a sound ID.
Unloads the sound specified by the soundID. This is the value
returned by the load() function. Returns true if the sound is
successfully unloaded, false if the sound was already unloaded.
|
|
