Package jmri.jmrit.audio

Interface AudioSource

  • All Superinterfaces:
    Audio, java.lang.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.

    • Method Detail

      • setPosition

        void setPosition​(javax.vecmath.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

        javax.vecmath.Vector3f 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

        javax.vecmath.Vector3f 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

        void 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

        boolean 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​(javax.vecmath.Vector3f vel)
        Sets the velocity of this AudioSource object

        Applies only to sub-types:

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

      • getVelocity

        javax.vecmath.Vector3f getVelocity()
        Returns the velocity of this AudioSource object

        Applies only to sub-types:

        • Listener
        • Source
        Returns:
        3d velocity vector

      • getAssignedBuffer

        AudioBuffer getAssignedBuffer()
        Returns linked AudioBuffer object

        Applies only to sub-types:

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

      • getAssignedBufferName

        java.lang.String 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​(java.lang.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​(java.util.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

      • 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

        float 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

        float 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

        float 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

        int 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

        int 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

        int 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

      • 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

        default java.lang.String 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()