FlixelSound

View source

class

org.flixelgdx.audio.FlixelSound

public class FlixelSound extends FlixelBasic implements FlixelAsset<FlixelSoundBackend>

Flixel sound object that wraps a platform-specific FlixelSoundBackend.

Provides volume, pitch, pan, play/pause/stop/resume, fade-in/fade-out, position (time), optional audio-graph effects (FlixelSound.addReverb(float), FlixelSound.addEcho(float, float), FlixelSound.addLowPassMuffle(double), FlixelSound.attachCustomNode(EffectNode)), and an FlixelSound.onComplete signal when the sound finishes (for non-looping sounds).

The effect methods return typed node handles rather than this, so holding the returned reference lets you modify parameters live without rebuilding the effect chain.

This class implements FlixelAsset<FlixelSoundBackend> for a refcount contract: each instance FlixelSound.retain()s once in the backend constructor, and FlixelSound.destroy() FlixelSound.release()s to balance it. Use extra FlixelSound.retain() / FlixelSound.release() for advanced sharing. FlixelSound.persist controls substate behavior.

See Also: FlixelAssetManager.resolveAudioPath

Constructors

FlixelSound(FileHandle)

public FlixelSound(FileHandle path)

Creates a new Flixel sound wrapping the given file path.

Parameters:

Name	Description
path	The path to the sound file.

---

FlixelSound(FlixelSoundBackend)

public FlixelSound(FlixelSoundBackend sound)

Creates a Flixel sound wrapping the given backend.

Parameters:

Name	Description
sound	The platform-specific sound backend to wrap (must not be null).

---

Fields

onComplete

public final FlixelSignal<Void> onComplete

Signal dispatched when the sound reaches its end (non-looping).

---

Methods

getBackend()

public FlixelSoundBackend getBackend()

Returns the underlying sound backend for advanced use. Prefer the FlixelSound API when possible.

Returns: The wrapped backend instance.

---

getManager()

public FlixelSoundManager getManager()

Returns the manager that this sound is a member of.

Returns: The manager, or null if not assigned to one.

---

setManager(FlixelSoundManager)

public FlixelSound setManager(FlixelSoundManager manager)

Sets the manager that this sound is a member of.

Parameters:

Name	Description
manager	The manager to set.

Returns: this for chaining.

---

setSourceAsset(FlixelAsset<FlixelSoundSource>)

public FlixelSound setSourceAsset(FlixelAsset<FlixelSoundSource> sourceAsset)

Attaches the backing FlixelAsset handle for the FlixelSoundSource that was retained when this sound was created through FlixelSoundManager. The handle is released in FlixelSound.destroy() so the source asset is eligible for cleanup according to the active FlixelAssetMode.

Parameters:

Name	Description
sourceAsset	The retained source handle, or null to clear it.

Returns: this for chaining.

---

getPath()

public String getPath()

---

get()

public FlixelSoundBackend get()

---

isLoaded()

public boolean isLoaded()

---

getLoaded()

public boolean getLoaded()

Returns whether this sound's audio data has been loaded.

---

getRefCount()

public int getRefCount()

---

retain()

public FlixelSound retain()

---

release()

public FlixelSound release()

---

getVolume()

public float getVolume()

Returns the current volume.

Returns: Volume level (0 = silent, 1 = default, values above 1 are allowed).

---

setVolume(float)

public FlixelSound setVolume(float volume)

Sets the volume.

Parameters:

Name	Description
volume	Volume level (0 = silent, 1 = default, values above 1 amplify).

Returns: this for chaining.

---

getPitch()

public float getPitch()

Returns the cached pitch multiplier.

Returns: Pitch multiplier; 1 = default, values above 1 raise pitch.

---

setPitch(float)

public FlixelSound setPitch(float pitch)

Sets the pitch multiplier.

Parameters:

Name	Description
pitch	Pitch value; must be greater than 0.

Returns: this for chaining.

---

getPan()

public float getPan()

Returns the cached pan value.

