playn.core

Class Sound

java.lang.Object

playn.core.Sound

Direct Known Subclasses:

Sound.Error, SoundImpl

public class Sound
extends Object

A single sound asset, which can be played, looped, etc.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Sound.Error Represents a sound that failed to load.

Field Summary

Fields

Modifier and Type	Field and Description
RFuture<Sound>	state Reports the asynchronous loading of this sound.

Constructor Summary

Constructors

Constructor and Description
Sound() Creates the sound of silence.

Method Summary

Modifier and Type	Method and Description
boolean	isLoaded() Returns whether this sound is fully loaded.
boolean	isPlaying() Determine whether this audio stream is currently playing.
boolean	play() If possible, begin playback of this audio stream.
boolean	prepare() Prepares this sound to be played by preloading it into audio buffers.
void	release() Releases resources used by this sound.
void	setLooping(boolean looping) Set whether audio stream playback should be looped indefinitely or not.
void	setVolume(float volume)
void	stop() Stop playback of the current audio stream as soon as possible, and reset the sound position to its starting position, such that a subsequent call to play() will cause the audio file to being playback from the beginning of the audio stream.
float	volume()

Methods inherited from class java.lang.Object

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

Field Detail

state

public final RFuture<Sound> state

Reports the asynchronous loading of this sound. This will be completed with success or failure when the sound's asynchronous load completes.

Constructor Detail

Sound

public Sound()

Creates the sound of silence.

Method Detail

isLoaded

public boolean isLoaded()

Returns whether this sound is fully loaded. In general you'll want to react to state to do things only after a sound is loaded, but this method is useful if you want to just skip playing a sound that's not fully loaded (because playing a sound that's not loaded will defer the play request until it has loaded, which may result in mismatched audio and visuals).

Note: this is different from prepare(). This has to do with loading the sound bytes from storage (or over the network in the case of the HTML backend). prepare() attempts to ensure that the sound bytes are then transferred from CPU memory into the appropriate audio buffers so that they can be played with the lowest possible latency.

prepare

public boolean prepare()

Prepares this sound to be played by preloading it into audio buffers. This expresses a desire to have subsequent calls to play() start emitting sound with the lowest possible latency.

Returns:

true if preloading occurred, false if unsupported or preloading failed

play

public boolean play()

If possible, begin playback of this audio stream. The audio system will make best efforts to playback this sound. However, lack of audio or codec support, or a (temporary) unavailability of audio channels may prevent playback. If the audio system is certain that audio playback failed, this method will return false. However, a return value of true does not guarantee that playback will in fact succeed.

Returns:

true if it's likely that audio playback will proceed

stop

public void stop()

Stop playback of the current audio stream as soon as possible, and reset the sound position to its starting position, such that a subsequent call to play() will cause the audio file to being playback from the beginning of the audio stream.

setLooping

public void setLooping(boolean looping)

Set whether audio stream playback should be looped indefinitely or not.

Parameters:

looping - true if the audio stream should be looped indefinitely

volume

public float volume()

Returns:

the current volume of this sound, a value between 0.0 and 1.0.

setVolume

public void setVolume(float volume)

Parameters:

volume - new volume between 0.0 and 1.0

isPlaying

public boolean isPlaying()

Determine whether this audio stream is currently playing.

Returns:

true if the audio stream is currently playing

release

public void release()

Releases resources used by this sound. It will no longer be usable after release. This will also happen automatically when this sound is garbage collected, but one may need to manually release sounds sooner to avoid running out of audio resources.