com.jme3.audio
Class AudioNode

java.lang.Object
  extended by com.jme3.scene.Spatial
      extended by com.jme3.scene.Node
          extended by com.jme3.audio.AudioNode
All Implemented Interfaces:
CloneableSmartAsset, Collidable, Savable, java.lang.Cloneable

public class AudioNode
extends Node

An AudioNode is used in jME3 for playing audio files.
First, an AudioNode is loaded from file, and then assigned to an audio node for playback. Once the audio node is attached to the scene, its location will influence the position it is playing from relative to the Listener.
An audio node can also play in "headspace", meaning its location or velocity does not influence how it is played. The "positional" property of an AudioNode can be set via setPositional(boolean).


Nested Class Summary
static class AudioNode.Status
          Status indicates the current status of the audio node.
 
Nested classes/interfaces inherited from class com.jme3.scene.Spatial
Spatial.BatchHint, Spatial.CullHint
 
Field Summary
protected  AudioKey audioKey
           
protected  int channel
           
protected  AudioData data
           
protected  Vector3f direction
           
protected  Filter dryFilter
           
protected  float innerAngle
           
protected  boolean loop
           
protected  float maxDistance
           
protected  float outerAngle
           
protected  float pitch
           
protected  boolean positional
           
protected  float refDistance
           
protected  boolean reverbEnabled
           
protected  Filter reverbFilter
           
protected  AudioNode.Status status
           
protected  float timeOffset
           
protected  Vector3f velocity
           
protected  float volume
           
 
Fields inherited from class com.jme3.scene.Node
children
 
Fields inherited from class com.jme3.scene.Spatial
batchHint, controls, cullHint, frustrumIntersects, key, localLights, localTransform, name, parent, queueBucket, queueDistance, refreshFlags, RF_BOUND, RF_LIGHTLIST, RF_TRANSFORM, shadowMode, userData, worldBound, worldLights, worldTransform
 
Constructor Summary
AudioNode()
          Creates a new AudioNode without any audio data set.
AudioNode(AssetManager assetManager, java.lang.String name)
          Creates a new AudioNode with the given audio file.
AudioNode(AssetManager assetManager, java.lang.String name, boolean stream)
          Creates a new AudioNode with the given audio file.
AudioNode(AssetManager assetManager, java.lang.String name, boolean stream, boolean streamCache)
          Creates a new AudioNode with the given audio file.
AudioNode(AudioData audioData, AudioKey audioKey)
          Creates a new AudioNode with the given data and key.
AudioNode(AudioRenderer audioRenderer, AssetManager assetManager, java.lang.String name)
          Deprecated. AudioRenderer parameter is ignored.
 
Method Summary
 AudioNode clone()
          Creates a clone of the asset.
 AudioData getAudioData()
           
 int getChannel()
          Do not use.
 Vector3f getDirection()
           
 Filter getDryFilter()
           
 float getInnerAngle()
           
 float getMaxDistance()
           
 float getOuterAngle()
           
 float getPitch()
           
 float getRefDistance()
           
protected  AudioRenderer getRenderer()
           
 Filter getReverbFilter()
           
 AudioNode.Status getStatus()
           
 float getTimeOffset()
           
 Vector3f getVelocity()
           
 float getVolume()
           
 boolean isDirectional()
           
 boolean isLooping()
           
 boolean isPositional()
           
 boolean isReverbEnabled()
           
 void pause()
          Pause the audio that was started with play().
 void play()
          Start playing the audio.
 void playInstance()
          Start playing an instance of this audio.
 void read(JmeImporter im)
           
 void setAudioData(AudioData audioData, AudioKey audioKey)
          Set the audio data to use for the audio.
 void setChannel(int channel)
          Do not use.
 void setDirection(Vector3f direction)
          Set the direction of this audio node.
 void setDirectional(boolean directional)
          Set the audio node to be directional.
 void setDryFilter(Filter dryFilter)
          Set the dry filter to use for this audio node.
 void setInnerAngle(float innerAngle)
          Set the directional audio node cone inner angle.
 void setLooping(boolean loop)
          Set the looping mode for the audio node.
 void setMaxDistance(float maxDistance)
          Set the maximum distance for the attenuation of the audio node.
 void setOuterAngle(float outerAngle)
          Set the directional audio node cone outer angle.
 void setPitch(float pitch)
          Set the pitch of the audio, also the speed of playback.
 void setPositional(boolean positional)
          Set the audio node as positional.
 void setRefDistance(float refDistance)
          Set the reference playing distance for the audio node.
 void setReverbEnabled(boolean reverbEnabled)
          Set to true to enable reverberation effects for this audio node.
 void setReverbFilter(Filter reverbFilter)
          Set the reverb filter for this audio node.
 void setStatus(AudioNode.Status status)
          Do not use.
 void setTimeOffset(float timeOffset)
          Set the time offset in the sound sample when to start playing.
 void setVelocity(Vector3f velocity)
          Set the velocity of the audio node.
 void setVolume(float volume)
          Set the volume of this audio node.
 void stop()
          Stop playing the audio that was started with play().
 java.lang.String toString()
          Returns the Spatial's name followed by the class of the spatial
