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.
-
-
Nested Class Summary
-
Nested classes/interfaces inherited from interface jmri.NamedBean
NamedBean.BadNameException, NamedBean.BadSystemNameException, NamedBean.BadUserNameException, NamedBean.DisplayOptions, NamedBean.DuplicateSystemNameException
-
-
Field Summary
Fields Modifier and Type Field Description static int
LOOP_CONTINUOUS
Constant to define that this source should loop continously when playedstatic int
LOOP_NONE
Constant to define that this source should not loop when played-
Fields inherited from interface jmri.Audio
AT, BUFFER, CMD_BIND_BUFFER, CMD_FADE_IN, CMD_FADE_OUT, CMD_INIT_FACTORY, CMD_LOAD_SOUND, CMD_PAUSE, CMD_PAUSE_TOGGLE, CMD_PLAY, CMD_PLAY_TOGGLE, CMD_QUEUE_BUFFERS, CMD_RESET_POSITION, CMD_RESUME, CMD_REWIND, CMD_STOP, CMD_UNQUEUE_BUFFERS, DECIMAL_PLACES, FADE_IN, FADE_NONE, FADE_OUT, LISTENER, MAX_DISTANCE, SOURCE, STATE_EMPTY, STATE_INITIAL, STATE_LOADED, STATE_MOVING, STATE_PLAYING, STATE_POSITIONED, STATE_STOPPED, UP
-
Fields inherited from interface jmri.NamedBean
DISPLAY_NAME_FORMAT, INCONSISTENT, PROPERTY_STATE, QUOTED_NAME_FORMAT, UNKNOWN
-
-
Method Summary
All Methods Instance Methods Abstract Methods Default Methods Modifier and Type Method Description void
fadeIn()
Method to fade in and then play this AudioSource Objectvoid
fadeOut()
Method to fade out and then stop this AudioSource Object only when it is already playing.AudioBuffer
getAssignedBuffer()
Returns linked AudioBuffer objectjava.lang.String
getAssignedBufferName()
Return system name of linked AudioBuffer objectjavax.vecmath.Vector3f
getCurrentPosition()
Returns the current position of this AudioSource object as a 3-dimensional vector.default java.lang.String
getDebugString()
Get debug info about this audio source.int
getFadeIn()
Retrieve the length of time in milliseconds to fade this source inint
getFadeOut()
Retrieve the length of time in milliseconds to fade this source infloat
getGain()
Return the currently stored gain settingint
getLastNumLoops()
Get the last value returned bygetNumLoops()
float
getMaximumDistance()
Return the current maximum distance setting.int
getMaxLoops()
Returns the maximum number of times that this AudioSource will loop, or LOOP_CONTINUOUS for infinite looping.int
getMinLoops()
Returns the minimum number of times that this AudioSource will loop, or LOOP_CONTINUOUS for infinite looping.int
getNumLoops()
The number of times that this AudioSource should loop, or LOOP_CONTINUOUS for infinite looping.long
getOffset()
Return the offset in which to start playback of this AudioSource.float
getPitch()
Return the current pitch settingjavax.vecmath.Vector3f
getPosition()
Returns the position of this AudioSource object as a 3-dimensional vector.float
getReferenceDistance()
Return the current reference distance settingfloat
getRollOffFactor()
Get the roll-off factor of this AudioSource object.javax.vecmath.Vector3f
getVelocity()
Returns the velocity of this AudioSource objectboolean
isBound()
Method to return if this AudioSource has been bound to an AudioBufferboolean
isLooped()
Check if this AudioSource object will loop or not.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.boolean
isQueued()
Method to return if this AudioSource has AudioBuffers queued to itint
numProcessedBuffers()
int
numQueuedBuffers()
void
pause()
Method to pause playing this AudioSource Objectvoid
play()
Method to start playing this AudioSource Objectboolean
queueBuffer(AudioBuffer audioBuffer)
boolean
queueBuffers(java.util.Queue<AudioBuffer> audioBuffers)
Queues the linked AudioBuffer object to this Source's buffer queuevoid
resetCurrentPosition()
Method to reset the current position of this AudioSource object to the initial position as defined by setPosition.void
resume()
Method to resume playing this AudioSource Objectvoid
rewind()
Method to rewind this AudioSource Objectvoid
setAssignedBuffer(java.lang.String sysName)
Sets the system name of the linked AudioBuffer objectvoid
setAssignedBuffer(AudioBuffer audioBuffer)
Sets the linked AudioBuffer objectvoid
setFadeIn(int fadeInTime)
Set the length of time in milliseconds to fade this source invoid
setFadeOut(int fadeOutTime)
Set the length of time in milliseconds to fade this source invoid
setGain(float gain)
Set the gain of this AudioSource objectvoid
setLooped(boolean loop)
Sets this AudioSource object to loop infinitely or not.void
setMaximumDistance(float maximumDistance)
Set the current maximum distance setting.void
setMaxLoops(int loops)
The maximum number of times that this AudioSource should loop.void
setMinLoops(int loops)
The minimum number of times that this AudioSource should loop.void
setOffset(long offset)
Set the offset in which to start playback of this AudioSource.void
setPitch(float pitch)
Set the pitch of this AudioSource objectvoid
setPosition(float x, float y)
Sets the position of this AudioSource object in x and y planes with z plane position fixed at zerovoid
setPosition(float x, float y, float z)
Sets the position of this AudioSource object in x, y and z planesvoid
setPosition(javax.vecmath.Vector3f pos)
Sets the position of this AudioSource objectvoid
setPositionRelative(boolean relative)
Sets the position of this AudioSource object to be relative to the position of the AudioListener object or absolute.void
setReferenceDistance(float referenceDistance)
Set the reference distance of this AudioSource object.void
setRollOffFactor(float rollOffFactor)
Set the roll-off factor of this AudioSource object.void
setVelocity(javax.vecmath.Vector3f vel)
Sets the velocity of this AudioSource objectvoid
stop()
Method to stop playing this AudioSource Objectvoid
togglePause()
Method to toggle playback of this AudioSource Object retaining postitionvoid
togglePlay()
Method to toggle playback of this AudioSource Object reseting positionboolean
unqueueBuffers()
-
Methods inherited from interface jmri.Audio
getSubType, stateChanged
-
Methods inherited from interface jmri.NamedBean
addPropertyChangeListener, addPropertyChangeListener, compareSystemNameSuffix, compareTo, describeState, dispose, getBeanType, getComment, getDisplayName, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListenersByReference, getPropertyKeys, getState, getSystemName, getUsageReport, getUserName, removeProperty, setComment, setProperty, setState, setUserName, toString, updateListenerRef, vetoableChange
-
Methods inherited from interface jmri.beans.PropertyChangeProvider
addPropertyChangeListener, addPropertyChangeListener, getPropertyChangeListeners, getPropertyChangeListeners, removePropertyChangeListener, removePropertyChangeListener
-
-
-
-
Field Detail
-
LOOP_CONTINUOUS
static final int LOOP_CONTINUOUS
Constant to define that this source should loop continously when played- See Also:
- Constant Field Values
-
LOOP_NONE
static final int LOOP_NONE
Constant to define that this source should not loop when played- See Also:
- Constant Field Values
-
-
Method Detail
-
setPosition
void setPosition(javax.vecmath.Vector3f pos)
Sets the position of this AudioSource objectApplies 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 planesApplies only to sub-types:
- Listener
- Source
- Parameters:
x
- x-coordinatey
- y-coordinatez
- 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 zeroEquivalent to setPosition(x, y, 0.0f)
Applies only to sub-types:
- Listener
- Source
- Parameters:
x
- x-coordinatey
- 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 objectApplies only to sub-types:
- Listener
- Source
- Parameters:
vel
- 3d velocity vector
-
getVelocity
javax.vecmath.Vector3f getVelocity()
Returns the velocity of this AudioSource objectApplies only to sub-types:
- Listener
- Source
- Returns:
- 3d velocity vector
-
getAssignedBuffer
AudioBuffer getAssignedBuffer()
Returns linked AudioBuffer objectApplies 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 objectApplies 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 objectApplies 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 objectApplies 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 queueApplies 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
int numQueuedBuffers()
-
numProcessedBuffers
int numProcessedBuffers()
-
isBound
boolean isBound()
Method to return if this AudioSource has been bound to an AudioBufferApplies 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 itApplies only to sub-types:
- Source
- Returns:
- True if AudioBuffers are queued.
-
getGain
float getGain()
Return the currently stored gain settingDefault 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 objectDefault value = 1.0f
Applies only to sub-types:
- Listener
- Source
- Parameters:
gain
- the gain of this AudioSource
-
getPitch
float getPitch()
Return the current pitch settingValues 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 objectValues 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 settingDefault 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 = 0Applies only to sub-types:
- Source
- Returns:
- number of loops
-
getLastNumLoops
int getLastNumLoops()
Get the last value returned bygetNumLoops()
- Returns:
- the number of loops
-
setFadeIn
void setFadeIn(int fadeInTime)
Set the length of time in milliseconds to fade this source inDefault 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 inDefault 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 inDefault 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 inDefault value = 1000
Applies only to sub-types:
- Source
- Returns:
- fade-in time in milliseconds
-
play
void play()
Method to start playing this AudioSource ObjectIf this AudioSource is already playing, this command is ignored.
Applies only to sub-types:
- Source
-
stop
void stop()
Method to stop playing this AudioSource ObjectApplies only to sub-types:
- Source
-
togglePlay
void togglePlay()
Method to toggle playback of this AudioSource Object reseting positionApplies only to sub-types:
- Source
-
pause
void pause()
Method to pause playing this AudioSource ObjectApplies only to sub-types:
- Source
-
resume
void resume()
Method to resume playing this AudioSource ObjectApplies only to sub-types:
- Source
-
togglePause
void togglePause()
Method to toggle playback of this AudioSource Object retaining postitionApplies only to sub-types:
- Source
-
rewind
void rewind()
Method to rewind this AudioSource ObjectApplies only to sub-types:
- Source
-
fadeIn
void fadeIn()
Method to fade in and then play this AudioSource ObjectApplies 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()
-
-