SoundPool Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
The SoundPool class manages and plays audio resources for applications.
[Android.Runtime.Register("android/media/SoundPool", DoNotGenerateAcw=true)]
public class SoundPool : Java.Lang.Object[<Android.Runtime.Register("android/media/SoundPool", DoNotGenerateAcw=true)>]
type SoundPool = class
inherit Object- Inheritance
- Attributes
Remarks
The SoundPool class manages and plays audio resources for applications.
A SoundPool is a collection of sound 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 MediaCodec service to decode the audio into raw 16-bit PCM. This allows applications to ship with compressed streams without having to suffer the CPU load and latency of decompressing during playback.
Soundpool sounds are expected to be short as they are predecoded into memory. Each decoded sound is internally limited to one megabyte storage, which represents approximately 5.6 seconds at 44.1kHz stereo (the duration is proportionally longer at lower sample rates or a channel mask of mono). A decoded audio sound will be truncated if it would exceed the per-sound one megabyte storage space.
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 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.
Java documentation for android.media.SoundPool.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Constructors
| SoundPool(Int32, Stream, Int32) |
Obsolete.
Constructor. |
| SoundPool(IntPtr, JniHandleOwnership) |
A constructor used when creating managed representations of JNI objects; called by the runtime. |
Properties
| Class |
Returns the runtime class of this |
| Handle |
The handle to the underlying Android instance. (Inherited from Object) |
| JniIdentityHashCode | (Inherited from Object) |
| JniPeerMembers | |
| PeerReference | (Inherited from Object) |
| ThresholdClass |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
| ThresholdType |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. |
Methods
| AutoPause() |
Pause all active streams. |
| AutoResume() |
Resume all previously active streams. |
| Clone() |
Creates and returns a copy of this object. (Inherited from Object) |
| Dispose() | (Inherited from Object) |
| Dispose(Boolean) | (Inherited from Object) |
| Equals(Object) |
Indicates whether some other object is "equal to" this one. (Inherited from Object) |
| GetHashCode() |
Returns a hash code value for the object. (Inherited from Object) |
| JavaFinalize() |
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object) |
| Load(AssetFileDescriptor, Int32) |
Load the sound from an asset file descriptor. |
| Load(Context, Int32, Int32) |
Load the sound from the specified APK resource. |
| Load(FileDescriptor, Int64, Int64, Int32) |
Load the sound from a FileDescriptor. |
| Load(String, Int32) |
Load the sound from the specified path. |
| LoadAsync(AssetFileDescriptor, Int32) | |
| LoadAsync(Context, Int32, Int32) | |
| LoadAsync(FileDescriptor, Int64, Int64, Int32) | |
| LoadAsync(String, Int32) | |
| Notify() |
Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object) |
| NotifyAll() |
Wakes up all threads that are waiting on this object's monitor. (Inherited from Object) |
| Pause(Int32) |
Pause a playback stream. |
| Play(Int32, Single, Single, Int32, Int32, Single) |
Play a sound from a sound ID. |
| Release() |
Release the SoundPool resources. |
| Resume(Int32) |
Resume a playback stream. |
| SetHandle(IntPtr, JniHandleOwnership) |
Sets the Handle property. (Inherited from Object) |
| SetLoop(Int32, Int32) |
Set loop mode. |
| SetOnLoadCompleteListener(SoundPool+IOnLoadCompleteListener) |
Sets the callback hook for the OnLoadCompleteListener. |
| SetPriority(Int32, Int32) |
Change stream priority. |
| SetRate(Int32, Single) |
Change playback rate. |
| SetVolume(Int32, Single, Single) |
Set stream volume. |
| Stop(Int32) |
Stop a playback stream. |
| ToArray<T>() | (Inherited from Object) |
| ToString() |
Returns a string representation of the object. (Inherited from Object) |
| Unload(Int32) |
Unload a sound from a sound ID. |
| UnregisterFromRuntime() | (Inherited from Object) |
| Wait() |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object) |
| Wait(Int64, Int32) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
| Wait(Int64) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
Events
| LoadComplete |
Explicit Interface Implementations
| IJavaPeerable.Disposed() | (Inherited from Object) |
| IJavaPeerable.DisposeUnlessReferenced() | (Inherited from Object) |
| IJavaPeerable.Finalized() | (Inherited from Object) |
| IJavaPeerable.JniManagedPeerState | (Inherited from Object) |
| IJavaPeerable.SetJniIdentityHashCode(Int32) | (Inherited from Object) |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from Object) |
| IJavaPeerable.SetPeerReference(JniObjectReference) | (Inherited from Object) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |