de.gurkenlabs.litiengine.sound

Class SoundEngine

java.lang.Object

de.gurkenlabs.litiengine.sound.SoundEngine

All Implemented Interfaces:

ILaunchable, IUpdateable

public final class SoundEngine
extends java.lang.Object
implements IUpdateable, ILaunchable

This SoundEngine class provides all methods to play back sounds and music in your game. It allows to define the 2D coordinates of the sound or even pass in the source entity of the sound which will adjust the position according to the position of the entity.

The LILIengine sound engine supports .wav, .mp3 and .ogg by default. If you need other file extensions, you have to write an own SPI implementation and inject it in your project.

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_DISTANCE

Constructor Summary

Constructors

Constructor and Description
SoundEngine() You should never call this manually! Instead use the Game.audio() instance.

Method Summary

Modifier and Type	Method and Description
SFXPlayback	createSound(Sound sound, java.util.function.Supplier<java.awt.geom.Point2D> supplier, boolean loop) Creates an SFXPlayback object that can be configured prior to starting.
void	fadeMusic(int time) Fades out the music over the specified time, if playing.
void	fadeMusic(int time, java.lang.Runnable callback) Fades out the music over the specified time, then calls the provided callback.
java.util.Collection<MusicPlayback>	getAllMusic() Gets a list of all music playbacks.
float	getMaxDistance() Gets the maximum distance from the listener at which a sound source can still be heard.
MusicPlayback	getMusic() Gets the "main" music that is playing.
MusicPlayback	playMusic(Sound music) Sets the currently playing track to a LoopedTrack with the specified music Sound.
MusicPlayback	playMusic(java.lang.String musicName) Sets the currently playing track to a LoopedTrack with the sound defined by the specified music name.
MusicPlayback	playMusic(Track track) Sets the currently playing track to the specified track.
MusicPlayback	playMusic(Track track, boolean restart) Sets the currently playing track to the specified track.
MusicPlayback	playMusic(Track track, boolean restart, boolean stop) Plays the specified track.
MusicPlayback	playMusic(Track track, java.util.function.Consumer<? super MusicPlayback> config, boolean restart, boolean stop) Plays the specified track, optionally configuring it before starting.
SFXPlayback	playSound(Sound sound) Plays the specified sound with the volume configured in the SOUND config with a center pan.
SFXPlayback	playSound(Sound sound, boolean loop) Plays the specified sound with the volume configured in the SOUND config with a center pan.
SFXPlayback	playSound(Sound sound, double x, double y) Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(Sound sound, double x, double y, boolean loop) Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(Sound sound, IEntity entity) Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
SFXPlayback	playSound(Sound sound, IEntity entity, boolean loop) Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.
SFXPlayback	playSound(Sound sound, java.awt.geom.Point2D location) Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(Sound sound, java.awt.geom.Point2D location, boolean loop) Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(java.lang.String soundName) Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.
SFXPlayback	playSound(java.lang.String soundName, boolean loop) Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.
SFXPlayback	playSound(java.lang.String soundName, double x, double y) Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(java.lang.String soundName, double x, double y, boolean loop) Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(java.lang.String soundName, IEntity entity) Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.
SFXPlayback	playSound(java.lang.String soundName, IEntity entity, boolean loop) Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.
SFXPlayback	playSound(java.lang.String soundName, java.awt.geom.Point2D location) Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
SFXPlayback	playSound(java.lang.String soundName, java.awt.geom.Point2D location, boolean loop) Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.
void	setListenerLocationCallback(java.util.function.UnaryOperator<java.awt.geom.Point2D> callback) This method allows to set the callback that is used by the SoundEngine to determine where the listener location is.
void	setMaxDistance(float radius) Sets the maximum distance from the listener at which a sound source can still be heard.
void	start() Starts the operation of this instance.
void	stopMusic() Stops the playback of the current background music.
void	terminate() Terminates the operation of this instance.
void	update() This method is called by the game loop on all objects that are attached to the loop.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_MAX_DISTANCE

public static final int DEFAULT_MAX_DISTANCE

See Also:

Constant Field Values

Constructor Detail

SoundEngine

public SoundEngine()

You should never call this manually! Instead use the Game.audio() instance.

See Also:

Game.audio()

Method Detail

getMaxDistance

public float getMaxDistance()

Gets the maximum distance from the listener at which a sound source can still be heard.

Returns:

The maximum distance at which a sound can be heard.

playMusic

public MusicPlayback playMusic(java.lang.String musicName)

Sets the currently playing track to a LoopedTrack with the sound defined by the specified music name. This has no effect if the specified track is already playing.

Parameters:

musicName - The name of the Sound to be played.

Returns:

The playback of the music

playMusic

public MusicPlayback playMusic(Sound music)

Sets the currently playing track to a LoopedTrack with the specified music Sound. This has no effect if the specified track is already playing.

Parameters:

music - The Sound to be played.

Returns:

The playback of the music

playMusic

public MusicPlayback playMusic(Track track)

Sets the currently playing track to the specified track. This has no effect if the specified track is already playing.

Parameters:

track - The track to play

Returns:

The playback of the music

playMusic

public MusicPlayback playMusic(Track track,
                               boolean restart)

Sets the currently playing track to the specified track.

Parameters:

track - The track to play

restart - Whether to restart if the specified track is already playing, determined by Object.equals(Object)

Returns:

The playback of the music

playMusic

public MusicPlayback playMusic(Track track,
                               boolean restart,
                               boolean stop)

Plays the specified track.

Parameters:

track - The track to play

restart - Whether to restart if the specified track is already playing, determined by Object.equals(Object)

stop - Whether to stop an existing track if present

Returns:

The playback of the music

playMusic

public MusicPlayback playMusic(Track track,
                               java.util.function.Consumer<? super MusicPlayback> config,
                               boolean restart,
                               boolean stop)

