Package com.adonax.audiocue

Class AudioCue

java.lang.Object
com.adonax.audiocue.AudioCue
All Implemented Interfaces:
AudioMixerTrack, AutoCloseable
public class AudioCue extends Object implements AudioMixerTrack, AutoCloseable
The AudioCue class functions as a data line, where the audio data played directly from memory. AudioCue is modeled upon javax.sound.sampled.Clip but with additional capabilities. It can play multiple instances concurrently, and offers individual dynamic controls for volume, panning and speed for each concurrently playing instance.

An AudioCue is created using the static factory method makeAudioCue. When doing so, the media data is loaded either from a "CD Quality" wav file (44100 fps, 16-bit, stereo, little-endian) or a float array of stereo PCM normalized to the range -1 to 1, at 44100 fps. Once loaded, the media data is immutable.

AudioCue achieves concurrent playback by treating state at two levels. A distinction is made between the AudioCue which holds the audio data, and a playback instance which controls a cursor that traverses over that data and corresponds to a single sounding playback. Methods that dynamically affect playback (volume, pan, speed) operate at the instance level. When using the factory method to create an AudioCue, the maximum number of simultaneously playing instances to be supported is set, along with the data source.

An AudioCue is either open or closed. Upon opening, an output line is obtained from the system. That line will either be held directly by the AudioCue or provided indirectly by an AudioMixer, in which case 'opening' refers to the act of registering as an AudioMixerTrack with an AudioMixer. Upon closing, the AudioCue releases the system audio line, or if registered with an AudioMixer, unregisters. Opening and closing events are broadcast to registered listeners implementing the methods AudioCueListener.audioCueOpened and AudioCueListener.audioCueClosed.

The line used for output is a javax.sound.sampled.SourceDataLine. The format specified for the line is 44100 fps, 16-bit, stereo, little-endian, a format also known as "CD Quality". This format is one of the most widely supported and is the only format available for output via AudioCue. If a javax.sound.sampled.Mixer is not specified, the default behavior is to obtain the line from the system's default Mixer, with a buffer size of 1024 frames (4192 bytes). The line will be run from within a dedicated thread, with a thread priority of HIGHEST. Given that the processing of audio data usually progresses much faster than time it takes to play the media, this thread can be expected to spend most of its time in a blocked state, which allows maximizing the thread priority without impacting overall performance. An alternative Mixer, buffer length or thread priority can be specified as parameters to the open method.

An instance can either be active or not active, and, if active, can either be running or not running. Instances are initially held in a pool as 'available instances'. An instance becomes active when it is removed from that pool. Methods which remove an instance from the pool either return an int identifier or -1 if there are no available instances. An active instance can receive commands pertaining to the cursor's location in the audio data, to starting or stopping, as well as volume, pan, and speed changes, and other commands. An inactive instance can only receive a command that withdraws it from the 'available instances' pool. An instance that is running is one that is currently being played.

Each instance holds its own state variables for volume, pan and speed, cursor location, and looping. Methods are provided for changing these values. If the methods are called while the instance is not running, the new value is stored immediately and will take affect when the instance is restarted. If the instance is running, and the change is for volume, pan, or speed, the new value will be arrived at incrementally, with the increments occurring behind the scenes on a per frame basis. This is done to prevent discontinuities in the signal that might result in audible clicks. If a running instance's property is updated before the incremental changes have completed, the new target value takes precedence, and a new increment is created based on the current, in-progress value.

An instance may be played on a fire-and-forget basis, in which case it is automatically returned to the pool of available instances (active == false). Alternatively, the instance can be allowed to stay active upon completion. The behavior upon play completion is controlled by the public method setRecycleWhenDone(int, boolean), where int is the instance identifier. When a play method is called, the recycledWhenDone value is set to true by default. When obtainInstance is used, the recycledWhenDone value is set to false.

