FlixelSoundBackend

View source

interface

org.flixelgdx.audio.FlixelSoundBackend

public interface FlixelSoundBackend

Platform-agnostic abstraction over a single sound instance.

On JVM platforms the default implementation wraps MiniAudio (MASound); on TeaVM/web the implementation uses the Web Audio API.

Obtain instances through Factory.createSound.

See Also: Factory

Methods

play()

public void play()

Starts or resumes playback.

---

pause()

public void pause()

Pauses playback at the current cursor position.

---

stop()

public void stop()

Stops playback and resets the cursor to the beginning.

---

isPlaying()

public boolean isPlaying()

Returns whether this sound is currently playing.

Returns: true if the sound is actively playing.

---

isEnd()

public boolean isEnd()

Returns whether this sound has reached its end.

Returns: true if the cursor is at or past the end of the stream.

---

getVolume()

public float getVolume()

Returns the current volume.

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

---

setVolume(float)

public void setVolume(float volume)

Sets the volume.

Parameters:

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

---

setPitch(float)

public void setPitch(float pitch)

Sets the pitch multiplier.

Parameters:

Name	Description
pitch	Pitch multiplier. Must be greater than 0. 1 = default.

---

setPan(float)

public void setPan(float pan)

Sets the stereo pan.

Parameters:

Name	Description
pan	Pan value in [-1, 1]; -1 = full left, 0 = center, 1 = full right.

---

getCursorPosition()

public float getCursorPosition()

Returns the current cursor position in seconds.

Returns: Playback position in seconds.

---

seekTo(float)

public void seekTo(float seconds)

Seeks to the given position.

Parameters:

Name	Description
seconds	Target position in seconds.

---

getLength()

public float getLength()

Returns the total length of the sound in seconds.

Returns: Duration in seconds, or 0 if unknown.

---

isLooping()

public boolean isLooping()

Returns whether this sound is set to loop.

Returns: true if the sound will loop when it reaches the end.

---

setLooping(boolean)

public void setLooping(boolean looping)

Enables or disables looping.

Parameters:

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

---

setPosition(float, float, float)

public void setPosition(float x, float y, float z)

Sets the 3-D position of this sound for spatial audio. Implementations that do not support spatial audio should ignore this call.

Parameters:

Name	Description
x	X position.
y	Y position.
z	Z position.

---

dispose()

public void dispose()

Releases native resources held by this sound.

---

Factory

interface

org.flixelgdx.audio.FlixelSoundBackend.Factory

public static interface Factory

Platform-specific factory for creating sounds, groups, and effect nodes.

One instance is injected into Flixel at startup via Flixel.soundFactory, and is shared by FlixelSoundManager and FlixelSound.

Methods

createSound(String, short, Object, boolean)

public FlixelSoundBackend createSound(String path, short flags, Object group, boolean external)

Creates a new sound from a resolved file path.

Parameters:

Name	Description
path	Resolved (absolute or internal) path to the audio file.
flags	Implementation-specific flags (typically 0).
group	A group handle previously obtained from FlixelSoundBackend.createGroup(), or null for the default group.
external	true if the path is an absolute external path.

Returns: A new backend sound instance.

---

createGroup()

public Object createGroup()

Creates a new sound group. The returned object is opaque; pass it back to group methods or to FlixelSoundBackend.createSound.

Returns: A new group handle.

---

disposeGroup(Object)

public void disposeGroup(Object group)

Disposes a group previously created by FlixelSoundBackend.createGroup().

Parameters:

Name	Description
group	The group handle to dispose.

---

groupPause(Object)

public void groupPause(Object group)

Pauses all sounds in the given group.

Parameters:

Name	Description
group	The group handle.

---

groupPlay(Object)

public void groupPlay(Object group)

Resumes (plays) all sounds in the given group.

Parameters:

Name	Description
group	The group handle.

---

setMasterVolume(float)

public void setMasterVolume(float volume)

Sets the global master volume for the audio engine.

Parameters:

Name	Description
volume	Master volume in [0, 1].

---

disposeEngine()

public void disposeEngine()

Disposes the underlying audio engine and releases all native resources.

---

prewarmSound(String)

public default void prewarmSound(String path)

Pre-decodes the audio at the given path and caches the result so the next FlixelSoundBackend.createSound call for the same path can start playback immediately with no decode lag.

This is an internal hook called automatically by FlixelDefaultAssetManager whenever a FlixelSoundSource is enqueued on the web platform. Do not call it directly; load audio through Flixel.assets.load(path) instead.

On platforms where decoding is synchronous (desktop, Android) this is a no-op.

Parameters:

