Java tutorial
/* * Copyright (C) 2007 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.media; import java.io.File; import java.io.FileDescriptor; import java.lang.ref.WeakReference; import android.annotation.NonNull; import android.annotation.Nullable; import android.app.ActivityThread; import android.app.AppOpsManager; import android.content.Context; import android.content.res.AssetFileDescriptor; import android.media.PlayerBase; import android.os.Handler; import android.os.IBinder; import android.os.Looper; import android.os.Message; import android.os.ParcelFileDescriptor; import android.os.Process; import android.os.RemoteException; import android.os.ServiceManager; import android.util.AndroidRuntimeException; import android.util.Log; /** * The SoundPool class manages and plays audio resources for applications. * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> * * <p>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.</p> */ public class SoundPool extends PlayerBase { static { System.loadLibrary("soundpool"); } // SoundPool messages // // must match SoundPool.h private static final int SAMPLE_LOADED = 1; private final static String TAG = "SoundPool"; private final static boolean DEBUG = Log.isLoggable(TAG, Log.DEBUG); private long mNativeContext; // accessed by native methods private EventHandler mEventHandler; private SoundPool.OnLoadCompleteListener mOnLoadCompleteListener; private boolean mHasAppOpsPlayAudio; private final Object mLock; private final AudioAttributes mAttributes; /** * Constructor. Constructs a SoundPool object with the following * characteristics: * * @param maxStreams the maximum number of simultaneous streams for this * SoundPool object * @param streamType the audio stream type as described in AudioManager * For example, game applications will normally use * {@link AudioManager#STREAM_MUSIC}. * @param srcQuality the sample-rate converter quality. Currently has no * effect. Use 0 for the default. * @return a SoundPool object, or null if creation failed * @deprecated use {@link SoundPool.Builder} instead to create and configure a * SoundPool instance */ public SoundPool(int maxStreams, int streamType, int srcQuality) { this(maxStreams, new AudioAttributes.Builder().setInternalLegacyStreamType(streamType).build()); PlayerBase.deprecateStreamTypeForPlayback(streamType, "SoundPool", "SoundPool()"); } private SoundPool(int maxStreams, AudioAttributes attributes) { super(attributes, AudioPlaybackConfiguration.PLAYER_TYPE_JAM_SOUNDPOOL); // do native setup if (native_setup(new WeakReference<SoundPool>(this), maxStreams, attributes) != 0) { throw new RuntimeException("Native setup failed"); } mLock = new Object(); mAttributes = attributes; baseRegisterPlayer(); } /** * 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 release() { baseRelease(); native_release(); } private native final void native_release(); protected void finalize() { release(); } /** * Load the sound from the specified path. * * @param path the path to the audio file * @param priority the priority of the sound. Currently has no effect. Use * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(String path, int priority) { int id = 0; try { File f = new File(path); ParcelFileDescriptor fd = ParcelFileDescriptor.open(f, ParcelFileDescriptor.MODE_READ_ONLY); if (fd != null) { id = _load(fd.getFileDescriptor(), 0, f.length(), priority); fd.close(); } } catch (java.io.IOException e) { Log.e(TAG, "error loading " + path); } return id; } /** * 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. * * @param context the application context * @param resId the resource ID * @param priority the priority of the sound. Currently has no effect. Use * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(Context context, int resId, int priority) { AssetFileDescriptor afd = context.getResources().openRawResourceFd(resId); int id = 0; if (afd != null) { id = _load(afd.getFileDescriptor(), afd.getStartOffset(), afd.getLength(), priority); try { afd.close(); } catch (java.io.IOException ex) { //Log.d(TAG, "close failed:", ex); } } return id; } /** * Load the sound from an asset file descriptor. * * @param afd an asset file descriptor * @param priority the priority of the sound. Currently has no effect. Use * a value of 1 for future compatibility. * @return a sound ID. This value can be used to play or unload the sound. */ public int load(AssetFileDescriptor afd, int priority) { 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; } } /** * 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. * * @param fd a FileDescriptor object * @param offset offset to the start of the sound * @param length length of the sound * @param priority the priority of the sound. Currently has no effect. Use * a value of 1 for future compatibility. * @return 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) { return _load(fd, offset, length, priority); } /** * 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. * * @param soundID a soundID returned by the load() function * @return true if just unloaded, false if previously unloaded */ public native final boolean unload(int soundID); /** * 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. * * @param soundID a soundID returned by the load() function * @param leftVolume left volume value (range = 0.0 to 1.0) * @param rightVolume right volume value (range = 0.0 to 1.0) * @param priority stream priority (0 = lowest priority) * @param loop loop mode (0 = no loop, -1 = loop forever) * @param rate playback rate (1.0 = normal playback, range 0.5 to 2.0) * @return non-zero streamID if successful, zero if failed */ public final int play(int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate) { baseStart(); return _play(soundID, leftVolume, rightVolume, priority, loop, rate); } /** * 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. * * @param streamID a streamID returned by the play() function */ public native final void pause(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. * * @param streamID a streamID returned by the play() function */ public native final void resume(int streamID); /** * 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 native final void autoPause(); /** * Resume all previously active streams. * * Automatically resumes all streams that were paused in previous * calls to autoPause(). */ public native final void autoResume(); /** * 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. * * @param streamID a streamID returned by the play() function */ public native final void stop(int streamID); /** * 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. * * @param streamID a streamID returned by the play() function * @param leftVolume left volume value (range = 0.0 to 1.0) * @param rightVolume right volume value (range = 0.0 to 1.0) */ public final void setVolume(int streamID, float leftVolume, float rightVolume) { // unlike other subclasses of PlayerBase, we are not calling // baseSetVolume(leftVolume, rightVolume) as we need to keep track of each // volume separately for each player, so we still send the command, but // handle mute/unmute separately through playerSetVolume() _setVolume(streamID, leftVolume, rightVolume); } @Override /* package */ int playerApplyVolumeShaper(@NonNull VolumeShaper.Configuration configuration, @Nullable VolumeShaper.Operation operation) { return -1; } @Override /* package */ @Nullable VolumeShaper.State playerGetVolumeShaperState(int id) { return null; } @Override void playerSetVolume(boolean muting, float leftVolume, float rightVolume) { // not used here to control the player volume directly, but used to mute/unmute _mute(muting); } @Override int playerSetAuxEffectSendLevel(boolean muting, float level) { // no aux send functionality so no-op return AudioSystem.SUCCESS; } @Override void playerStart() { // FIXME implement resuming any paused sound } @Override void playerPause() { // FIXME implement pausing any playing sound } @Override void playerStop() { // FIXME implement pausing any playing sound } /** * Similar, except set volume of all channels to same value. * @hide */ public void setVolume(int streamID, float volume) { setVolume(streamID, volume, volume); } /** * 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. * * @param streamID a streamID returned by the play() function */ public native final void setPriority(int streamID, int priority); /** * 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. * * @param streamID a streamID returned by the play() function * @param loop loop mode (0 = no loop, -1 = loop forever) */ public native final void setLoop(int streamID, int loop); /** * 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. * * @param streamID a streamID returned by the play() function * @param rate playback rate (1.0 = normal playback, range 0.5 to 2.0) */ public native final void setRate(int streamID, float rate); public interface OnLoadCompleteListener { /** * Called when a sound has completed loading. * * @param soundPool SoundPool object from the load() method * @param sampleId the sample ID of the sound loaded. * @param status the status of the load operation (0 = success) */ public void onLoadComplete(SoundPool soundPool, int sampleId, int status); } /** * Sets the callback hook for the OnLoadCompleteListener. */ public void setOnLoadCompleteListener(OnLoadCompleteListener listener) { synchronized (mLock) { if (listener != null) { // setup message handler Looper looper; if ((looper = Looper.myLooper()) != null) { mEventHandler = new EventHandler(looper); } else if ((looper = Looper.getMainLooper()) != null) { mEventHandler = new EventHandler(looper); } else { mEventHandler = null; } } else { mEventHandler = null; } mOnLoadCompleteListener = listener; } } private native final int _load(FileDescriptor fd, long offset, long length, int priority); private native final int native_setup(Object weakRef, int maxStreams, Object/*AudioAttributes*/ attributes); private native final int _play(int soundID, float leftVolume, float rightVolume, int priority, int loop, float rate); private native final void _setVolume(int streamID, float leftVolume, float rightVolume); private native final void _mute(boolean muting); // post event from native code to message handler @SuppressWarnings("unchecked") private static void postEventFromNative(Object ref, int msg, int arg1, int arg2, Object obj) { SoundPool soundPool = ((WeakReference<SoundPool>) ref).get(); if (soundPool == null) return; if (soundPool.mEventHandler != null) { Message m = soundPool.mEventHandler.obtainMessage(msg, arg1, arg2, obj); soundPool.mEventHandler.sendMessage(m); } } private final class EventHandler extends Handler { public EventHandler(Looper looper) { super(looper); } @Override public void handleMessage(Message msg) { switch (msg.what) { case SAMPLE_LOADED: if (DEBUG) Log.d(TAG, "Sample " + msg.arg1 + " loaded"); synchronized (mLock) { if (mOnLoadCompleteListener != null) { mOnLoadCompleteListener.onLoadComplete(SoundPool.this, msg.arg1, msg.arg2); } } break; default: Log.e(TAG, "Unknown message type " + msg.what); return; } } } /** * Builder class for {@link SoundPool} objects. */ public static class Builder { private int mMaxStreams = 1; private AudioAttributes mAudioAttributes; /** * Constructs a new Builder with the defaults format values. * If not provided, the maximum number of streams is 1 (see {@link #setMaxStreams(int)} to * change it), and the audio attributes have a usage value of * {@link AudioAttributes#USAGE_MEDIA} (see {@link #setAudioAttributes(AudioAttributes)} to * change them). */ public Builder() { } /** * Sets the maximum of number of simultaneous streams that can be played simultaneously. * @param maxStreams a value equal to 1 or greater. * @return the same Builder instance * @throws IllegalArgumentException */ public Builder setMaxStreams(int maxStreams) throws IllegalArgumentException { if (maxStreams <= 0) { throw new IllegalArgumentException( "Strictly positive value required for the maximum number of streams"); } mMaxStreams = maxStreams; return this; } /** * Sets the {@link AudioAttributes}. For examples, game applications will use attributes * built with usage information set to {@link AudioAttributes#USAGE_GAME}. * @param attributes a non-null * @return */ public Builder setAudioAttributes(AudioAttributes attributes) throws IllegalArgumentException { if (attributes == null) { throw new IllegalArgumentException("Invalid null AudioAttributes"); } mAudioAttributes = attributes; return this; } public SoundPool build() { if (mAudioAttributes == null) { mAudioAttributes = new AudioAttributes.Builder().setUsage(AudioAttributes.USAGE_MEDIA).build(); } return new SoundPool(mMaxStreams, mAudioAttributes); } } }