Examples: (assumes the audioCue is open) 

    // (1) Fire-and-Forget, with default values.
    audioCue.play(); // (vol = 1, pan = 0, speed = 1, loop = 0)
    // instance will be recycled upon completion.
    
    // (2) Fire-and-forget, with explicit values
    int play0 = audioCue.play(0.5, -0.75, 2, 1); 
    // will play at "half" volume, "half way" to the left pan,
    // double the speed, and will loop back and play again one time.
    // Instance will be recycled upon completion, however, the
    // play0 variable allows one to make further changes to the
    // instance if executed prior to the completion of the 
    // playback.
    
    // (3) Using obtainInstance()
    int footstep = footstepCue.obtainInstance();
    for (int i = 0; i < 10; i++) {
        // play the successive footsteps more quietly
        footstepCue.setVolume(footstep, 1 - (i * 0.1));
        // successive footsteps will travel from left to right
        footstepCue.setPan(footstep, -1 + (i * 0.2));
        // cursor must be manually placed at the beginning
        footstepCue.setFramePosition(footstep, 0);
        footstepCue.start(footstep);
        Thread.sleep(1000); // Allow time between each footstep start.
        // This assumes that the cue is shorter than 1 second in 
        // in length and each start will stop on its own.
    }
    // Another instance might be associated with a slightly 
    // different speed, for example 1.1, implying a different 
    // individual with a slightly lighter foot fall.

More extensive examples can be found in the companion github project audiocue-demo.

