com.qualcomm.ftccommon

## Class SoundPlayer

- java.lang.Object
- - com.qualcomm.ftccommon.SoundPlayer

-     public class SoundPlayer
      extends java.lang.Object

  `SoundPlayer` is a simple utility class that plays sounds on the phone. The class is used through its singleton instance.
  See Also:
    `startPlaying(Context, int)`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `SoundPlayer.CurrentlyPlaying`
    `protected static class` | `SoundPlayer.InstanceHolder`
    `protected class` | `SoundPlayer.LoadedSoundCache` `SoundPlayer.LoadedSoundCache` keeps track of loaded sounds, mapping sound resource id to loaded sound id.
    `static class` | `SoundPlayer.PlaySoundParams`
    `protected static interface` | `SoundPlayer.SoundFromFile`
    `protected class` | `SoundPlayer.SoundInfo`
    `protected static class` | `SoundPlayer.StopWhat`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected SoundPlayer.SoundInfo` | `currentlyLoadingInfo`
    `protected java.util.concurrent.CountDownLatch` | `currentlyLoadingLatch`
    `protected java.util.Set<SoundPlayer.CurrentlyPlaying>` | `currentlyPlayingSounds`
    `protected boolean` | `isRobotController`
    `protected SoundPlayer.LoadedSoundCache` | `loadedSounds`
    `protected java.lang.Object` | `lock`
    `protected float` | `masterVolume`
    `protected MediaPlayer` | `mediaSizer`
    `static int` | `msSoundTransmissionFreshness`
    `protected java.util.concurrent.ScheduledExecutorService` | `scheduledThreadPool`
    `protected SharedPreferences` | `sharedPreferences`
    `protected float` | `soundOffVolume`
    `protected float` | `soundOnVolume`
    `protected SoundPool` | `soundPool`
    `static java.lang.String` | `TAG`
    `protected java.util.concurrent.ExecutorService` | `threadPool`
    `static boolean` | `TRACE`
    `protected Tracer` | `tracer`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SoundPlayer(int simultaneousStreams, int cacheSize)` Instantiates a new sound player.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `static SoundPlayer.SoundInfo` | `addRef(SoundPlayer.SoundInfo soundInfo)`
    `void` | `close()`
    `protected static void` | `copy(java.io.InputStream inputStream, java.io.OutputStream outputStream, int cbToCopy)`
    `protected void` | `ensureCached(Context context, int resId)` Ensures this local sound is also in the local cache.
    `protected SoundPlayer.SoundInfo` | `ensureCached(java.lang.String hashString, SoundPlayer.SoundFromFile ifAbsent)` returns a new ref on the returned `SoundPlayer.SoundInfo`; caller must releaseRef()
    `protected SoundPlayer.SoundInfo` | `ensureLoaded(Context context, java.io.File file)`
    `protected SoundPlayer.SoundInfo` | `ensureLoaded(Context context, int resourceId)`
    `protected SoundPlayer.SoundInfo` | `ensureLoaded(java.lang.String hashString, SoundPlayer.SoundFromFile ifAbsent)` returns a new ref on the returned `SoundPlayer.SoundInfo`; caller must releaseRef()
    `static SoundPlayer` | `getInstance()`
    `float` | `getMasterVolume()` Returns the master volume control that is applied to all played sounds
    `protected int` | `getMsDuration(Context context, java.io.File file)`
    `protected int` | `getMsDuration(Context context, int resourceId)`
    `protected long` | `getMsNow()`
    `CallbackResult` | `handleCommandPlaySound(java.lang.String extra)`
    `CallbackResult` | `handleCommandRequestSound(Command requestSoundCommand)`
    `CallbackResult` | `handleCommandStopPlayingSounds(Command stopPlayingSoundsCommand)`
    `protected void` | `internalStopPlaying(SoundPlayer.StopWhat stopWhat)`
    `boolean` | `isLocalSoundOn()`
    `protected void` | `loadAndStartPlaying(Context context, java.io.File file, SoundPlayer.PlaySoundParams params, <any> runWhenStarted, java.lang.Runnable runWhenFinished)`
    `protected void` | `loadAndStartPlaying(Context context, int resourceId, SoundPlayer.PlaySoundParams params, <any> runWhenStarted, java.lang.Runnable runWhenFinished)`
    `void` | `onLoadComplete(SoundPool soundPool, int sampleId, int status)`
    `void` | `play(Context context, java.io.File file, float volume, int loop, float rate)`
    `void` | `play(Context context, int resId)` Deprecated. use `startPlaying(Context, int)` instead
    `void` | `play(Context context, int resId, boolean waitForCompletion)` Deprecated. use `#startPlaying(Context, int, PlaySoundParams, Consumer, Runnable)` instead
    `void` | `prefillSoundCache(int... resourceIds)` Ensures that these local sounds are also in the local cache
    `boolean` | `preload(Context context, java.io.File file)` Preloads the sound so as to to reduce delays if the sound is subsequently played.
    `boolean` | `preload(Context context, int resourceId)` Preloads the sound so as to to reduce delays if the sound is subsequently played.
    `static void` | `releaseRef(SoundPlayer.SoundInfo soundInfo)`
    `protected void` | `safeClose(java.lang.Object closeable)`
    `void` | `setMasterVolume(float masterVolume)` Sets the master volume control that is applied to all played sounds
    `void` | `startPlaying(Context context, java.io.File file)`
    `void` | `startPlaying(Context context, java.io.File file, SoundPlayer.PlaySoundParams params, <any> runWhenStarted, java.lang.Runnable runWhenFinished)`
    `void` | `startPlaying(Context context, int resId)` Asynchronously loads the indicated sound from its resource (if not already loaded), then initiates its play once any current non-looping sound is finished playing.
    `void` | `startPlaying(Context context, int resId, SoundPlayer.PlaySoundParams params, <any> runWhenStarted, java.lang.Runnable runWhenFinished)` Asynchronously loads the indicated sound from its resource (if not already loaded), then initiates its play, optionally waiting for any currently non-looping playing sounds to finish first.
    `protected void` | `startPlayingLoadedSound(SoundPlayer.SoundInfo soundInfo, SoundPlayer.PlaySoundParams paramsIn, <any> runWhenStarted, java.lang.Runnable runWhenFinished)`
    `void` | `stopPlayingAll()` Stops playing all sounds that are currently playing
    `void` | `stopPlayingLoops()` Stops playing all sounds that are currently playing in a loop
    `protected void` | `waitForLoadCompletion()`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### TAG

          public static final java.lang.String TAG

      See Also:
        Constant Field Values

    - #### TRACE

          public static boolean TRACE

    - #### tracer

          protected Tracer tracer

    - #### msSoundTransmissionFreshness

          public static final int msSoundTransmissionFreshness

      See Also:
        Constant Field Values

    - #### lock

          protected final java.lang.Object lock

    - #### isRobotController

          protected final boolean isRobotController

    - #### soundPool

          protected SoundPool soundPool

    - #### currentlyLoadingLatch

          protected java.util.concurrent.CountDownLatch currentlyLoadingLatch

    - #### currentlyLoadingInfo

          protected SoundPlayer.SoundInfo currentlyLoadingInfo

    - #### loadedSounds

          protected SoundPlayer.LoadedSoundCache loadedSounds

    - #### threadPool

          protected java.util.concurrent.ExecutorService threadPool

    - #### scheduledThreadPool

          protected java.util.concurrent.ScheduledExecutorService scheduledThreadPool

    - #### sharedPreferences

          protected SharedPreferences sharedPreferences

    - #### soundOnVolume

          protected float soundOnVolume

    - #### soundOffVolume

          protected float soundOffVolume

    - #### masterVolume

          protected float masterVolume

    - #### mediaSizer

          protected MediaPlayer mediaSizer

    - #### currentlyPlayingSounds

          protected java.util.Set<SoundPlayer.CurrentlyPlaying> currentlyPlayingSounds

  - ### Constructor Detail

    - #### SoundPlayer

          public SoundPlayer(int simultaneousStreams,
                             int cacheSize)

      Instantiates a new sound player.
      Parameters:
        `simultaneousStreams` - the number of sounds that can simultaneously play from this player. If one, then playing any new sound interrupts the playing of a a previous sound
        `cacheSize` - the maximum size of the cache of loaded sounds.

  - ### Method Detail

    - #### getInstance

          public static SoundPlayer getInstance()

    - #### close

          public void close()

    - #### prefillSoundCache

          public void prefillSoundCache(int... resourceIds)

      Ensures that these local sounds are also in the local cache

    - #### startPlaying

          public void startPlaying(Context context,
                                   int resId)

      Asynchronously loads the indicated sound from its resource (if not already loaded), then initiates its play once any current non-looping sound is finished playing.
      Parameters:
        `context` - the context in which resId is to be interpreted
        `resId` - the resource id of the raw resource containing the sound.

    - #### startPlaying

          public void startPlaying(Context context,
                                   java.io.File file)

    - #### startPlaying

          public void startPlaying(Context context,
                                   int resId,
                                   SoundPlayer.PlaySoundParams params,
                                   <any> runWhenStarted,
                                   java.lang.Runnable runWhenFinished)

      Asynchronously loads the indicated sound from its resource (if not already loaded), then initiates its play, optionally waiting for any currently non-looping playing sounds to finish first.
      Parameters:
        `context` - the context in which resId is to be interpreted
        `resId` - the resource id of the raw resource containing the sound.
        `params` - controls how the playback proceeds
        `runWhenStarted` - executed when the stream starts to play
        `runWhenFinished` - executed when the stream finishes playing

    - #### startPlaying

          public void startPlaying(Context context,
                                   java.io.File file,
                                   SoundPlayer.PlaySoundParams params,
                                   <any> runWhenStarted,
                                   java.lang.Runnable runWhenFinished)

    - #### stopPlayingAll

          public void stopPlayingAll()

      Stops playing all sounds that are currently playing

    - #### stopPlayingLoops

          public void stopPlayingLoops()

      Stops playing all sounds that are currently playing in a loop

    - #### internalStopPlaying

          protected void internalStopPlaying(SoundPlayer.StopWhat stopWhat)

    - #### preload

          public boolean preload(Context context,
                                 int resourceId)

      Preloads the sound so as to to reduce delays if the sound is subsequently played.

    - #### preload

          public boolean preload(Context context,
                                 java.io.File file)

      Preloads the sound so as to to reduce delays if the sound is subsequently played.

    - #### setMasterVolume

          public void setMasterVolume(float masterVolume)

      Sets the master volume control that is applied to all played sounds
      See Also:
        `getMasterVolume()`

    - #### getMasterVolume

          public float getMasterVolume()

      Returns the master volume control that is applied to all played sounds
      See Also:
        `setMasterVolume(float)`

    - #### play

          @Deprecated
          public void play(Context context,
                                       int resId)

      Deprecated. use `startPlaying(Context, int)` instead

    - #### play

          @Deprecated
          public void play(Context context,
                                       int resId,
                                       boolean waitForCompletion)

      Deprecated. use `#startPlaying(Context, int, PlaySoundParams, Consumer, Runnable)` instead

    - #### loadAndStartPlaying

          protected void loadAndStartPlaying(Context context,
                                             int resourceId,
                                             SoundPlayer.PlaySoundParams params,
                                             <any> runWhenStarted,
                                             java.lang.Runnable runWhenFinished)

    - #### loadAndStartPlaying

          protected void loadAndStartPlaying(Context context,
                                             java.io.File file,
                                             SoundPlayer.PlaySoundParams params,
                                             <any> runWhenStarted,
                                             java.lang.Runnable runWhenFinished)

    - #### ensureLoaded

          protected SoundPlayer.SoundInfo ensureLoaded(Context context,
                                                       int resourceId)

    - #### ensureLoaded

          protected SoundPlayer.SoundInfo ensureLoaded(Context context,
                                                       java.io.File file)

    - #### isLocalSoundOn

          public boolean isLocalSoundOn()

    - #### startPlayingLoadedSound

          protected void startPlayingLoadedSound(SoundPlayer.SoundInfo soundInfo,
                                                 SoundPlayer.PlaySoundParams paramsIn,
                                                 <any> runWhenStarted,
                                                 java.lang.Runnable runWhenFinished)

    - #### getMsDuration

          protected int getMsDuration(Context context,
                                      int resourceId)

    - #### getMsDuration

          protected int getMsDuration(Context context,
                                      java.io.File file)

    - #### waitForLoadCompletion

          protected void waitForLoadCompletion()

    - #### onLoadComplete

          public void onLoadComplete(SoundPool soundPool,
                                     int sampleId,
                                     int status)

    - #### getMsNow

          protected long getMsNow()

    - #### ensureLoaded

          protected SoundPlayer.SoundInfo ensureLoaded(java.lang.String hashString,
                                                       SoundPlayer.SoundFromFile ifAbsent)

      returns a new ref on the returned `SoundPlayer.SoundInfo`; caller must releaseRef()

    - #### ensureCached

          protected void ensureCached(Context context,
                                      int resId)

      Ensures this local sound is also in the local cache.

    - #### ensureCached

          protected SoundPlayer.SoundInfo ensureCached(java.lang.String hashString,
                                                       SoundPlayer.SoundFromFile ifAbsent)

      returns a new ref on the returned `SoundPlayer.SoundInfo`; caller must releaseRef()

    - #### handleCommandPlaySound

          public CallbackResult handleCommandPlaySound(java.lang.String extra)

    - #### handleCommandStopPlayingSounds

          public CallbackResult handleCommandStopPlayingSounds(Command stopPlayingSoundsCommand)

    - #### copy

          protected static void copy(java.io.InputStream inputStream,
                                     java.io.OutputStream outputStream,
                                     int cbToCopy)
                              throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### handleCommandRequestSound

          public CallbackResult handleCommandRequestSound(Command requestSoundCommand)

    - #### safeClose

          protected void safeClose(java.lang.Object closeable)

    - #### addRef

          public static SoundPlayer.SoundInfo addRef(SoundPlayer.SoundInfo soundInfo)

    - #### releaseRef

          public static void releaseRef(SoundPlayer.SoundInfo soundInfo)

    - #### play

          public void play(Context context,
                           java.io.File file,
                           float volume,
                           int loop,
                           float rate)