Example: "MyNode (com.jme3.scene.Spatial)
 void updateGeometricState()
          updateGeometricState updates the lightlist, computes the world transforms, and computes the world bounds for this Spatial.
 void write(JmeExporter ex)
           
 
Methods inherited from class com.jme3.scene.Node
attachChild, attachChildAt, breadthFirstTraversal, clone, collideWith, deepClone, depthFirstTraversal, descendantMatches, descendantMatches, descendantMatches, detachAllChildren, detachChild, detachChildAt, detachChildNamed, getChild, getChild, getChildIndex, getChildren, getQuantity, getTriangleCount, getVertexCount, hasChild, setLightListRefresh, setLodLevel, setMaterial, setModelBound, setTransformRefresh, swapChildren, updateLogicalState, updateModelBound, updateWorldBound
 
Methods inherited from class com.jme3.scene.Spatial
addControl, addLight, breadthFirstTraversal, center, checkCulling, getBatchHint, getControl, getControl, getCullHint, getKey, getLastFrustumIntersection, getLocalBatchHint, getLocalCullHint, getLocalLightList, getLocalQueueBucket, getLocalRotation, getLocalScale, getLocalShadowMode, getLocalToWorldMatrix, getLocalTransform, getLocalTranslation, getName, getNumControls, getParent, getQueueBucket, getShadowMode, getUserData, getUserDataKeys, getWorldBound, getWorldLightList, getWorldRotation, getWorldScale, getWorldTransform, getWorldTranslation, hasAncestor, localToWorld, lookAt, matches, move, move, removeControl, removeControl, removeFromParent, removeLight, rotate, rotate, rotateUpTo, runControlRender, scale, scale, setBatchHint, setBoundRefresh, setCullHint, setKey, setLastFrustumIntersection, setLocalRotation, setLocalRotation, setLocalScale, setLocalScale, setLocalScale, setLocalTransform, setLocalTranslation, setLocalTranslation, setName, setParent, setQueueBucket, setShadowMode, setUserData, updateWorldLightList, updateWorldTransforms, worldToLocal
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

loop

protected boolean loop

volume

protected float volume

pitch

protected float pitch

timeOffset

protected float timeOffset

dryFilter

protected Filter dryFilter

audioKey

protected AudioKey audioKey

data

protected transient AudioData data

status

protected transient volatile AudioNode.Status status

channel

protected transient volatile int channel

velocity

protected Vector3f velocity

reverbEnabled

protected boolean reverbEnabled

maxDistance

protected float maxDistance

refDistance

protected float refDistance

reverbFilter

protected Filter reverbFilter

direction

protected Vector3f direction

innerAngle

protected float innerAngle

outerAngle

protected float outerAngle

positional

protected boolean positional
Constructor Detail

AudioNode

public AudioNode()
Creates a new AudioNode without any audio data set.


AudioNode

public AudioNode(AudioData audioData,
                 AudioKey audioKey)
Creates a new AudioNode with the given data and key.

Parameters:
audioData - The audio data contains the audio track to play.
audioKey - The audio key that was used to load the AudioData

AudioNode

public AudioNode(AssetManager assetManager,
                 java.lang.String name,
                 boolean stream,
                 boolean streamCache)
Creates a new AudioNode with the given audio file.

Parameters:
assetManager - The asset manager to use to load the audio file
name - The filename of the audio file
stream - If true, the audio will be streamed gradually from disk, otherwise, it will be buffered.
streamCache - If stream is also true, then this specifies if the stream cache is used. When enabled, the audio stream will be read entirely but not decoded, allowing features such as seeking, looping and determining duration.

AudioNode

public AudioNode(AssetManager assetManager,
                 java.lang.String name,
                 boolean stream)
Creates a new AudioNode with the given audio file.

Parameters:
assetManager - The asset manager to use to load the audio file
name - The filename of the audio file
stream - If true, the audio will be streamed gradually from disk, otherwise, it will be buffered.

AudioNode

public AudioNode(AudioRenderer audioRenderer,
                 AssetManager assetManager,
                 java.lang.String name)
Deprecated. AudioRenderer parameter is ignored.

Creates a new AudioNode with the given audio file.

Parameters:
audioRenderer - The audio renderer to use for playing. Cannot be null.
assetManager - The asset manager to use to load the audio file
name - The filename of the audio file