Since:
2.0.0
Version:
2.0.0
Author:
Philip Freihofner

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final AudioFormat
    audioFormat
    A javax.sound.sampled.AudioFormat, set to the only format used by AudioCue, also known as 'CD quality.' The type is signed PCM, with a rate of 44100 frames per second, with 16 bit encoding for each PCM value, stereo, and with the constituent bytes of each PCM value given in little-endian order.
    static final int
    DEFAULT_BUFFER_FRAMES
    A value indicating the default number of PCM frames in a buffer used in AudioCuePlayer for processing media output.
    static final Line.Info
    info
    An immutable javax.sound.sampled.Line.Info that is used when obtaining a SourceDataLine for media output.
    static final int
    PAN_STEPS
    A value indicating the number of frames over which the pan setting changes incrementally when a new pan value is given.
    static final int
    SPEED_STEPS
    A value indicating the number of frames over which the speed setting changes incrementally when a new speed value is given.
    static final int
    VOLUME_STEPS
    A value indicating the number of frames over which the volume changes incrementally when a new volume is given.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addAudioCueListener(AudioCueListener listener)
    Registers an AudioCueListener to receive notifications of events pertaining to the AudioCue and its playing or playable instances.
    void
    close()
    Releases resources allocated for media play.
    long
    getFrameLength()
    Gets the media length in sample frames.
    double
    getFramePosition(int instanceID)
    Returns the current sample frame number.
    boolean
    getIsActive(int instanceID)
    Returns true if the designated instance is active, false if not.
    boolean
    getIsPlaying(int instanceID)
    Returns true if instance is playing, false if not
    long
    getMicrosecondLength()
    Gets the media length in microseconds.
    String
    getName()
    Returns the name associated with the AudioCue.
    double
    getPan(int instanceID)
    Returns a double in the range [-1, 1] where -1 corresponds to 100% left, 1 corresponds to 100% right, and 0 corresponds to center.
    float[]
    getPcmCopy()
    Returns a copy of the signed, normalized float PCM array for this AudioCue.
    double
    getSpeed(int instanceID)
    Returns a factor indicating the current rate of play of the AudioCue instance relative to normal play.
    double
    getVolume(int instanceID)
    Returns a value indicating the current volume setting of an AudioCue instance, ranging [0..1].
    boolean
    isTrackRunning()
    Indicates if the track is or is not being included in the AudioMixer media out.
    static AudioCue
    makeStereoCue(float[] cue, String name, int polyphony)
    Creates and returns a new AudioCue.
    static AudioCue
    makeStereoCue(URL url, int polyphony)
    Creates and returns a new AudioCue.
    int
    obtainInstance()
    Obtains an int instance identifier from a pool of available instances and marks this instance as 'active'.
    void
    open()
    Readies this AudioCue for media play by instantiating, registering, and running the inner class AudioCuePlayer with default settings.
    void
    open(int bufferFrames)
    Readies this AudioCue for media play by instantiating, registering, and running the inner class AudioCuePlayer with a custom buffer size.
    void
    open(AudioMixer audioMixer)
    Registers an AudioMixer, instead of an inner class AudioCuePlayer, to handle the media play.
    void
    open(Mixer mixer, int bufferFrames, int threadPriority)
    Readies this AudioCue for media play by instantiating, registering, and running the inner class AudioCuePlayer with explicit settings for the javax.sound.sampled.Mixer, the number of PCM frames used in an internal buffer, and the priority level for the thread created to handle the media play.
    int
    play()
    Obtains an AudioCue instance and if the AudioCue has been opened, starts playing from the beginning, with default values: full volume, center pan and at normal speed, and returns an int identifying the instance, or, returns -1 if no AudioCue instance is available.
    int
    play(double volume)
    Obtains an AudioCue instance and if the AudioCue has been opened, starts playing from the beginning, at the given volume, at the default center pan, and at the default normal speed, and returns an int identifying the instance, or, returns -1 if no AudioCue instance is available.
    int
    play(double volume, double pan, double speed, int loop)
    Obtains an AudioCue instance and if the AudioCue has been opened, starts playing from the beginning, at the given volume, pan, speed and number of repetitions, and returns an int identifying the instance, or, returns -1 if no AudioCue instance is available.
    float[]
    readTrack()
    Reads one buffer of normalized audio data frames of the track.
    void
    releaseInstance(int instanceID)
    Releases an AudioCue instance, making it available as a new concurrently playing instance.
    void
    removeAudioCueListener(AudioCueListener listener)
    Removes an AudioCueListener from receiving notifications of events pertaining to the AudioCue and its playing instances.
    void
    setFractionalPosition(int instanceID, double normal)
    Repositions the play position ("play head") of the designated AudioCue instance to the frame that corresponds to the specified elapsed fractional part the total audio cue length.
    void
    setFramePosition(int instanceID, double frame)
    Sets the play position ("play head") to a specified sample frame location.
    void
    setLooping(int instanceID, int loops)
    Sets the number of times the media will restart from the beginning, after completing, or specifies infinite looping via the value -1.
    void
    setMicrosecondPosition(int instanceID, int microseconds)
    Repositions the play position ("play head") of the designated AudioCue instance to the frame that corresponds to the specified elapsed time in microseconds.
    void
    setName(String name)
    Sets the name of the AudioCue.
    void
    setPan(int instanceID, double pan)
    Sets the pan of the instance, where 100% left corresponds to -1, 100% right corresponds to 1, and center = 0.
    void
    setPanType(AudioCueFunctions.PanType panType)
    Assigns the type of panning to be used.
    void
    setRecycleWhenDone(int instanceID, boolean recycleWhenDone)
    Sets an internal flag which determines what happens when the designated instance finishes playing.
    void
    setSpeed(int instanceID, double speed)
    Sets the play speed of the AudioCue instance.
    void
    setTrackRunning(boolean trackRunning)
    Used to set whether or not this AudioMixerTrack is to be included in the AudioMixer media out.
    void
    setVolType(AudioCueFunctions.VolType volType)
    Assigns a function to map linear volume settings to volume factors used to control the sound cue's amplitude.
    void
    setVolume(int instanceID, double volume)
    Sets the volume of the instance.
    void
    start(int instanceID)
    Plays the specified AudioCue instance from its current position in the data, using existing volume, pan, and speed settings.
    void
    stop(int instanceID)
    Sends message to indicate that the playing of the instance associated with the int identifier should be halted.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • audioFormat

      public static final AudioFormat audioFormat
      A javax.sound.sampled.AudioFormat, set to the only format used by AudioCue, also known as 'CD quality.' The type is signed PCM, with a rate of 44100 frames per second, with 16 bit encoding for each PCM value, stereo, and with the constituent bytes of each PCM value given in little-endian order.

    • info

      public static final Line.Info info
      An immutable javax.sound.sampled.Line.Info that is used when obtaining a SourceDataLine for media output.

    • DEFAULT_BUFFER_FRAMES

      public static final int DEFAULT_BUFFER_FRAMES
      A value indicating the default number of PCM frames in a buffer used in AudioCuePlayer for processing media output.
      See Also:

    • VOLUME_STEPS

      public static final int VOLUME_STEPS
      A value indicating the number of frames over which the volume changes incrementally when a new volume is given.
      See Also:

    • SPEED_STEPS

      public static final int SPEED_STEPS
      A value indicating the number of frames over which the speed setting changes incrementally when a new speed value is given.
      See Also:

    • PAN_STEPS

      public static final int PAN_STEPS
      A value indicating the number of frames over which the pan setting changes incrementally when a new pan value is given.
      See Also:

  • Method Details

    • getName

      public String getName()
      Returns the name associated with the AudioCue.
      Returns:
      the name as a String

    • setName

      public void setName(String name)
      Sets the name of the AudioCue.
      Parameters:
      name - - a String to associate with this AudioCue

    • addAudioCueListener

      public void addAudioCueListener(AudioCueListener listener)
      Registers an AudioCueListener to receive notifications of events pertaining to the AudioCue and its playing or playable instances.

      Notifications occur on the thread which processes the audio signal, and includes events such as the starting, stopping, and looping of instances. Implementations of the methods that receive these notifications should be coded for brevity in order to minimize extraneous processing on the audio thread.

      Parameters:
      listener - - an object implementing the AudioCueListener interface

    • removeAudioCueListener

      public void removeAudioCueListener(AudioCueListener listener)
      Removes an AudioCueListener from receiving notifications of events pertaining to the AudioCue and its playing instances.
      Parameters:
      listener - - an object implementing the AudioCueListener interface

    • setVolType

      public void setVolType(AudioCueFunctions.VolType volType)
      Assigns a function to map linear volume settings to volume factors used to control the sound cue's amplitude.
      Parameters:
      volType - - a member of the enum AudioCue.VolType
      See Also:

    • setPanType

      public void setPanType(AudioCueFunctions.PanType panType)
      Assigns the type of panning to be used.
      Parameters:
      panType - - a member of the enum AudioCue.PanType
      See Also:

    • makeStereoCue

      public static AudioCue makeStereoCue(float[] cue, String name, int polyphony)
      Creates and returns a new AudioCue. This method allows the direct insertion of a float PCM array as an argument, where the data is presumed to be stereo signed, normalized floats with a sample rate of 44100 frames per second. The name for this cue is set by the name argument. The maximum number of concurrent playing instances is set with the polyphony argument.
      Parameters:
      cue - - a float array of audio data in "CD Quality" format, scaled to the range [-1, 1]
      name - - a String to be associated with the AudioCue
      polyphony - - an int specifying the maximum number of concurrent instances
      Returns:
      AudioCue

    • makeStereoCue

      public static AudioCue makeStereoCue(URL url, int polyphony) throws UnsupportedAudioFileException, IOException
      Creates and returns a new AudioCue. The file designated by the URL argument is loaded and held in memory. Only one format, known as "CD Quality", is supported: 44100 frames per second, 16-bit encoding, stereo, little-endian. The maximum number of concurrent playing instances is given as the polyphony argument. The file name is derived from the URL argument, but can be changed via the method setName.
      Parameters:
      url - - a URL for the source file
      polyphony - - an int specifying the maximum number of concurrent instances
      Returns:
      AudioCue
      Throws:
      UnsupportedAudioFileException - if the media being loaded is not 44100 fps, 16-bit, stereo, little-endian
      IOException - if unable to load the file

    • getPcmCopy

      public float[] getPcmCopy()
      Returns a copy of the signed, normalized float PCM array for this AudioCue.
      Returns:
      a float[] new copy of the internal array of the PCM for the AudioCue

    • open

      public void open() throws LineUnavailableException
      Readies this AudioCue for media play by instantiating, registering, and running the inner class AudioCuePlayer with default settings. Internally, the registered AudioCuePlayer instance obtains and configures a javax.sound.sampled.SourceDataLine to write to the default system javax.sound.sampled.Mixer, and will make use of the default internal buffer size of 1024 PCM frames, and will run with the default thread priority setting of 10.

      Once completed, this AudioCue is marked open and the AudioCueListener.audioCueOpened method is called on every registered AudioCueListener.

      NOTE: data can be read from an AudioCue even if it is not open. The data that is read from an unopened AudioCue will not be written to a SourceDataLine and will not be heard.

      Throws:
      IllegalStateException - if this AudioCue is already open
      LineUnavailableException - if unable to obtain a SourceDataLine for the player, which could occur if the Mixer does not support the AudioFormat implemented by AudioCue
      See Also:

    • open

      public void open(int bufferFrames) throws LineUnavailableException
      Readies this AudioCue for media play by instantiating, registering, and running the inner class AudioCuePlayer with a custom buffer size. As the performance of the AudioCuePlayer is subject to tradeoffs based upon the size of an internal buffer, a number of frames other than the default of 1024 can be specified with this method. A lower value responds more quickly to dynamic requests, but is more prone to underflow which can result in audible drop outs. The registered AudioCuePlayer instance obtains and configures a javax.sound.sampled.SourceDataLine to write to the default system javax.sound.sampled.Mixer, and will run with the default thread priority setting of 10.

      Once completed, this AudioCue is marked open and the AudioCueListener.audioCueOpened method is called on every registered AudioCueListener.

      NOTE: data can be read from an AudioCue even if it is not open. The data that is read from an unopened AudioCue will not be written to a SourceDataLine and will not be heard.

      Parameters:
      bufferFrames - - an int specifying the size of the internal buffer in PCM frames
      Throws:
      IllegalStateException - if this AudioCue is already open
      LineUnavailableException - if unable to obtain a SourceDataLine for the player, which could occur if the Mixer does not support the AudioFormat implemented by AudioCue
      See Also:

    • open

      public void open(Mixer mixer, int bufferFrames, int threadPriority) throws LineUnavailableException
      Readies this AudioCue for media play by instantiating, registering, and running the inner class AudioCuePlayer with explicit settings for the javax.sound.sampled.Mixer, the number of PCM frames used in an internal buffer, and the priority level for the thread created to handle the media play. Internally, the registered AudioCuePlayer instance obtains and configures a javax.sound.sampled.SourceDataLine to write to the provided javax.sound.sampled.Mixer rather than the default system Mixer. As the performance of the AudioCuePlayer is subject to tradeoffs based upon the size of an internal buffer, a number of frames other than the default of 1024 can be specified. A lower value responds more quickly to dynamic requests, but is more prone to underflow which can result in audible drop outs. While the default thread priority setting of 10 is generally safe given that to audio processing spending a majority of its time in a blocked state, this method allows specification of a lower priority setting.

      Once completed, this AudioCue is marked open and the audioCueOpened method is called on every registered AudioCueListener.

      NOTE: data can be read from an AudioCue even if it is not open. The data that is read from an unopened AudioCue will not be written to a SourceDataLine and will not be heard.

      Parameters:
      mixer - - a javax.sound.sampled.Mixer. If null, the system default mixer is used.
      bufferFrames - - an int specifying the size of the internal buffer in PCM frames
      threadPriority - - an int specifying the priority level of the thread, clamped to the range 1 to 10 inclusive
      Throws:
      IllegalArgumentException - if the thread priority is not in the range MIN_PRIORITY to MAX_PRIORITY.
      IllegalStateException - if this AudioCue is already open
      LineUnavailableException - if unable to obtain a SourceDataLine for the player, which could occur if the Mixer does not support the AudioFormat implemented by AudioCue
      See Also:

    • open

      public void open(AudioMixer audioMixer)
      Registers an AudioMixer, instead of an inner class AudioCuePlayer, to handle the media play. This AudioCue will be added as an AudioMixerTrack to the registered AudioMixer, and the buffer size and the thread priority of the AudioMixer will take effect for media play.

      Once completed, the AudioCue is marked open and the AudioCueListener.audioCueOpened method is called on every registered AudioCueListener.

      NOTE: data can be read from an AudioCue even if it is not open. The data that is read from an unopened AudioCue will not be written to a SourceDataLine and will not be heard.

      Parameters:
      audioMixer - - the AudioMixer that will handle media output for this AudioCue
      Throws:
      IllegalStateException - if the AudioCue is already open
      See Also:

    • close

      public void close()
      Releases resources allocated for media play. If the AudioCue was opened as a stand alone cue, its inner class AudioPlayer runnable will be allowed to end, and allocated resources will be cleaned up. If the AudioCue was opened as a track on an AudioMixer, the track will be removed from the AudioMixer.

      Once completed, the AudioCue is marked closed and the AudioCueListener.audioCueClosed method is called on every registered AudioCueListener.

      Specified by:
      close in interface AutoCloseable
      Throws:
      IllegalStateException - if player is already closed
      See Also:

    • getFrameLength

      public long getFrameLength()
      Gets the media length in sample frames.
      Returns:
      length in sample frames

    • getMicrosecondLength

      public long getMicrosecondLength()
      Gets the media length in microseconds.
      Returns:
      length in microseconds

    • obtainInstance

      public int obtainInstance()
      Obtains an int instance identifier from a pool of available instances and marks this instance as 'active'. If no playable instances are available, the method returns -1.

      The instance designated by this identifier is not automatically recycled back into the pool of available instances when it finishes playing. To put the instance back in the pool of available instances, the method releaseInstance must be called. To change the behavior so that the instance is returned to the pool when it plays completely to the end, use setRecycleWhenDone(int, boolean).

      When executed, the AudioCueListener.instanceEventOccurred method will be called with an argument of AudioCueInstanceEvent.Type.OBTAIN_INSTANCE.

      Returns:
      an int instance ID for an active instance, or -1 if no instances are available
      See Also:

    • releaseInstance

      public void releaseInstance(int instanceID)
      Releases an AudioCue instance, making it available as a new concurrently playing instance. Once released, and back in the pool of available instances, an instance cannot receive updates.

      When executed, the AudioCueListener.instanceEventOccurred method will be called with an argument of AudioCueInstanceEvent.Type.RELEASE_EVENT.

      Parameters:
      instanceID - - an int identifying the instance to be released
      See Also:

    • play

      public int play()
      Obtains an AudioCue instance and if the AudioCue has been opened, starts playing from the beginning, with default values: full volume, center pan and at normal speed, and returns an int identifying the instance, or, returns -1 if no AudioCue instance is available.

      If an AudioCue instance is available to play, the AudioCueListener.instanceEventOccurred method will be called twice, with arguments AudioCueInstanceEvent.Type.OBTAIN_INSTANCE and AudioCueInstanceEvent.Type.START_INSTANCE. This instance will be set to automatically recycle back into the pool of available instances when playing completes.

      NOTE: the play method can be called on an unopened AudioCue. If unopened, the AudioCuePlayer.readTrack method will advance the AudioCueCursor and return a buffer of PCM data when called, but will not write the data to the sound system.

      Returns:
      an int identifying the playing instance, or -1 if no instance is available
      See Also:

    • play

      public int play(double volume)
      Obtains an AudioCue instance and if the AudioCue has been opened, starts playing from the beginning, at the given volume, at the default center pan, and at the default normal speed, and returns an int identifying the instance, or, returns -1 if no AudioCue instance is available.

      If an AudioCue instance is available to play, the AudioCueListener.instanceEventOccurred method will be called twice, with arguments AudioCueInstanceEvent.Type.OBTAIN_INSTANCE and AudioCueInstanceEvent.Type.START_INSTANCE. This instance will be set to automatically recycle back into the pool of available instances when playing completes.

      NOTE: the play method can be called on an unopened AudioCue. If unopened, the AudioCuePlayer.readTrack method will advance the AudioCueCursor and return a buffer of PCM data when called, but will not write the data to the sound system.

      Parameters:
      volume - - a double in the range [0, 1]
      Returns:
      an int identifying the playing instance, or -1 if no instance is available
      See Also:

    • play

      public int play(double volume, double pan, double speed, int loop)
      Obtains an AudioCue instance and if the AudioCue has been opened, starts playing from the beginning, at the given volume, pan, speed and number of repetitions, and returns an int identifying the instance, or, returns -1 if no AudioCue instance is available.

      If an AudioCue instance is available for play back, the AudioCueListener.instanceEventOccurred method will be called twice, with arguments AudioCueInstanceEvent.Type.OBTAIN_INSTANCE and AudioCueInstanceEvent.Type.START_INSTANCE. This instance will be set to automatically recycle back into the pool of available instances when playing completes.

      NOTE: the play method can be called on an unopened AudioCue. If unopened, the AudioCuePlayer.readTrack method will advance the AudioCueCursor and return a buffer of PCM data when called, but will not write the data to the sound system.

      Parameters:
      volume - - a double within the range [0, 1]
      pan - - a double within the range [-1, 1]
      speed - - a double factor that is multiplied to the frame rate
      loop - - an int that specifies a number of additional plays (looping)
      Returns:
      an int identifying the playing instance, or -1 if no instance is available
      See Also:

    • start

      public void start(int instanceID)
      Plays the specified AudioCue instance from its current position in the data, using existing volume, pan, and speed settings.

      If an AudioCue instance is able to start, the AudioCueListener.instanceEventOccurred method will be called with the argument AudioCueInstanceEvent.Type.START_INSTANCE.

      If the AudioCue has not been opened, calls to AudioMixerTrack.readTrack() can be used to advance the cursors and produce a buffer-length float[] array of the mix of all the playing instances without sending the data on to a SourceDataLine to be heard.

      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      Throws:
      IllegalStateException - if instance is not active or if instance is already playing
      See Also:

    • stop

      public void stop(int instanceID)
      Sends message to indicate that the playing of the instance associated with the int identifier should be halted. Calling this method on an already stopped instance does nothing. The instance is left in an open state.

      The AudioCueListener.instanceEventOccurred method will be called with the argument AudioCueInstanceEvent.Type.STOP_INSTANCE.

      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      Throws:
      IllegalStateException - if instance is not active
      See Also:

    • getFramePosition

      public double getFramePosition(int instanceID)
      Returns the current sample frame number. The frame count is zero-based. The position may lie in between two frames.
      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      Returns:
      a double corresponding to the current sample frame position
      Throws:
      IllegalStateException - if instance is not active
      See Also:

    • setFramePosition

      public void setFramePosition(int instanceID, double frame)
      Sets the play position ("play head") to a specified sample frame location. The frame count is zero-based. The play position can be a fractional amount, lying between two frames.

      The input frame position will be clamped to a value that lies within or at the start or end of the media data. When the instance is next started, it will commence from this position.

      An instance cannot have its position changed if it is currently playing. An attempt to do so will throw an IllegalStateException.

      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      frame - - a double giving the frame position from which play will commence if the start method is executed
      Throws:
      IllegalStateException - if instance is not active or if the instance is playing
      See Also:

    • setMicrosecondPosition

      public void setMicrosecondPosition(int instanceID, int microseconds)
      Repositions the play position ("play head") of the designated AudioCue instance to the frame that corresponds to the specified elapsed time in microseconds. The new play position can be a fractional amount, lying between two frames.

      The input microsecond position will be clamped to a frame that lies within or is located at the start or end of the media data. When the instance is next started, it will commence from this position.

      An instance cannot have its position changed if it is currently playing. An attempt to do so will throw an IllegalStateException.

      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      microseconds - - an int in microseconds that corresponds to a position in the audio media
      Throws:
      IllegalStateException - if instance is not active or if instance is playing
      See Also:

    • setFractionalPosition

      public void setFractionalPosition(int instanceID, double normal)
      Repositions the play position ("play head") of the designated AudioCue instance to the frame that corresponds to the specified elapsed fractional part the total audio cue length. The new play position can be a fractional amount, lying between two frames.

      The fractional position argument is clamped to the range [0..1], where 1 corresponds to 100% of the media. When restarted, the instance will commence from the new sample frame position.

      An instance cannot have its position changed if it is currently playing. An attempt to do so will throw an IllegalStateException.

      Parameters:
      instanceID - - an int used to identify the AudioCue instance
      normal - - a double in the range [0..1] that corresponds to a position in the media
      Throws:
      IllegalStateException - if instance is not active or if instance is playing
      See Also:

    • getVolume

      public double getVolume(int instanceID)
      Returns a value indicating the current volume setting of an AudioCue instance, ranging [0..1].
      Parameters:
      instanceID - - an int used to identify the AudioCue instance
      Returns:
      volume factor as a double
      Throws:
      IllegalStateException - if instance is not active
      See Also:

    • setVolume

      public void setVolume(int instanceID, double volume)
      Sets the volume of the instance. Volumes can be altered while an instance is either playing or stopped. When a volume change is presented while the instance is playing, a smoothing algorithm used to prevent signal discontinuities that could result in audible clicks. If a second volume change arrives before the first change is completed, the most recent volume change takes precedence.

      Arguments are clamped to the range [0..1], with 0 denoting silence and 1 denoting the natural volume of the sample. In other words, the volume control can only diminish the volume of the media, not amplify it. Internally, the volume argument is used as a factor that is directly multiplied against the media's PCM values.

      Parameters:
      instanceID - - an int used to identify the AudioCue instance
      volume - - a float in the range [0, 1] multiplied against the audio values
      Throws:
      IllegalStateException - if instance is not active
      See Also:

    • getPan

      public double getPan(int instanceID)
      Returns a double in the range [-1, 1] where -1 corresponds to 100% left, 1 corresponds to 100% right, and 0 corresponds to center.

      The calculations used to apply the pan are determined by the PanType.

      Parameters:
      instanceID - - an int used to identify the AudioCue instance
      Returns:
      the current pan value, ranging [-1, 1]
      Throws:
      IllegalStateException - if instance is not active
      See Also:

    • setPan

      public void setPan(int instanceID, double pan)
      Sets the pan of the instance, where 100% left corresponds to -1, 100% right corresponds to 1, and center = 0. The pan setting can either be changed while a cue is either playing or stopped. If the instance is playing, a smoothing algorithm used to prevent signal discontinuities that result in audible clicks. If a second pan change arrives before the first change is completed, the most recent pan change takes precedence.

      Arguments are clamped to the range [-1, 1]. The calculations used to apply the pan are determined by the PanType.

      Parameters:
      instanceID - - an int used to identify the AudioCue instance
      pan - - a double ranging from -1 to 1
      Throws:
      IllegalStateException - if instance is not active
      See Also:

    • getSpeed

      public double getSpeed(int instanceID)
      Returns a factor indicating the current rate of play of the AudioCue instance relative to normal play.
      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      Returns:
      a float factor indicating the speed at which the AudioCue instance is being played in the range [0.125, 8]
      Throws:
      IllegalStateException - if instance is not active

    • setSpeed

      public void setSpeed(int instanceID, double speed)
      Sets the play speed of the AudioCue instance. A faster speed results in both higher-pitched frequency content and a shorter duration. Play speeds can be altered in while a cue is either playing or stopped. If the instance is playing, a smoothing algorithm used to prevent signal discontinuities. If a second speed change arrives before the first change is completed, the most recent speed change takes precedence.

      A speed of 1 will play the AudioCue instance at its originally recorded speed. A value of 2 will double the play speed, and a value of 0.5 will halve the play speed. Arguments are clamped to values ranging from 8 times slower to 8 times faster than unity, a range of [0.125, 8].

      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      speed - -a double factor ranging from 0.125 to 8
      Throws:
      IllegalStateException - if instance is not active

    • setLooping

      public void setLooping(int instanceID, int loops)
      Sets the number of times the media will restart from the beginning, after completing, or specifies infinite looping via the value -1. Note: an instance set to loop 2 times will play back a total of 3 times.
      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      loops - - an int that specifies the number of times an instance will return to the beginning and play the instance anew
      Throws:
      IllegalStateException - if instance is not active

    • setRecycleWhenDone

      public void setRecycleWhenDone(int instanceID, boolean recycleWhenDone)
      Sets an internal flag which determines what happens when the designated instance finishes playing. If true the instance will be added to the pool of available instances and will not accept updates. If false then the instance will remain available for updates.

      By default, an instance that is obtained and started via the play method automatically recycles, and an instance obtained via getInstance does not. In both cases the behavior can be changed by setting this flag.

      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      recycleWhenDone - - a boolean that designates whether to recycle the instance or not when the instance plays through to completion
      Throws:
      IllegalStateException - if the instance is not active

    • getIsActive

      public boolean getIsActive(int instanceID)
      Returns true if the designated instance is active, false if not. An active instance is one which is not in the pool of available instances, but is open to receiving commands. It may or may not be playing at any given moment.
      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      Returns:
      true if the instance is active, false if not
      See Also:

    • getIsPlaying

      public boolean getIsPlaying(int instanceID)
      Returns true if instance is playing, false if not
      Parameters:
      instanceID - - an int used to identify an AudioCue instance
      Returns:
      true if instance is playing, false if not

    • isTrackRunning

      public boolean isTrackRunning()
      Description copied from interface: AudioMixerTrack
      Indicates if the track is or is not being included in the AudioMixer media out. If the method returns true, this track is included in the mix. If false, the track is ignored, as if a 'mute' button had been pressed.
      Specified by:
      isTrackRunning in interface AudioMixerTrack
      Returns:
      true if the track is being included in the mix, otherwise false

    • setTrackRunning

      public void setTrackRunning(boolean trackRunning)
      Description copied from interface: AudioMixerTrack
      Used to set whether or not this AudioMixerTrack is to be included in the AudioMixer media out. When set to true, this AudioMixerTrack will be included in the audio mix. When set to false, this track will be ignored, and not included in the audio mix, as if a 'mute' button had been pressed.
      Specified by:
      setTrackRunning in interface AudioMixerTrack
      Parameters:
      trackRunning - - if true, this track will be included in the audio mix, if false this track will not be included

    • readTrack

      public float[] readTrack()
      Description copied from interface: AudioMixerTrack
      Reads one buffer of normalized audio data frames of the track.
      Specified by:
      readTrack in interface AudioMixerTrack
      Returns:
      one buffer of normalized audio frames