Returns: Pan in [-1, 1]; -1 = left, 0 = center, 1 = right.

---

setPan(float)

public FlixelSound setPan(float pan)

Sets the stereo pan.

Parameters:

Name	Description
pan	Pan value in [-1, 1].

Returns: this for chaining.

---

getTime()

public float getTime()

Returns the current playback position in milliseconds.

If set while paused, the change takes effect after FlixelSound.resume().

Returns: Playback position in milliseconds.

---

setTime(float)

public FlixelSound setTime(float timeMs)

Sets the playback position in milliseconds.

Parameters:

Name	Description
timeMs	The time to set the playback position to in milliseconds.

Returns: this for chaining.

---

getLength()

public float getLength()

Returns the total length of the sound in milliseconds.

Returns: Duration in milliseconds, or 0 if unknown.

---

isLooped()

public boolean isLooped()

Returns whether this sound is set to loop.

Returns: true if looping is enabled.

---

getLooped()

public boolean getLooped()

Returns whether this sound is set to loop.

---

setLooped(boolean)

public FlixelSound setLooped(boolean looped)

Enables or disables looping.

Parameters:

Name	Description
looped	true to loop, false to play once.

Returns: this for chaining.

---

isPlaying()

public boolean isPlaying()

Returns whether this sound is currently playing.

Returns: true if the sound is actively playing.

---

getPlaying()

public boolean getPlaying()

Returns whether this sound is currently playing.

---

play()

public FlixelSound play()

Plays the sound from the beginning.

Returns: this for chaining.

---

play(boolean)

public FlixelSound play(boolean forceRestart)

Plays the sound.

Parameters:

Name	Description
forceRestart	Should the sound be restarted if it is already playing?

Returns: this for chaining.

---

play(boolean, float)

public FlixelSound play(boolean forceRestart, float startTimeMs)

Plays the sound.

Parameters:

Name	Description
forceRestart	Whether to restart the sound if it is already playing.
startTimeMs	The time to start the sound at in milliseconds.

Returns: this for chaining.

---

pause()

public FlixelSound pause()

Pauses the sound at its current position.

Returns: this for chaining.

---

stop()

public FlixelSound stop()

Stops the sound and resets position to 0.

Returns: this for chaining.

---

resume()

public FlixelSound resume()

Resumes from the current position after a pause.

Returns: this for chaining.

---

getEndTime()

public Float getEndTime()

Returns the position (in milliseconds) at which playback will stop, or null if the sound will play to the end.

Returns: End time in milliseconds, or null.

---

setEndTime(Float)

public FlixelSound setEndTime(Float endTimeMs)

Sets the position (ms) at which to stop. null means play to the end.

Parameters:

Name	Description
endTimeMs	End time in milliseconds, or null.

Returns: this for chaining.

---

fadeIn(float)

public FlixelSound fadeIn(float durationSeconds)

Fades in from 0 to 1 over the given duration (seconds).

Parameters:

Name	Description
durationSeconds	Fade duration in seconds.

Returns: this for chaining.

---

fadeIn(float, float, float)

public FlixelSound fadeIn(float durationSeconds, float from, float to)

Fades volume from from to to over durationSeconds.

Parameters:

Name	Description
durationSeconds	Fade duration in seconds.
from	Start volume.
to	End volume.

Returns: this for chaining.

---

fadeOut(float)

public FlixelSound fadeOut(float durationSeconds)

Fades out to 0 over the given duration (seconds).

Parameters:

Name	Description
durationSeconds	Fade duration in seconds.

Returns: this for chaining.

---

fadeOut(float, float)

public FlixelSound fadeOut(float durationSeconds, float to)

Fades volume to to over durationSeconds.

Parameters:

Name	Description
durationSeconds	Fade duration in seconds.
to	Target volume (typically 0).

Returns: this for chaining.

---

getFadeTween()

public FlixelTween getFadeTween()

Returns the tween used for fade-in/fade-out, if any.

Returns: The active fade tween, or null.

