android SoundPool api 翻译(正在进行) 播放游戏声音

最新推荐文章于 2024-09-13 17:57:30 发布

hakunamatata2008

最新推荐文章于 2024-09-13 17:57:30 发布

阅读量1.3k

点赞数

文章标签： api android 游戏 playback stream application

本文链接：https://blog.csdn.net/hakunamatata2008/article/details/6094730

版权

public class

SoundPool

extends Object

java.lang.Object
↳	android.media.SoundPool

Class Overview

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.

Summary

Nested Classes
interface	SoundPool.OnLoadCompleteListener	Interface definition for a callback to be invoked when all the sounds are loaded.

Public Constructors
	SoundPool(int maxStreams, int streamType, int srcQuality) Constructor.

Public Methods
final void	autoPause() Pause all active streams.
final void	autoResume() Resume all previously active streams.
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(String path, int priority) Load the sound from the specified path.
int	load(FileDescriptor fd, long offset, long length, int priority) Load the sound from a FileDescriptor.
final void	pause(int streamID) Pause a playback stream.
final int	play(int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate) Play a sound from a sound ID.
final void	release() Release the SoundPool resources.
final void	resume(int streamID) Resume a playback stream.
final void	setLoop(int streamID, int loop) Set loop mode.
void	setOnLoadCompleteListener(SoundPool.OnLoadCompleteListener listener) Sets the callback hook for the OnLoadCompleteListener.
final void	setPriority(int streamID, int priority) Change stream priority.
final void	setRate(int streamID, float rate) Change playback rate.
final void	setVolume(int streamID, float leftVolume, float rightVolume) Set stream volume.
final void	stop(int streamID) Stop a playback stream.
final boolean	unload(int soundID) Unload a sound from a sound ID.

Protected Methods
void	finalize() Called before the object's memory is reclaimed by the VM.

[Expand] Inherited Methods
From class java.lang.Object

Public Constructors

public SoundPool (int maxStreams, int streamType, int srcQuality)

Since: API Level 1

Constructor. Constructs a SoundPool object with the following characteristics:

Parameters

maxStreams	the maximum number of simultaneous streams for this SoundPool object
streamType	the audio stream type as described in AudioManager For example, game applications will normally use `STREAM_MUSIC`.
srcQuality	the sample-rate converter quality. Currently has no effect. Use 0 for the default.

Returns

a SoundPool object, or null if creation failed

Public Methods

public final void autoPause ()

Since: API Level 8

Pause all active streams. Pause all streams that are currently playing. This function iterates through all the active streams and pauses any that are playing. It also sets a flag so that any streams that are playing can be resumed by calling autoResume().

public final void autoResume ()

Since: API Level 8

Resume all previously active streams. Automatically resumes all streams that were paused in previous calls to autoPause().

public int load (AssetFileDescriptor afd, int priority)

Since: API Level 3

Load the sound from an asset file descriptor.

Parameters

afd	an asset file descriptor
priority	the priority of the sound. Currently has no effect. Use a value of 1 for future compatibility.

Returns

a sound ID. This value can be used to play or unload the sound.

public int load (Context context, int resId, int priority)

Since: API Level 1

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.

Parameters

context	the application context
resId	the resource ID
priority	the priority of the sound. Currently has no effect. Use a value of 1 for future compatibility.

Returns

a sound ID. This value can be used to play or unload the sound.

public int load (String path, int priority)

Since: API Level 1

Load the sound from the specified path.

Parameters

path	the path to the audio file
priority	the priority of the sound. Currently has no effect. Use a value of 1 for future compatibility.

Returns

a sound ID. This value can be used to play or unload the sound.

public int load (FileDescriptor fd, long offset, long length, int priority)

Since: API Level 3

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.

Parameters

fd	a FileDescriptor object
offset	offset to the start of the sound
length	length of the sound
priority	the priority of the sound. Currently has no effect. Use a value of 1 for future compatibility.

Returns

a sound ID. This value can be used to play or unload the sound.

public final void pause (int streamID)

Since: API Level 1

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.

Parameters

streamID	a streamID returned by the play() function

public final int play (int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate)

Since: API Level 1

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.

Parameters

soundID	a soundID returned by the load() function
leftVolume	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)

Returns

non-zero streamID if successful, zero if failed

public final void release ()

Since: API Level 1

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 void resume (int streamID)

Since: API Level 1

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.

Parameters

streamID	a streamID returned by the play() function

public final void setLoop (int streamID, int loop)

Since: API Level 1

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.

Parameters

streamID	a streamID returned by the play() function
loop	loop mode (0 = no loop, -1 = loop forever)

public void setOnLoadCompleteListener (SoundPool.OnLoadCompleteListener listener)

Since: API Level 8

soundID	a soundID returned by the load() function

Returns

true if just unloaded, false if previously unloaded

Protected Methods

protected void finalize ()

Since: API Level 1

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 aReferenceQueue, because it provides more control over the way the VM deals with references during garbage collection.