Plays the specified track, optionally configuring it before starting.

Parameters:

track - The track to play

config - A call to configure the playback prior to starting, which can be null

restart - Whether to restart if the specified track is already playing, determined by Object.equals(Object)

stop - Whether to stop an existing track if present

Returns:

The playback of the music

fadeMusic

public void fadeMusic(int time)

Fades out the music over the specified time, if playing.

Parameters:

time - The time in frames to make the existing music fade out for if present

fadeMusic

public void fadeMusic(int time,
                      java.lang.Runnable callback)

Fades out the music over the specified time, then calls the provided callback.

Parameters:

time - The time in frames to make the existing music fade out for if present

callback - The callback for when the fade finishes

getMusic

public MusicPlayback getMusic()

Gets the "main" music that is playing. This usually means the last call to playMusic, though if the music has been stopped it will be null.

Returns:

The main music, which could be null.

getAllMusic

public java.util.Collection<MusicPlayback> getAllMusic()

Gets a list of all music playbacks.

Returns:

A list of all music playbacks.

playSound

public SFXPlayback playSound(Sound sound,
                             IEntity entity)

Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.

Parameters:

entity - The entity at which location the sound should be played.

sound - The sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             IEntity entity)

Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.

Parameters:

entity - The entity at which location the sound should be played.

soundName - The name of the sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound,
                             IEntity entity,
                             boolean loop)

Plays the specified sound and updates its volume and pan by the current entity location in relation to the listener location.

Parameters:

entity - The entity at which location the sound should be played.

sound - The sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             IEntity entity,
                             boolean loop)

Plays a Sound with the specified name and updates its volume and pan by the current entity location in relation to the listener location.

Parameters:

entity - The entity at which location the sound should be played.

soundName - The name of the sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound,
                             java.awt.geom.Point2D location)

Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

location - The location at which to play the sound.

sound - The sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             java.awt.geom.Point2D location)

Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

location - The location at which to play the sound.

soundName - The name of the sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound,
                             double x,
                             double y)

Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

x - The x-coordinate of the location at which to play the sound.

y - The y-coordinate of the location at which to play the sound.

sound - The sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             double x,
                             double y)

Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

x - The x-coordinate of the location at which to play the sound.

y - The y-coordinate of the location at which to play the sound.

soundName - The name of the sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound,
                             java.awt.geom.Point2D location,
                             boolean loop)

Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

location - The location at which to play the sound.

sound - The sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             java.awt.geom.Point2D location,
                             boolean loop)

Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

location - The location at which to play the sound.

soundName - The name of the sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound,
                             double x,
                             double y,
                             boolean loop)

Plays the specified sound at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

x - The x-coordinate of the location at which to play the sound.

y - The y-coordinate of the location at which to play the sound.

sound - The sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             double x,
                             double y,
                             boolean loop)

Plays a Sound with the specified name at the specified location and updates the volume and pan in relation to the listener location.

Parameters:

x - The x-coordinate of the location at which to play the sound.

y - The y-coordinate of the location at which to play the sound.

soundName - The name of the sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound)

Plays the specified sound with the volume configured in the SOUND config with a center pan.

Parameters:

sound - The sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName)

Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.

Parameters:

soundName - The name of the sound to play.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(Sound sound,
                             boolean loop)

Plays the specified sound with the volume configured in the SOUND config with a center pan.

Parameters:

sound - The sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

playSound

public SFXPlayback playSound(java.lang.String soundName,
                             boolean loop)

Plays a Sound with the specified name with the volume configured in the SOUND config with a center pan.

Parameters:

soundName - The name of the sound to play.

loop - Determines whether this playback should be looped or not.

Returns:

An SFXPlayback instance that allows to further process and control the played sound.

setMaxDistance

public void setMaxDistance(float radius)

Sets the maximum distance from the listener at which a sound source can still be heard. If the distance between the sound source and the listener is greater than the specified value, the volume is set to 0.

Parameters:

radius - The maximum distance at which sounds can still be heard.

stopMusic

public void stopMusic()

Stops the playback of the current background music.

createSound

public SFXPlayback createSound(Sound sound,
                               java.util.function.Supplier<java.awt.geom.Point2D> supplier,
                               boolean loop)

Creates an SFXPlayback object that can be configured prior to starting. Also allows for a custom source supplier.

Unlike the playSound methods, the SFXPlayback objects returned by this method must be started using the SoundPlayback.start() method. However, necessary resources are acquired immediately upon calling this method, and will remain in use until the playback is either cancelled or finalized.

Parameters:

sound - The sound to play

supplier - A function to get the sound's current source location (the sound is statically positioned if the location is null)

loop - Whether to loop the sound

Returns:

An SFXPlayback object that can be configured prior to starting, but will need to be manually started.

setListenerLocationCallback

public void setListenerLocationCallback(java.util.function.UnaryOperator<java.awt.geom.Point2D> callback)

This method allows to set the callback that is used by the SoundEngine to determine where the listener location is. If not explicitly set, the SoundEngine uses the camera focus (center of the screen) as listener location.

Parameters:

callback - The callback that determines the location of the sound listener.

start

public void start()

Description copied from interface: ILaunchable

Starts the operation of this instance.

Specified by:

start in interface ILaunchable

terminate

public void terminate()

Description copied from interface: ILaunchable

Terminates the operation of this instance.

Specified by:

terminate in interface ILaunchable

update

public void update()

Description copied from interface: IUpdateable

This method is called by the game loop on all objects that are attached to the loop. It's called on every tick of the loop and the frequency can be configured using the ClientConfiguration.

Specified by:

update in interface IUpdateable

See Also:

ClientConfiguration.setMaxFps(int)