AudioNode

public AudioNode(AssetManager assetManager,
                 java.lang.String name)
Creates a new AudioNode with the given audio file.

Parameters:
assetManager - The asset manager to use to load the audio file
name - The filename of the audio file
Method Detail

getRenderer

protected AudioRenderer getRenderer()

play

public void play()
Start playing the audio.


playInstance

public void playInstance()
Start playing an instance of this audio. This method can be used to play the same AudioNode multiple times. Note that changes to the parameters of this AudioNode will not effect the instances already playing.


stop

public void stop()
Stop playing the audio that was started with play().


pause

public void pause()
Pause the audio that was started with play().


setChannel

public final void setChannel(int channel)
Do not use.


getChannel

public int getChannel()
Do not use.


getDryFilter

public Filter getDryFilter()
Returns:
The {#link Filter dry filter} that is set.
See Also:
setDryFilter(com.jme3.audio.Filter)

setDryFilter

public void setDryFilter(Filter dryFilter)
Set the dry filter to use for this audio node. When reverb is used, the dry filter will only influence the "dry" portion of the audio, e.g. not the reverberated parts of the AudioNode playing. See the relevent documentation for the Filter to determine the effect.

Parameters:
dryFilter - The filter to set, or null to disable dry filter.

setAudioData

public void setAudioData(AudioData audioData,
                         AudioKey audioKey)
Set the audio data to use for the audio. Note that this method can only be called once, if for example the audio node was initialized without an AudioData.

Parameters:
audioData - The audio data contains the audio track to play.
audioKey - The audio key that was used to load the AudioData

getAudioData

public AudioData getAudioData()
Returns:
The AudioData set previously with setAudioData(com.jme3.audio.AudioData, com.jme3.audio.AudioKey) or any of the constructors that initialize the audio data.

getStatus

public AudioNode.Status getStatus()
Returns:
The AudioNode.Status of the audio node. The status will be changed when either the play() or stop() methods are called.

setStatus

public final void setStatus(AudioNode.Status status)
Do not use.


isLooping

public boolean isLooping()
Returns:
True if the audio will keep looping after it is done playing, otherwise, false.
See Also:
setLooping(boolean)

setLooping

public void setLooping(boolean loop)
Set the looping mode for the audio node. The default is false.

Parameters:
loop - True if the audio should keep looping after it is done playing.

getPitch

public float getPitch()
Returns:
The pitch of the audio, also the speed of playback.
See Also:
setPitch(float)

setPitch

public void setPitch(float pitch)
Set the pitch of the audio, also the speed of playback. The value must be between 0.5 and 2.0.

Parameters:
pitch - The pitch to set.
Throws:
java.lang.IllegalArgumentException - If pitch is not between 0.5 and 2.0.

getVolume

public float getVolume()
Returns:
The volume of this audio node.
See Also:
setVolume(float)

setVolume

public void setVolume(float volume)
Set the volume of this audio node. The volume is specified as gain. 1.0 is the default.

Parameters:
volume - The volume to set.
Throws:
java.lang.IllegalArgumentException - If volume is negative

getTimeOffset

public float getTimeOffset()
Returns:
the time offset in the sound sample when to start playing.

setTimeOffset

public void setTimeOffset(float timeOffset)
Set the time offset in the sound sample when to start playing.

Parameters:
timeOffset - The time offset
Throws:
java.lang.IllegalArgumentException - If timeOffset is negative

getVelocity

public Vector3f getVelocity()
Returns:
The velocity of the audio node.
See Also:
setVelocity(com.jme3.math.Vector3f)

setVelocity

public void setVelocity(Vector3f velocity)
Set the velocity of the audio node. The velocity is expected to be in meters. Does nothing if the audio node is not positional.

Parameters:
velocity - The velocity to set.
See Also:
setPositional(boolean)

isReverbEnabled

public boolean isReverbEnabled()
Returns:
True if reverb is enabled, otherwise false.
See Also:
setReverbEnabled(boolean)

setReverbEnabled

public void setReverbEnabled(boolean reverbEnabled)
Set to true to enable reverberation effects for this audio node. Does nothing if the audio node is not positional.
When enabled, the audio environment set with AudioRenderer.setEnvironment(com.jme3.audio.Environment) will apply a reverb effect to the audio playing from this audio node.

Parameters:
reverbEnabled - True to enable reverb.

getReverbFilter

public Filter getReverbFilter()
Returns:
Filter for the reverberations of this audio node.
See Also:
setReverbFilter(com.jme3.audio.Filter)

setReverbFilter

public void setReverbFilter(Filter reverbFilter)
Set the reverb filter for this audio node.
The reverb filter will influence the reverberations of the audio node playing. This only has an effect if reverb is enabled.

Parameters:
reverbFilter - The reverb filter to set.
See Also:
setDryFilter(com.jme3.audio.Filter)

getMaxDistance

public float getMaxDistance()
Returns:
Max distance for this audio node.
See Also:
setMaxDistance(float)

setMaxDistance

public void setMaxDistance(float maxDistance)
Set the maximum distance for the attenuation of the audio node. Does nothing if the audio node is not positional.
The maximum distance is the distance beyond which the audio node will no longer be attenuated. Normal attenuation is logarithmic from refDistance (it reduces by half when the distance doubles). Max distance sets where this fall-off stops and the sound will never get any quieter than at that distance. If you want a sound to fall-off very quickly then set ref distance very short and leave this distance very long.

Parameters:
maxDistance - The maximum playing distance.
Throws:
java.lang.IllegalArgumentException - If maxDistance is negative

getRefDistance

public float getRefDistance()
Returns:
The reference playing distance for the audio node.
See Also:
setRefDistance(float)

setRefDistance

public void setRefDistance(float refDistance)
Set the reference playing distance for the audio node. Does nothing if the audio node is not positional.
The reference playing distance is the distance at which the audio node will be exactly half of its volume.

Parameters:
refDistance - The reference playing distance.
Throws:
java.lang.IllegalArgumentException - If refDistance is negative

isDirectional

public boolean isDirectional()
Returns:
True if the audio node is directional
See Also:
setDirectional(boolean)

setDirectional

public void setDirectional(boolean directional)
Set the audio node to be directional. Does nothing if the audio node is not positional.
After setting directional, you should call setDirection(com.jme3.math.Vector3f) to set the audio node's direction.

Parameters:
directional - If the audio node is directional

getDirection

public Vector3f getDirection()
Returns:
The direction of this audio node.
See Also:
setDirection(com.jme3.math.Vector3f)

setDirection

public void setDirection(Vector3f direction)
Set the direction of this audio node. Does nothing if the audio node is not directional.

Parameters:
direction -
See Also:
setDirectional(boolean)

getInnerAngle

public float getInnerAngle()
Returns:
The directional audio node, cone inner angle.
See Also:
setInnerAngle(float)

setInnerAngle

public void setInnerAngle(float innerAngle)
Set the directional audio node cone inner angle. Does nothing if the audio node is not directional.

Parameters:
innerAngle - The cone inner angle.

getOuterAngle

public float getOuterAngle()
Returns:
The directional audio node, cone outer angle.
See Also:
setOuterAngle(float)

setOuterAngle

public void setOuterAngle(float outerAngle)
Set the directional audio node cone outer angle. Does nothing if the audio node is not directional.

Parameters:
outerAngle - The cone outer angle.

isPositional

public boolean isPositional()
Returns:
True if the audio node is positional.
See Also:
setPositional(boolean)

setPositional

public void setPositional(boolean positional)
Set the audio node as positional. The position, velocity, and distance parameters effect positional audio nodes. Set to false if the audio node should play in "headspace".

Parameters:
positional - True if the audio node should be positional, otherwise false if it should be headspace.

updateGeometricState

public void updateGeometricState()
Description copied from class: Spatial
updateGeometricState updates the lightlist, computes the world transforms, and computes the world bounds for this Spatial. Calling this when the Spatial is attached to a node will cause undefined results. User code should only call this method on Spatials having no parent.

Overrides:
updateGeometricState in class Node
See Also:
Spatial.getWorldLightList(), Spatial.getWorldTransform(), Spatial.getWorldBound()

clone

public AudioNode clone()
Description copied from interface: CloneableSmartAsset
Creates a clone of the asset. Please see Object.clone() for more info on how this method should be implemented.

Specified by:
clone in interface CloneableSmartAsset
Overrides:
clone in class Spatial
Returns:
A clone of this Spatial, the scene graph in its entirety is cloned and can be altered independently of the original scene graph. Note that meshes of geometries are not cloned explicitly, they are shared if static, or specially cloned if animated. All controls will be cloned using the Control.cloneForSpatial method on the clone.
See Also:
Mesh.cloneForAnim()

write

public void write(JmeExporter ex)
           throws java.io.IOException
Specified by:
write in interface Savable
Overrides:
write in class Node
Throws:
java.io.IOException

read

public void read(JmeImporter im)
          throws java.io.IOException
Specified by:
read in interface Savable
Overrides:
read in class Node
Throws:
java.io.IOException

toString

public java.lang.String toString()
Description copied from class: Spatial
Returns the Spatial's name followed by the class of the spatial
Example: "MyNode (com.jme3.scene.Spatial)

Overrides:
toString in class Spatial
Returns:
Spatial's name followed by the class of the Spatial