---

getX()

public float getX()

Returns the X position in world coordinates (for proximity/panning).

Returns: World X position.

---

getY()

public float getY()

Returns the Y position in world coordinates (for proximity/panning).

Returns: World Y position.

---

setPosition(float, float)

public FlixelSound setPosition(float x, float y)

Sets world position for proximity/panning.

Parameters:

Name	Description
x	World X coordinate.
y	World Y coordinate.

Returns: this for chaining.

---

isAutoDestroy()

public boolean isAutoDestroy()

Returns whether this sound auto-destroys when playback completes.

Returns: true if auto-destroy is enabled.

---

getAutoDestroy()

public boolean getAutoDestroy()

Returns whether this sound auto-destroys when playback completes.

---

setAutoDestroy(boolean)

public FlixelSound setAutoDestroy(boolean autoDestroy)

Sets whether this sound auto-destroys when playback completes.

Parameters:

Name	Description
autoDestroy	true to enable auto-destroy.

Returns: this for chaining.

---

isPersist()

public boolean isPersist()

---

getPersist()

public boolean getPersist()

Returns whether this sound persists across state transitions.

---

setPersist(boolean)

public FlixelSound setPersist(boolean persist)

---

update(float)

public void update(float elapsed)

---

getEffectNodes()

public Array<EffectNode> getEffectNodes()

Returns the list of effect nodes currently attached to this sound's audio graph, in chain order (index 0 is closest to the sound source, last index is closest to the output).

Typed nodes (ReverbNode, EchoNode, LowPassNode) can be cast from elements in this list if needed, though it is simpler to keep references returned by FlixelSound.addReverb(float), FlixelSound.addEcho(float, float), and FlixelSound.addLowPassMuffle(double) directly.

Returns: A read-only view of the effect chain.

---

clearAudioEffectChain()

public void clearAudioEffectChain()

Detaches and disposes every node in the effect chain (reverse order). Called from FlixelSound.destroy().

---

addReverb(float)

public ReverbNode addReverb(float wetAmount)

Appends a reverb node with the given wet amount in [0, 1] (dry is set to 1 - wet). Build effect chains in load/setup code, not every frame.

Hold the returned node to adjust reverb parameters at runtime without rebuilding the chain:

FlixelSoundBackend.ReverbNode reverb = sound.addReverb(0.4f);
// Later, on entering a cave:
reverb.setRoomSize(0.9f);
reverb.setWet(0.7f);

Parameters:

Name	Description
wetAmount	Wet signal level in [0, 1].

Returns: The attached reverb node. Hold this reference to modify parameters later.

---

addEcho(float, float)

public EchoNode addEcho(float delaySeconds, float decay)

Appends a stereo delay/echo node.

Delay time and decay are fixed at construction. To change them, call FlixelSound.clearAudioEffectChain() and rebuild, or dispose the specific node and add a new one.

Parameters:

Name	Description
delaySeconds	Delay time in seconds.
decay	Decay factor for the delayed signal.

Returns: The attached echo node.

---

addLowPassMuffle(double)

public LowPassNode addLowPassMuffle(double cutoffHz)

Appends a 2nd-order low-pass filter (muffled / distant sound).

Hold the returned node to adjust the cutoff frequency at runtime:

FlixelSoundBackend.LowPassNode muffle = sound.addLowPassMuffle(8000.0);
// Tighten the filter as the player moves deeper:
muffle.setCutoff(2000.0);

Parameters:

Name	Description
cutoffHz	Cutoff frequency in Hz.

Returns: The attached low-pass node. Hold this reference to adjust cutoff later.

---

attachCustomNode(EffectNode)

public FlixelSound attachCustomNode(EffectNode node)

Expert escape hatch: append any effect node to the chain. this sound disposes the node when FlixelSound.clearAudioEffectChain() runs unless you remove it yourself first.

Parameters:

Name	Description
node	The effect node to attach.

Returns: this for chaining.

---

destroy()

public void destroy()

---