/*
 * 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.
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 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.
/**
 * 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:
Params:
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 AudioManager.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
Deprecated:
use Builder instead to create and configure a SoundPool instance/**
     * 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.
/**
     * 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.
Params:
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./**
     * 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.
Params:
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./**
     * 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.
Params:
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./**
     * 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.
Params:
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./**
     * 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.
Params:
soundID – a soundID returned by the load() function
Returns:
true if just unloaded, false if previously unloaded/**
     * 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.
Params:
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/**
     * 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.
Params:
streamID – a streamID returned by the play() function/**
     * 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.
Params:
streamID – a streamID returned by the play() function/**
     * 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().
/**
     * 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().
/**
     * 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.
Params:
streamID – a streamID returned by the play() function/**
     * 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.
Params:
streamID – a streamID returned by the play() function
leftVolume – left volume value (range = 0.0 to 1.0)
rightVolume – right volume value (range = 0.0 to 1.0)/**
     * 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
/**
     * 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.
Params:
streamID – a streamID returned by the play() function/**
     * 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.
Params:
streamID – a streamID returned by the play() function
loop – loop mode (0 = no loop, -1 = loop forever)/**
     * 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.
Params:
streamID – a streamID returned by the play() function
rate – playback rate (1.0 = normal playback, range 0.5 to 2.0)/**
     * 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.
Params:
soundPool – SoundPool object from the load() method
sampleId – the sample ID of the sound loaded.
status – the status of the load operation (0 = success)/**
         * 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.
/**
     * 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 SoundPool objects. /**
     * 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 setMaxStreams(int) to change it), and the audio attributes have a usage value of AudioAttributes.USAGE_MEDIA (see setAudioAttributes(AudioAttributes) to change them). /**
         * 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.
Params:
maxStreams – a value equal to 1 or greater.
Throws:
IllegalArgumentException – 
Returns:
the same Builder instance/**
         * 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 AudioAttributes. For examples, game applications will use attributes built with usage information set to AudioAttributes.USAGE_GAME. 
Params:
attributes – a non-null
Returns:
/**
         * 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);
        }
    }
}