Name	Description
path	The resolved internal asset path to pre-decode.

---

isPrewarmPending()

public default boolean isPrewarmPending()

Returns true while at least one FlixelSoundBackend.prewarmSound decode is still in progress.

On platforms where decoding is synchronous (desktop, Android) this always returns false. On the web platform, FlixelAssetManager.update() consults this method and continues returning false until all pending decodes resolve, keeping the loading-state loop alive until audio is truly ready to play.

Returns: true if one or more background decodes have not yet completed.

---

attachToEngineOutput(FlixelSoundBackend, int)

public void attachToEngineOutput(FlixelSoundBackend sound, int outputBusIndex)

Attaches a sound directly to the engine endpoint, bypassing any effect chain. Used to restore direct routing after clearing effects. Implementations that do not support an audio graph should no-op.

Parameters:

Name	Description
sound	The sound backend whose output to route.
outputBusIndex	Output bus index (typically 0).

---

attachEffectToEngineOutput(EffectNode, int)

public void attachEffectToEngineOutput(EffectNode node, int outputBusIndex)

Attaches the tail effect node in a chain to the engine endpoint so that processed audio reaches the output. Must be called each time a new node is appended to the chain. Implementations that do not support an audio graph should no-op.

Parameters:

Name	Description
node	The tail effect node whose output to route.
outputBusIndex	Output bus index (typically 0).

---

attachEffectToEngineOutput(EffectNode, int, FlixelSoundBackend)

public default void attachEffectToEngineOutput(EffectNode node, int outputBusIndex, FlixelSoundBackend sound)

Sound-aware overload of FlixelSoundBackend.attachEffectToEngineOutput(...).

Backends that route through sound groups (e.g. MiniAudio) should override this to connect the tail node through the sound's group rather than directly to the engine endpoint, preserving group-level pause and resume behavior. The default implementation delegates to the two-argument form and ignores the sound.

Parameters:

Name	Description
node	The tail effect node whose output to route.
outputBusIndex	Output bus index (typically 0).
sound	The sound whose effect chain is being finalized.

---

createReverbNode(float)

public ReverbNode createReverbNode(float wet)

Creates a reverb effect node.

Parameters:

Name	Description
wet	Wet amount in [0, 1].

Returns: A new reverb node, or a no-op stub on unsupported platforms.

---

createDelayNode(float, float)

public EchoNode createDelayNode(float delaySeconds, float decay)

Creates a delay / echo effect node.

Parameters:

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

Returns: A new echo node, or a no-op stub on unsupported platforms.

---

createLowPassFilter(double, int)

public LowPassNode createLowPassFilter(double cutoffHz, int order)

Creates a low-pass filter effect node.

Parameters:

Name	Description
cutoffHz	Cutoff frequency in hertz.
order	Filter order (e.g. 2 for a second-order filter).

Returns: A new low-pass node, or a no-op stub on unsupported platforms.

---

EffectNode

interface

org.flixelgdx.audio.FlixelSoundBackend.EffectNode

public static interface EffectNode

An opaque handle to an audio-graph effect node (reverb, delay, low-pass, etc.).

On platforms that do not support an audio graph the returned instances are no-op stubs. Typed subtypes (ReverbNode, EchoNode, LowPassNode) expose live parameter setters for the effects that support them.

Methods

attachToUpstream(FlixelSoundBackend, int)

public void attachToUpstream(FlixelSoundBackend upstream, int bus)

Wires a sound source into this node's input.

Parameters:

Name	Description
upstream	The upstream sound backend.
bus	Input bus index (typically 0).

---

attachToUpstreamNode(EffectNode, int)

public void attachToUpstreamNode(EffectNode upstream, int bus)

Wires another effect node into this node's input, allowing effects to be chained together (e.g. reverb feeding into a low-pass filter).

Parameters:

Name	Description
upstream	The upstream effect node.
bus	Input bus index (typically 0).

---

detach(int)

public void detach(int bus)

Detaches this node from its input bus.

Parameters:

Name	Description
bus	The bus index to detach.

---

dispose()

public void dispose()

Releases native resources held by this effect node.

---

ReverbNode

interface

org.flixelgdx.audio.FlixelSoundBackend.ReverbNode

public static interface ReverbNode extends EffectNode

A live-controllable reverb effect node.

All setters take effect immediately without rebuilding the audio graph. Corresponding change*() methods apply a delta to the current value, so callers do not need to manually combine a getter with a setter.

Example usage:

ReverbNode reverb = sound.addReverb(0.4f);
// Later, when the player enters a cave:
reverb.setRoomSize(0.9f);
reverb.changeWet(0.3f);  // wet is now 0.7

