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 class provides all methods to playback 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() Instantiates a new SoundEngine instance.

Method Summary

Modifier and Type	Method and Description
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()
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.
void	playMusic(Sound music)
void	playMusic(java.lang.String music)
void	playMusic(Track track) Sets the currently playing track to the specified track.
void	playMusic(Track track, boolean restart) Sets the currently playing track to the specified track.
void	playMusic(Track track, boolean restart, boolean stop) Plays the specified track.
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)
SFXPlayback	playSound(Sound sound, double x, double y, boolean loop)
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 sound)
SFXPlayback	playSound(java.lang.String sound, boolean loop)
SFXPlayback	playSound(java.lang.String sound, double x, double y)
SFXPlayback	playSound(java.lang.String sound, double x, double y, boolean loop)
SFXPlayback	playSound(java.lang.String sound, IEntity entity)
SFXPlayback	playSound(java.lang.String sound, IEntity entity, boolean loop)
SFXPlayback	playSound(java.lang.String sound, java.awt.geom.Point2D location)
SFXPlayback	playSound(java.lang.String sound, java.awt.geom.Point2D location, boolean loop)
void	setListenerLocationCallback(java.util.function.Function<java.awt.geom.Point2D,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 need to update their attributes.

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

Instantiates a new SoundEngine instance.

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 void playMusic(java.lang.String music)

playMusic

public void playMusic(Sound music)

playMusic

public void 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

playMusic

public void 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)

playMusic

public void 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

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

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 sound,
                             IEntity entity)

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 sound,
                             IEntity entity,
                             boolean loop)

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 sound,
                             java.awt.geom.Point2D location)

playSound

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

playSound

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

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 sound,
                             java.awt.geom.Point2D location,
                             boolean loop)

playSound

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

playSound

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

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 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 sound,
                             boolean loop)

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.

setListenerLocationCallback

public void setListenerLocationCallback(java.util.function.Function<java.awt.geom.Point2D,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 need to update their attributes. It is called on every tick, means, it is called Game.GameLoop.TICKS_PER_SECOND times per second.

Specified by:

update in interface IUpdateable