Interface AudioSource

All Superinterfaces:
Audio, Comparable<NamedBean>, NamedBean, PropertyChangeProvider
All Known Implementing Classes:
AbstractAudioSource, JavaSoundAudioSource, JoalAudioSource, NullAudioSource

public interface AudioSource
extends Audio
Represent an AudioSource, a place to store or control sound information.

The AbstractAudio class contains a basic implementation of the state and messaging code, and forms a useful start for a system-specific implementation. Specific implementations in the jmrix package, e.g. for LocoNet and NCE, will convert to and from the layout commands.

The states and names are Java Bean parameters, so that listeners can be registered to be notified of any changes.

Each AudioSource object has a two names. The "user" name is entirely free form, and can be used for any purpose. The "system" name is provided by the system-specific implementations, and provides a unique mapping to the layout control system (for example LocoNet or NCE) and address within that system.


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.

  • Field Details

  • Method Details

    • setPosition

      void setPosition​(Vector3f pos)
      Sets the position of this AudioSource object

      Applies only to sub-types:

      • Listener
      • Source
      Parameters:
      pos - 3d position vector
    • setPosition

      void setPosition​(float x, float y, float z)
      Sets the position of this AudioSource object in x, y and z planes

      Applies only to sub-types:

      • Listener
      • Source
      Parameters:
      x - x-coordinate
      y - y-coordinate
      z - z-coordinate
    • setPosition

      void setPosition​(float x, float y)
      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
      Parameters:
      x - x-coordinate
      y - y-coordinate
    • getPosition

      Returns the position of this AudioSource object as a 3-dimensional vector.

      Applies only to sub-types:

      • Listener
      • Source
      Returns:
      3d position vector
    • getCurrentPosition

      Returns the current position of this AudioSource object as a 3-dimensional vector.

      Applies only to sub-types:

      • Listener
      • Source
      Returns:
      3d position vector
    • resetCurrentPosition

      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
    • setPositionRelative

      void setPositionRelative​(boolean relative)
      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
      Parameters:
      relative - position relative or absolute
    • isPositionRelative

      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
      Returns:
      boolean position relative
    • setVelocity

      void setVelocity​(Vector3f vel)
      Sets the velocity of this AudioSource object

      Applies only to sub-types:

      • Listener
      • Source
      Parameters:
      vel - 3d velocity vector
    • getVelocity

      Returns the velocity of this AudioSource object

      Applies only to sub-types:

      • Listener
      • Source
      Returns:
      3d velocity vector
    • getAssignedBuffer

      Returns linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Returns:
      AudioBuffer the AudioBuffer object bound to this AudioSource
    • getAssignedBufferName

      Return system name of linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Returns:
      sysName the SystemName of the AudioBuffer bound to this AudioSource
    • setAssignedBuffer

      void setAssignedBuffer​(AudioBuffer audioBuffer)
      Sets the linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Parameters:
      audioBuffer - the AudioBuffer object to bind to this AudioSource
    • setAssignedBuffer

      void setAssignedBuffer​(String sysName)
      Sets the system name of the linked AudioBuffer object

      Applies only to sub-types:

      • Source
      Parameters:
      sysName - the SystemName of the AudioBuffer (i.e. IAB1) to bind to this AudioSource
    • queueBuffers

      boolean queueBuffers​(Queue<AudioBuffer> audioBuffers)
      Queues the linked AudioBuffer object to this Source's buffer queue

      Applies only to sub-types:

      • Source
      Parameters:
      audioBuffers - the AudioBuffer object to enqueue to this AudioSource
      Returns:
      true if successfully queued audioBuffers; false otherwise
    • queueBuffer

      boolean queueBuffer​(AudioBuffer audioBuffer)
    • unqueueBuffers

      boolean unqueueBuffers()
    • numQueuedBuffers

    • numProcessedBuffers

    • isBound

      boolean isBound()
      Method to return if this AudioSource has been bound to an AudioBuffer

      Applies only to sub-types:

      • Source
      Returns:
      True if bound to an AudioBuffer
    • isQueued

      boolean isQueued()
      Method to return if this AudioSource has AudioBuffers queued to it

      Applies only to sub-types:

      • Source
      Returns:
      True if AudioBuffers are queued.
    • getGain

      float getGain()
      Return the currently stored gain setting

      Default value = 1.0f

      Applies only to sub-types:

      • Listener
      • Source
      Returns:
      gain setting of this AudioSource
    • setGain

      void setGain​(float gain)
      Set the gain of this AudioSource object

      Default value = 1.0f

      Applies only to sub-types:

      • Listener
      • Source
      Parameters:
      gain - the gain of this AudioSource
    • getPitch

      float getPitch()
      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
      Returns:
      pitch of this AudioSource
    • setPitch

      void setPitch​(float pitch)
      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
      Parameters:
      pitch - the pitch of this AudioSource
    • getReferenceDistance

      Return the current reference distance setting

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Returns:
      Reference Distance of this AudioSource
    • setReferenceDistance

      void setReferenceDistance​(float referenceDistance)
      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
      Parameters:
      referenceDistance - the Reference Distance for this AudioSource
    • setOffset

      void setOffset​(long offset)
      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
      Parameters:
      offset - the offset in samples marking the point to commence playback
    • getOffset

      long getOffset()
      Return the offset in which to start playback of this AudioSource.

      Default value = 0

      Applies only to sub-types:

      • Source
      Returns:
      the offset in samples marking the point to commence playback
    • getMaximumDistance

      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
      Returns:
      the maximum distance
    • setMaximumDistance

      void setMaximumDistance​(float maximumDistance)
      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
      Parameters:
      maximumDistance - maximum distance of this source
    • setRollOffFactor

      void setRollOffFactor​(float rollOffFactor)
      Set the roll-off factor of this AudioSource object.

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Parameters:
      rollOffFactor - roll-off factor
    • getRollOffFactor

      Get the roll-off factor of this AudioSource object.

      Default value = 1.0f

      Applies only to sub-types:

      • Source
      Returns:
      the roll-off factor
    • isLooped

      boolean isLooped()
      Check if this AudioSource object will loop or not.

      Applies only to sub-types:

      • Source
      Returns:
      boolean loop
    • setLooped

      void setLooped​(boolean loop)
      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
      Parameters:
      loop - infinite loop setting
    • getMinLoops

      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
      Returns:
      number of loops
    • setMinLoops

      void setMinLoops​(int loops)
      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
      Parameters:
      loops - minimum number of loops
    • getMaxLoops

      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
      Returns:
      maximum number of loops
    • setMaxLoops

      void setMaxLoops​(int loops)
      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
      Parameters:
      loops - maximum number of loops
    • getNumLoops

      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
      Returns:
      number of loops
    • setFadeIn

      void setFadeIn​(int fadeInTime)
      Set the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Parameters:
      fadeInTime - fade-in time in milliseconds
    • getFadeIn

      int getFadeIn()
      Retrieve the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Returns:
      fade-in time in milliseconds
    • setFadeOut

      void setFadeOut​(int fadeOutTime)
      Set the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Parameters:
      fadeOutTime - fade-out time in milliseconds
    • getFadeOut

      int getFadeOut()
      Retrieve the length of time in milliseconds to fade this source in

      Default value = 1000

      Applies only to sub-types:

      • Source
      Returns:
      fade-in time in milliseconds
    • setDopplerFactor

      @Deprecated default void setDopplerFactor​(float dopplerFactor)
      Deprecated.
      Set the doppler factor of this source

      Default value = 1.0f

      Only calculated for JoalAudioSources

      Applies only to sub-types:

      • Source
      Parameters:
      dopplerFactor - factor to apply in doppler calculations
    • getDopplerFactor

      @Deprecated default float getDopplerFactor()
      Deprecated.
      Retrieve the doppler factor of this source

      Default value = 1.0f

      Only calculated for JoalAudioSources

      Applies only to sub-types:

      • Source
      Returns:
      factor to apply in doppler calculations
    • play

      void play()
      Method to start playing this AudioSource Object

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

      Applies only to sub-types:

      • Source
    • stop

      void stop()
      Method to stop playing this AudioSource Object

      Applies only to sub-types:

      • Source
    • togglePlay

      void togglePlay()
      Method to toggle playback of this AudioSource Object reseting position

      Applies only to sub-types:

      • Source
    • pause

      void pause()
      Method to pause playing this AudioSource Object

      Applies only to sub-types:

      • Source
    • resume

      void resume()
      Method to resume playing this AudioSource Object

      Applies only to sub-types:

      • Source
    • togglePause

      void togglePause()
      Method to toggle playback of this AudioSource Object retaining postition

      Applies only to sub-types:

      • Source
    • rewind

      void rewind()
      Method to rewind this AudioSource Object

      Applies only to sub-types:

      • Source
    • fadeIn

      void fadeIn()
      Method to fade in and then play this AudioSource Object

      Applies only to sub-types:

      • Source
    • fadeOut

      void fadeOut()
      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
    • getDebugString

      Get debug info about this audio source. AbstractAudioSource overrides this to get more debug info. It was previously the method toString().
      Returns:
      a string with debug info or the result of the method toString()