Package jmri.jmrit.audio

Class AbstractAudioSource

java.lang.Object
jmri.implementation.AbstractNamedBean
jmri.implementation.AbstractAudio
jmri.jmrit.audio.AbstractAudioSource
All Implemented Interfaces:
Comparable<NamedBean>, Audio, PropertyChangeProvider, AudioSource, NamedBean
Direct Known Subclasses:
JavaSoundAudioSource, JoalAudioSource, NullAudioSource
public abstract class AbstractAudioSource extends AbstractAudio implements AudioSource
Base implementation of the AudioSource class.

Specific implementations will extend this base class.

This file is part of JMRI.

JMRI is free software; you can redistribute it and/or modify it under the terms of version 2 of the GNU General Public License as published by the Free Software Foundation. See the "COPYING" file for a copy of this license.

JMRI is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

  • Constructor Details

    • AbstractAudioSource

      public AbstractAudioSource(String systemName)
      Abstract constructor for new AudioSource with system name
      Parameters:
      systemName - AudioSource object system name (e.g. IAS1)

    • AbstractAudioSource

      public AbstractAudioSource(String systemName, String userName)
      Abstract constructor for new AudioSource with system name and user name
      Parameters:
      systemName - AudioSource object system name (e.g. IAS1)
      userName - AudioSource object user name

  • Method Details

    • isAudioAlive

      public boolean isAudioAlive()

    • getSubType

      public char getSubType()
      Description copied from interface: Audio
      An Audio object can represent one of a number of subtypes of object.

      This method enables us to determine which of those subtypes this particular instance is and be able to process accordingly.

      Current supported subtypes are:

      • B = Buffer
      • L = Listener
      • S = Source
      Specified by:
      getSubType in interface Audio
      Returns:
      subType char

    • queueBuffers

      public boolean queueBuffers(Queue<AudioBuffer> audioBuffers)
      Description copied from interface: AudioSource
      Queues the linked AudioBuffer object to this Source's buffer queue

      Applies only to sub-types:

      • Source
      Specified by:
      queueBuffers in interface AudioSource
      Parameters:
      audioBuffers - the AudioBuffer object to enqueue to this AudioSource
      Returns:
      true if successfully queued audioBuffers; false otherwise

    • queueBuffer

      public boolean queueBuffer(AudioBuffer audioBuffer)
      Specified by:
      queueBuffer in interface AudioSource

    • unqueueBuffers

      public boolean unqueueBuffers()
      Specified by:
      unqueueBuffers in interface AudioSource

    • getQueuedBuffers

      public Queue<AudioBuffer> getQueuedBuffers()

    • setAssignedBuffer

      public void setAssignedBuffer(AudioBuffer audioBuffer)
      Description copied from interface: AudioSource
      Sets the linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Specified by:
      setAssignedBuffer in interface AudioSource
      Parameters:
      audioBuffer - the AudioBuffer object to bind to this AudioSource

    • setAssignedBuffer

      public void setAssignedBuffer(String bufferSystemName)
      Description copied from interface: AudioSource
      Sets the system name of the linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Specified by:
      setAssignedBuffer in interface AudioSource
      Parameters:
      bufferSystemName - the SystemName of the AudioBuffer (i.e. IAB1) to bind to this AudioSource

    • getAssignedBuffer

      public AudioBuffer getAssignedBuffer()
      Description copied from interface: AudioSource
      Returns linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Specified by:
      getAssignedBuffer in interface AudioSource
      Returns:
      AudioBuffer the AudioBuffer object bound to this AudioSource

    • getAssignedBufferName

      public String getAssignedBufferName()
      Description copied from interface: AudioSource
      Return system name of linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Specified by:
      getAssignedBufferName in interface AudioSource
      Returns:
      sysName the SystemName of the AudioBuffer bound to this AudioSource

    • setPosition

      public void setPosition(javax.vecmath.Vector3f pos)
      Description copied from interface: AudioSource
      Sets the position of this AudioSource object

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      setPosition in interface AudioSource
      Parameters:
      pos - 3d position vector

    • setPosition

      public void setPosition(float x, float y, float z)
      Description copied from interface: AudioSource
      Sets the position of this AudioSource object in x, y and z planes

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      setPosition in interface AudioSource
      Parameters:
      x - x-coordinate
      y - y-coordinate
      z - z-coordinate

    • setPosition

      public void setPosition(float x, float y)
      Description copied from interface: AudioSource
      Sets the position of this AudioSource object in x and y planes with z plane position fixed at zero

      Equivalent to setPosition(x, y, 0.0f)

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      setPosition in interface AudioSource
      Parameters:
      x - x-coordinate
      y - y-coordinate

    • getPosition

      public javax.vecmath.Vector3f getPosition()
      Description copied from interface: AudioSource
      Returns the position of this AudioSource object as a 3-dimensional vector.

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      getPosition in interface AudioSource
      Returns:
      3d position vector

    • getCurrentPosition

      public javax.vecmath.Vector3f getCurrentPosition()
      Description copied from interface: AudioSource
      Returns the current position of this AudioSource object as a 3-dimensional vector.

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      getCurrentPosition in interface AudioSource
      Returns:
      3d position vector

    • setPositionRelative

      public void setPositionRelative(boolean relative)
      Description copied from interface: AudioSource
      Sets the position of this AudioSource object to be relative to the position of the AudioListener object or absolute.

      Applies only to sub-types:

      • Source
      Specified by:
      setPositionRelative in interface AudioSource
      Parameters:
      relative - position relative or absolute

    • isPositionRelative

      public boolean isPositionRelative()
      Description copied from interface: AudioSource
      Returns a boolean value that determines if the position of this AudioSource object is relative to the position of the AudioListener object or absolute.

      Applies only to sub-types:

      • Source
      Specified by:
      isPositionRelative in interface AudioSource
      Returns:
      boolean position relative

    • setVelocity

      public void setVelocity(javax.vecmath.Vector3f vel)
      Description copied from interface: AudioSource
      Sets the velocity of this AudioSource object

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      setVelocity in interface AudioSource
      Parameters:
      vel - 3d velocity vector

    • getVelocity

      public javax.vecmath.Vector3f getVelocity()
      Description copied from interface: AudioSource
      Returns the velocity of this AudioSource object

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      getVelocity in interface AudioSource
      Returns:
      3d velocity vector

    • calculateCurrentPosition

      protected void calculateCurrentPosition()
      Calculate current position based on velocity.

    • resetCurrentPosition

      public void resetCurrentPosition()
      Description copied from interface: AudioSource
      Method to reset the current position of this AudioSource object to the initial position as defined by setPosition.

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      resetCurrentPosition in interface AudioSource

    • doResetCurrentPosition

      protected void doResetCurrentPosition()
      Reset the current position.

    • changePosition

      protected abstract void changePosition(javax.vecmath.Vector3f pos)
      Change the current position of this source.
      Parameters:
      pos - new position

    • setGain

      public void setGain(float gain)
      Description copied from interface: AudioSource
      Set the gain of this AudioSource object

      Default value = 1.0f

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      setGain in interface AudioSource
      Parameters:
      gain - the gain of this AudioSource

    • getGain

      public float getGain()
      Description copied from interface: AudioSource
      Return the currently stored gain setting

      Default value = 1.0f

      Applies only to sub-types:

      • Listener
      • Source
      Specified by:
      getGain in interface AudioSource
      Returns:
      gain setting of this AudioSource

    • calculateGain

      protected abstract void calculateGain()
      Calculate the gain of this AudioSource based on distance from listener and fade levels.

    • setPitch

      public void setPitch(float pitch)
      Description copied from interface: AudioSource
      Set the pitch of this AudioSource object

      Values are restricted from 0.5f to 2.0f, i.e. half to double

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Specified by:
      setPitch in interface AudioSource
      Parameters:
      pitch - the pitch of this AudioSource

    • getPitch

      public float getPitch()
      Description copied from interface: AudioSource
      Return the current pitch setting

      Values are restricted from 0.5f to 2.0f, i.e. half to double

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Specified by:
      getPitch in interface AudioSource
      Returns:
      pitch of this AudioSource

    • setReferenceDistance

      public void setReferenceDistance(float referenceDistance)
      Description copied from interface: AudioSource
      Set the reference distance of this AudioSource object.

      Default value = 1.0f

      The Reference Distance is one of the main parameters you have for controlling the way that sounds attenuate with distance. A Source with Reference Distance set to 5 (meters) will be at maximum volume while it is within 5 metere of the listener, and start to fade out as it moves further away. At 10 meters it will be at half volume, and at 20 meters at a quarter volume, etc ...

      Applies only to sub-types:

      • Source
      Specified by:
      setReferenceDistance in interface AudioSource
      Parameters:
      referenceDistance - the Reference Distance for this AudioSource

    • getReferenceDistance

      public float getReferenceDistance()
      Description copied from interface: AudioSource
      Return the current reference distance setting

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Specified by:
      getReferenceDistance in interface AudioSource
      Returns:
      Reference Distance of this AudioSource

    • setOffset

      public void setOffset(long offset)
      Description copied from interface: AudioSource
      Set the offset in which to start playback of this AudioSource.

      Default value = 0

      Value is clamped between 0 and length of attached AudioBuffer

      Applies only to sub-types:

      • Source
      Specified by:
      setOffset in interface AudioSource
      Parameters:
      offset - the offset in samples marking the point to commence playback

    • getOffset

      public long getOffset()
      Description copied from interface: AudioSource
      Return the offset in which to start playback of this AudioSource.

      Default value = 0

      Applies only to sub-types:

      • Source
      Specified by:
      getOffset in interface AudioSource
      Returns:
      the offset in samples marking the point to commence playback

    • setMaximumDistance

      public void setMaximumDistance(float maximumDistance)
      Description copied from interface: AudioSource
      Set the current maximum distance setting.

      Default value = Audio.MAX_DISTANCE

      The maximum distance is that where the volume of the sound would normally be zero.

      Applies only to sub-types:

      • Source
      Specified by:
      setMaximumDistance in interface AudioSource
      Parameters:
      maximumDistance - maximum distance of this source

    • getMaximumDistance

      public float getMaximumDistance()
      Description copied from interface: AudioSource
      Return the current maximum distance setting.

      Default value = Audio.MAX_DISTANCE

      The maximum distance is that where the volume of the sound would normally be zero.

      Applies only to sub-types:

      • Source
      Specified by:
      getMaximumDistance in interface AudioSource
      Returns:
      the maximum distance

    • setRollOffFactor

      public void setRollOffFactor(float rollOffFactor)
      Description copied from interface: AudioSource
      Set the roll-off factor of this AudioSource object.

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Specified by:
      setRollOffFactor in interface AudioSource
      Parameters:
      rollOffFactor - roll-off factor

    • getRollOffFactor

      public float getRollOffFactor()
      Description copied from interface: AudioSource
      Get the roll-off factor of this AudioSource object.

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Specified by:
      getRollOffFactor in interface AudioSource
      Returns:
      the roll-off factor

    • setLooped

      public void setLooped(boolean loop)
      Description copied from interface: AudioSource
      Sets this AudioSource object to loop infinitely or not.

      When loop == false, sets the min and max number of loops to zero.

      Applies only to sub-types:

      • Source
      Specified by:
      setLooped in interface AudioSource
      Parameters:
      loop - infinite loop setting

    • isLooped

      public boolean isLooped()
      Description copied from interface: AudioSource
      Check if this AudioSource object will loop or not.

      Applies only to sub-types:

      • Source
      Specified by:
      isLooped in interface AudioSource
      Returns:
      boolean loop

    • setMinLoops

      public void setMinLoops(int loops)
      Description copied from interface: AudioSource
      The minimum number of times that this AudioSource should loop.

      When set to 1, the sound will loop once (i.e. play through twice).

      When set to LOOP_CONTINUOUS, determines that this AudioSource object should loop indefinitely until explicitly stopped.

      Default value = 0

      Applies only to sub-types:

      • Source
      Specified by:
      setMinLoops in interface AudioSource
      Parameters:
      loops - minimum number of loops

    • getMinLoops

      public int getMinLoops()
      Description copied from interface: AudioSource
      Returns the minimum number of times that this AudioSource will loop, or LOOP_CONTINUOUS for infinite looping.

      Default value = 0

      Applies only to sub-types:

      • Source
      Specified by:
      getMinLoops in interface AudioSource
      Returns:
      number of loops

    • setMaxLoops

      public void setMaxLoops(int loops)
      Description copied from interface: AudioSource
      The maximum number of times that this AudioSource should loop.

      When set to 1, the sound will loop once (i.e. play through twice).

      When set to LOOP_CONTINUOUS, determines that this AudioSource object should loop indefinitely until explicitly stopped.

      Default value = 0

      Applies only to sub-types:

      • Source
      Specified by:
      setMaxLoops in interface AudioSource
      Parameters:
      loops - maximum number of loops

    • calculateLoops

      protected void calculateLoops()
      Calculate the number of times to loop playback of this sound.

    • getMaxLoops

      public int getMaxLoops()
      Description copied from interface: AudioSource
      Returns the maximum number of times that this AudioSource will loop, or LOOP_CONTINUOUS for infinite looping.

      Default value = 0

      Applies only to sub-types:

      • Source
      Specified by:
      getMaxLoops in interface AudioSource
      Returns:
      maximum number of loops

    • getNumLoops

      public int getNumLoops()
      Description copied from interface: AudioSource
      The number of times that this AudioSource should loop, or LOOP_CONTINUOUS for infinite looping.

      When the minimum and maximum number of loops are different, each call to this method will return a different random number that lies between the two settings: 

       minimum <= number of loops <= maximum
      Default value = 0

      Applies only to sub-types:

      • Source
      Specified by:
      getNumLoops in interface AudioSource
      Returns:
      number of loops

    • getLastNumLoops

      public int getLastNumLoops()
      Description copied from interface: AudioSource
      Get the last value returned by AudioSource.getNumLoops()
      Specified by:
      getLastNumLoops in interface AudioSource
      Returns:
      the number of loops

    • setFadeIn

      public void setFadeIn(int fadeInTime)
      Description copied from interface: AudioSource
      Set the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Specified by:
      setFadeIn in interface AudioSource
      Parameters:
      fadeInTime - fade-in time in milliseconds

    • getFadeIn

      public int getFadeIn()
      Description copied from interface: AudioSource
      Retrieve the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Specified by:
      getFadeIn in interface AudioSource
      Returns:
      fade-in time in milliseconds

    • setFadeOut

      public void setFadeOut(int fadeOutTime)
      Description copied from interface: AudioSource
      Set the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Specified by:
      setFadeOut in interface AudioSource
      Parameters:
      fadeOutTime - fade-out time in milliseconds

    • getFadeOut

      public int getFadeOut()
      Description copied from interface: AudioSource
      Retrieve the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Specified by:
      getFadeOut in interface AudioSource
      Returns:
      fade-in time in milliseconds

    • getFadeGain

      protected float getFadeGain()
      Used to return the current calculated fade gain for this AudioSource.
      Returns:
      current fade gain

    • calculateFades

      protected void calculateFades()
      Calculate the fade gains.

    • queueAudioBuffers

      public boolean queueAudioBuffers(Queue<AudioBuffer> audioBuffers)

    • queueAudioBuffer

      public boolean queueAudioBuffer(AudioBuffer audioBuffer)

    • unqueueAudioBuffers

      public boolean unqueueAudioBuffers()

    • numQueuedBuffers

      public int numQueuedBuffers()
      Specified by:
      numQueuedBuffers in interface AudioSource

    • numProcessedBuffers

      public int numProcessedBuffers()
      Specified by:
      numProcessedBuffers in interface AudioSource

    • bindAudioBuffer

      abstract boolean bindAudioBuffer(AudioBuffer buffer)
      Binds this AudioSource with the specified AudioBuffer.

      Applies only to sub-types:

      • Source
      Parameters:
      buffer - The AudioBuffer to bind to this AudioSource
      Returns:
      true if successful

    • setBound

      protected void setBound(boolean bound)
      Method to define if this AudioSource has been bound to an AudioBuffer.
      Parameters:
      bound - True if bound to an AudioBufferr

    • setQueued

      protected void setQueued(boolean queued)

    • isBound

      public boolean isBound()
      Description copied from interface: AudioSource
      Method to return if this AudioSource has been bound to an AudioBuffer

      Applies only to sub-types:

      • Source
      Specified by:
      isBound in interface AudioSource
      Returns:
      True if bound to an AudioBuffer

    • isQueued

      public boolean isQueued()
      Description copied from interface: AudioSource
      Method to return if this AudioSource has AudioBuffers queued to it

      Applies only to sub-types:

      • Source
      Specified by:
      isQueued in interface AudioSource
      Returns:
      True if AudioBuffers are queued.

    • stateChanged

      public void stateChanged(int oldState)
      Description copied from interface: Audio
      Method used to update the current state of the Audio object
      Specified by:
      stateChanged in interface Audio
      Parameters:
      oldState - the former state

    • play

      public void play()
      Description copied from interface: AudioSource
      Method to start playing this AudioSource Object

      If this AudioSource is already playing, this command is ignored.

      Applies only to sub-types:

      • Source
      Specified by:
      play in interface AudioSource

    • doPlay

      protected abstract void doPlay()
      Play the clip from the beginning. If looped, start looping.

    • stop

      public void stop()
      Description copied from interface: AudioSource
      Method to stop playing this AudioSource Object

      Applies only to sub-types:

      • Source
      Specified by:
      stop in interface AudioSource

    • doStop

      protected abstract void doStop()
      Stop playing the clip and rewind to the beginning.

    • togglePlay

      public void togglePlay()
      Description copied from interface: AudioSource
      Method to toggle playback of this AudioSource Object reseting position

      Applies only to sub-types:

      • Source
      Specified by:
      togglePlay in interface AudioSource

    • doTogglePlay

      protected void doTogglePlay()
      Toggle the current playing status. Will always start at/return to the beginning of the sample.

    • pause

      public void pause()
      Description copied from interface: AudioSource
      Method to pause playing this AudioSource Object

      Applies only to sub-types:

      • Source
      Specified by:
      pause in interface AudioSource

    • doPause

      protected abstract void doPause()
      Stop playing the clip but retain the current position.

    • resume

      public void resume()
      Description copied from interface: AudioSource
      Method to resume playing this AudioSource Object

      Applies only to sub-types:

      • Source
      Specified by:
      resume in interface AudioSource

    • doResume

      protected abstract void doResume()
      Play the clip from the current position.

    • togglePause

      public void togglePause()
      Description copied from interface: AudioSource
      Method to toggle playback of this AudioSource Object retaining postition

      Applies only to sub-types:

      • Source
      Specified by:
      togglePause in interface AudioSource

    • doTogglePause

      protected void doTogglePause()
      Toggle the current playing status. Will retain the playback position of the sample.

    • rewind

      public void rewind()
      Description copied from interface: AudioSource
      Method to rewind this AudioSource Object

      Applies only to sub-types:

      • Source
      Specified by:
      rewind in interface AudioSource

    • doRewind

      protected abstract void doRewind()
      Rewind clip to the beginning.

    • fadeIn

      public void fadeIn()
      Description copied from interface: AudioSource
      Method to fade in and then play this AudioSource Object

      Applies only to sub-types:

      • Source
      Specified by:
      fadeIn in interface AudioSource

    • doFadeIn

      protected abstract void doFadeIn()
      Fade in then play this AudioSource.

    • fadeOut

      public void fadeOut()
      Description copied from interface: AudioSource
      Method to fade out and then stop this AudioSource Object only when it is already playing.

      If not playing, command is ignored.

      Applies only to sub-types:

      • Source
      Specified by:
      fadeOut in interface AudioSource

    • doFadeOut

      protected abstract void doFadeOut()
      Fade out then stop this AudioSource.

    • getFading

      protected int getFading()
      Get the current fading status.
      Returns:
      fading status

    • attachSourcesToEffects

      public int attachSourcesToEffects()
      Description copied from interface: AudioSource
      Method to attach sources to effects
      Specified by:
      attachSourcesToEffects in interface AudioSource
      Returns:
      a number code

    • detachSourcesToEffects

      public int detachSourcesToEffects()
      Description copied from interface: AudioSource
      Method to detach sources to effects
      Specified by:
      detachSourcesToEffects in interface AudioSource
      Returns:
      a number code

    • getDebugString

      @Nonnull public String getDebugString()
      Description copied from interface: AudioSource
      Get debug info about this audio source. AbstractAudioSource overrides this to get more debug info. It was previously the method toString().
      Specified by:
      getDebugString in interface AudioSource
      Returns:
      a string with debug info or the result of the method toString()