org.cell2d

Class Music

java.lang.Object

org.cell2d.Music

All Implemented Interfaces:

Loadable

public class Music
extends java.lang.Object
implements Loadable

A Music track is a piece of music that can be played in the background of a CellGame. All playing and stopping of Music tracks is controlled by methods of a CellGame, so that the CellGame can keep track of the Music tracks in its music stack.

Like other Loadables, Music tracks can be manually loaded and unloaded into and out of memory. Loading may take a moment, but while a Music track is not loaded, it cannot play.

Music tracks can be played at different speeds from 0 up, with a speed of 0 pausing the Music track and a speed of 1 causing no speed change. They can also be played at different volumes between 0 and 1, with a volume of 0 making the Music track inaudible and a volume of 1 causing no volume change. Finally, the Music class has a global volume between 0 and 1, by which the effective volumes of all currently playing Music tracks are scaled. The global volume is 1 by default.

See Also:

CellGame

Field Summary

Fields

Modifier and Type	Field and Description
static Music	BLANK A blank Music track that produces no sound and plays indefinitely.

Constructor Summary

Constructors

Constructor and Description
Music(java.lang.String path, boolean load) Constructs a Music track from an audio file.
Music(java.lang.String path, double loopStart, double loopEnd, boolean load) Constructs a Music track from an audio file.

Method Summary

Modifier and Type	Method and Description
void	fadeOut(double duration) Instructs the music player to gradually fade this Music track's volume to 0 over the specified duration, stopping this Music track once it is silent, if it is currently playing.
void	fadeSpeed(double speed, double duration) Instructs the music player to gradually fade this Music track's speed to the specified speed over the specified duration, if this Music track is currently playing.
void	fadeVolume(double volume, double duration) Instructs the music player to gradually fade this Music track's volume to the specified volume over the specified duration, if this Music track is currently playing.
static double	getGlobalVolume() Returns the global music volume.
double	getPosition() Returns the music player's position in seconds in this Music track, or 0 if it is not currently playing.
double	getSpeed() Returns the speed at which this Music track is playing, or 0 if it is not currently playing.
double	getVolume() Returns the volume at which this Music track is playing, or 0 if it is not currently playing.
boolean	isLoaded() Returns whether this Loadable is loaded.
boolean	isLooping() Returns whether this Music track is currently looping indefinitely.
boolean	isPaused() Returns whether this Music track is currently paused.
boolean	isPlaying() Returns whether this Music track is currently playing.
boolean	load() Loads this Loadable if it is not already loaded.
void	pause() Pauses this Music track if it is currently playing.
void	resume() Resumes playing this Music track if it currently paused.
static void	setGlobalVolume(double volume) Sets the global music volume to the specified value.
void	setLooping(boolean loop) Sets whether this Music track is looping indefinitely, if it is currently playing.
void	setPosition(double position) Sets the music player's position in seconds in this Music track, if it is currently playing.
void	setSpeed(double speed) Sets the speed at which this Music track is playing if it is currently playing.
void	setVolume(double volume) Sets the volume at which this Music track is playing if it is currently playing.
boolean	unload() Unloads this Loadable if it is currently loaded.

Methods inherited from class java.lang.Object

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

Field Detail

BLANK

public static final Music BLANK

A blank Music track that produces no sound and plays indefinitely. It is considered to be always looping, never paused, and with a position, speed, and volume of 0.

Constructor Detail

Music

public Music(java.lang.String path,
             boolean load)

Constructs a Music track from an audio file. Files of WAV and OGG formats are supported. When this Music track is looping, it will return to the start of the track once it reaches the end.

Parameters:

path - The relative path to the audio file

load - Whether this Music track should load upon creation

Music

public Music(java.lang.String path,
             double loopStart,
             double loopEnd,
             boolean load)

Constructs a Music track from an audio file. Files of WAV and OGG formats are supported.

Parameters:

path - The relative path to the audio file

loopStart - The position in seconds in this Music track to which it should return at the start of a loop

loopEnd - The position in seconds in this Music track that, when reached, causes it to start a new loop if it is looping. If this is negative, this Music track will start a new loop when it reaches the end of the track.

load - Whether this Music track should load upon creation

Method Detail

getGlobalVolume

public static double getGlobalVolume()

Returns the global music volume.

Returns:

The global music volume

setGlobalVolume

public static void setGlobalVolume(double volume)

Sets the global music volume to the specified value.

Parameters:

volume - The new global music volume

isLoaded

public final boolean isLoaded()

Description copied from interface: Loadable

Returns whether this Loadable is loaded.

Specified by:

isLoaded in interface Loadable

Returns:

Whether this Loadable is loaded

load

public final boolean load()

Description copied from interface: Loadable

Loads this Loadable if it is not already loaded.

Specified by:

load in interface Loadable

Returns:

Whether the loading occurred

unload

public final boolean unload()

Description copied from interface: Loadable

Unloads this Loadable if it is currently loaded.

Specified by:

unload in interface Loadable

Returns:

Whether the unloading occurred

isPlaying

public final boolean isPlaying()

Returns whether this Music track is currently playing. A Music track counts as playing when it is paused.

Returns:

Whether this Music track is currently playing

isPaused

public final boolean isPaused()

Returns whether this Music track is currently paused.

Returns:

Whether this Music track is currently paused

pause

public final void pause()

Pauses this Music track if it is currently playing.

resume

public final void resume()

Resumes playing this Music track if it currently paused.

getPosition

public final double getPosition()

Returns the music player's position in seconds in this Music track, or 0 if it is not currently playing.

Returns:

The music player's position in seconds in this Music track

setPosition

public final void setPosition(double position)

Sets the music player's position in seconds in this Music track, if it is currently playing.

Parameters:

position - The music player's new position in seconds in this Music track

getSpeed

public final double getSpeed()

Returns the speed at which this Music track is playing, or 0 if it is not currently playing.

Returns:

The speed at which this Music track is playing

setSpeed

public final void setSpeed(double speed)

Sets the speed at which this Music track is playing if it is currently playing. If this Music track's speed is fading, the fade will be interrupted.

Parameters:

speed - The speed at which this Music track should play

fadeSpeed

public final void fadeSpeed(double speed,
                            double duration)

Instructs the music player to gradually fade this Music track's speed to the specified speed over the specified duration, if this Music track is currently playing.

Parameters:

speed - This Music track's eventual speed

duration - The fade's duration in seconds

getVolume

public final double getVolume()

Returns the volume at which this Music track is playing, or 0 if it is not currently playing.

Returns:

The volume at which this Music track is playing

setVolume

public final void setVolume(double volume)

Sets the volume at which this Music track is playing if it is currently playing. If this Music track's volume is fading, the fade will be interrupted.

Parameters:

volume - The volume at which this Music track should play

fadeVolume

public final void fadeVolume(double volume,
                             double duration)

Instructs the music player to gradually fade this Music track's volume to the specified volume over the specified duration, if this Music track is currently playing.

Parameters:

volume - This Music track's eventual volume

duration - The fade's duration in seconds

fadeOut

public final void fadeOut(double duration)

Instructs the music player to gradually fade this Music track's volume to 0 over the specified duration, stopping this Music track once it is silent, if it is currently playing.

Parameters:

duration - The duration in seconds of the fade-out

isLooping

public final boolean isLooping()

Returns whether this Music track is currently looping indefinitely.

Returns:

Whether this Music track is currently looping indefinitely

setLooping

public final void setLooping(boolean loop)

Sets whether this Music track is looping indefinitely, if it is currently playing.

Parameters:

loop - Whether this Music track should loop indefinitely