jmri.jmrit.audio
Interface AudioSource

All Superinterfaces:

Audio, NamedBean

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 (e.g. LocoNet, NCE, etc) 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.

Author:

Matthew Harris copyright (c) 2009

Field Summary

static int	LOOP_CONTINUOUS Constant to define that this source should loop continously when played
static 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_RESET_POSITION, CMD_RESUME, CMD_REWIND, CMD_STOP, 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

INCONSISTENT, UNKNOWN

Method Summary

void	fadeIn() Method to fade in and then play this AudioSource Object Applies only to sub-types: Source
void	fadeOut() Method to fade out and then stop this AudioSource Object only when it is already playing.
AudioBuffer	getAssignedBuffer() Returns linked AudioBuffer object Applies only to sub-types: Source
String	getAssignedBufferName() Return system name of linked AudioBuffer object Applies only to sub-types: Source
Vector3f	getCurrentPosition() Returns the current position of this AudioSource object as a 3-dimensional vector.
float	getDopplerFactor() Deprecated.
int	getFadeIn() Retrieve the length of time in milliseconds to fade this source in Default value = 1000 Applies only to sub-types: Source
int	getFadeOut() Retrieve the length of time in milliseconds to fade this source in Default value = 1000 Applies only to sub-types: Source
float	getGain() Return the currently stored gain setting Default value = 1.0f Applies only to sub-types: Listener Source
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.
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.
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
Vector3f	getPosition() Returns the position of this AudioSource object as a 3-dimensional vector.
float	getReferenceDistance() Return the current reference distance setting Default value = 1.0f Applies only to sub-types: Source
float	getRollOffFactor() Return the roll-off factor of this AudioSource object Default value = 1.0f Applies only to sub-types: Source
Vector3f	getVelocity() Returns the velocity of this AudioSource object Applies only to sub-types: Listener Source
boolean	isBound() Method to return if this AudioSource has been bound to an AudioBuffer Applies only to sub-types: Source
boolean	isLooped() Returns a boolean if this AudioSource object will loop or not Applies only to sub-types: Source
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.
void	pause() Method to pause playing this AudioSource Object Applies only to sub-types: Source
void	play() Method to start playing this AudioSource Object If this AudioSource is already playing, this command is ignored.
void	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 Object Applies only to sub-types: Source
void	rewind() Method to rewind this AudioSource Object Applies only to sub-types: Source
void	setAssignedBuffer(AudioBuffer audioBuffer) Sets the linked AudioBuffer object Applies only to sub-types: Source
void	setAssignedBuffer(String sysName) Sets the system name of the linked AudioBuffer object Applies only to sub-types: Source
void	setDopplerFactor(float dopplerFactor) Deprecated.
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
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
void	setGain(float gain) Set the gain of this AudioSource object Default value = 1.0f Applies only to sub-types: Listener Source
void	setLooped(boolean loop) Sets this AudioSource object to loop infinitely or not.
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.
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	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
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
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
void	setPosition(Vector3f pos) Sets the position of this AudioSource object Applies only to sub-types: Listener Source
void	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 Default value = 1.0f Applies only to sub-types: Source
void	setVelocity(Vector3f vel) Sets the velocity of this AudioSource object Applies only to sub-types: Listener Source
void	stop() Method to stop playing this AudioSource Object Applies only to sub-types: Source
void	togglePause() Method to toggle playback of this AudioSource Object retaining postition Applies only to sub-types: Source
void	togglePlay() Method to toggle playback of this AudioSource Object reseting position Applies only to sub-types: Source

Methods inherited from interface jmri.Audio

getSubType, stateChanged

Methods inherited from interface jmri.NamedBean

addPropertyChangeListener, addPropertyChangeListener, dispose, getComment, getDisplayName, getListenerRef, getListenerRefs, getNumPropertyChangeListeners, getProperty, getPropertyChangeListeners, getPropertyKeys, getState, getSystemName, getUserName, removePropertyChangeListener, setComment, setProperty, setState, setUserName, updateListenerRef

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(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

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

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(Vector3f vel)

Sets the velocity of this AudioSource object

Applies only to sub-types:

• Listener
• Source

Parameters:

vel - 3d velocity vector

getVelocity

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

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(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

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

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 attenutate 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

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

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()

Return the roll-off factor of this AudioSource object

Default value = 1.0f

Applies only to sub-types:

• Source

isLooped

boolean isLooped()

Returns a boolean 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

setDopplerFactor

@Deprecated
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
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