Fields

NOOP

public static final ReverbNode NOOP

No-op sentinel returned when no sound factory is available.

---

Methods

getWet()

public float getWet()

Returns the current wet (processed) signal level.

Returns: Level in [0, 1].

---

getDry()

public float getDry()

Returns the current dry (unprocessed) signal level.

Returns: Level in [0, 1].

---

getRoomSize()

public float getRoomSize()

Returns the current simulated room size.

Returns: Room size in [0, 1].

---

getDamping()

public float getDamping()

Returns the current high-frequency damping amount.

Returns: Damping in [0, 1].

---

getWidth()

public float getWidth()

Returns the current stereo width of the reverb tail.

Returns: Width in [0, 1].

---

isFrozen()

public boolean isFrozen()

Returns whether the reverb tail is currently frozen.

Returns: true if the tail is recirculating indefinitely.

---

changeWet(float)

public default void changeWet(float amount)

Adds amount to the current wet level, clamped to [0, 1].

Parameters:

Name	Description
amount	Delta to apply.

---

changeDry(float)

public default void changeDry(float amount)

Adds amount to the current dry level, clamped to [0, 1].

Parameters:

Name	Description
amount	Delta to apply.

---

changeRoomSize(float)

public default void changeRoomSize(float amount)

Adds amount to the current room size, clamped to [0, 1].

Parameters:

Name	Description
amount	Delta to apply.

---

changeDamping(float)

public default void changeDamping(float amount)

Adds amount to the current damping, clamped to [0, 1].

Parameters:

Name	Description
amount	Delta to apply.

---

changeWidth(float)

public default void changeWidth(float amount)

Adds amount to the current width, clamped to [0, 1].

Parameters:

Name	Description
amount	Delta to apply.

---

setWet(float)

public void setWet(float wet)

Sets the wet (processed) signal level.

Parameters:

Name	Description
wet	Level in [0, 1].

---

setDry(float)

public void setDry(float dry)

Sets the dry (unprocessed) signal level.

Parameters:

Name	Description
dry	Level in [0, 1].

---

setRoomSize(float)

public void setRoomSize(float size)

Sets the simulated room size.

Parameters:

Name	Description
size	Room size in [0, 1]; larger values produce longer reverb tails.

---

setDamping(float)

public void setDamping(float damping)

Sets the high-frequency damping amount.

Parameters:

Name	Description
damping	Damping in [0, 1]; higher values absorb treble faster.

---

setWidth(float)

public void setWidth(float width)

Sets the stereo width of the reverb tail.

Parameters:

Name	Description
width	Width in [0, 1]; 0 is mono, 1 is full stereo spread.

---

setFrozen(boolean)

public void setFrozen(boolean frozen)

Freezes or unfreezes the reverb tail.

When frozen, the tail recirculates indefinitely, producing an infinite-sustain effect.

Parameters:

Name	Description
frozen	true to freeze, false for normal decay.

---

EchoNode

interface

org.flixelgdx.audio.FlixelSoundBackend.EchoNode

public static interface EchoNode extends EffectNode

A delay / echo effect node.

Delay time and decay are fixed at construction on platforms backed by MiniAudio. To change them, dispose the current node and add a new one via FlixelSound.addEcho(float, float).

Fields

NOOP

public static final EchoNode NOOP

No-op sentinel returned when no sound factory is available.

---

LowPassNode

interface

org.flixelgdx.audio.FlixelSoundBackend.LowPassNode

public static interface LowPassNode extends EffectNode

A live-controllable low-pass filter effect node.

The cutoff can be read back via FlixelSoundBackend.getCutoff() and adjusted by a delta via FlixelSoundBackend.changeCutoff(...) without needing to combine a getter and setter manually.

Example usage:

LowPassNode muffle = sound.addLowPassMuffle(8000.0);
// Smoothly tighten the filter as the player goes deeper underground:
muffle.changeCutoff(-500.0);  // now 7500 Hz

Fields

NOOP

public static final LowPassNode NOOP

No-op sentinel returned when no sound factory is available.

---

Methods

getCutoff()

public double getCutoff()

Returns the current filter cutoff frequency.

Returns: Cutoff frequency in hertz.

---

changeCutoff(double)

public default void changeCutoff(double amount)

Adds amount to the current cutoff frequency.

Parameters:

Name	Description
amount	Delta in hertz to apply.

---

setCutoff(double)

public void setCutoff(double hz)

Sets the filter cutoff frequency.

Frequencies above the cutoff are progressively attenuated.

Parameters:

Name	Description
hz	Cutoff frequency in hertz; must be positive and below the Nyquist frequency.

---