pulpcore.sound
Class Sound

java.lang.Object
  pulpcore.sound.Sound

Direct Known Subclasses:

SoundSequence

public abstract class Sound
extends Object

The Sound class is a base class for sampled sound.

See Also:

SoundSequence

Constructor Summary

Sound(int sampleRate)
Creates a new Sound with the specified sample rate.

Method Summary

long	getDuration() Gets the duration of this clip in milliseconds.
abstract int	getNumFrames() Gets the length of this sound, expressed in the number of frames.
int	getSampleRate() Returns the sample rate - the number of samples played per second, per channel.
abstract void	getSamples(byte[] dest, int destOffset, int destChannels, int srcFrame, int numFrames) Copies a sequence of samples from this Sound to a byte array as signed, little endian, 16-bit PCM format.
int	getSampleSize() Returns the sample size - the number of bytes in each sample.
static Sound	load(byte[] data, int sampleRate, boolean stereo) Creates an sound clip with the specified samples (signed, little endian, 16-bit PCM format).
static Sound	load(String soundAsset) Loads a sound from the the asset catalog.
Playback	loop() Loops this sound clip.
Playback	loop(Fixed level) Loops this sound clip with the specified volume level (0.0 to 1.0).
Playback	loop(Fixed level, Fixed pan) Loops this sound clip with the specified volume level (0.0 to 1.0) and pan (-1.0 to 1.0).
Playback	play() Plays this sound clip.
Playback	play(Fixed level) Plays this sound clip with the specified colume level (0.0 to 1.0).
Playback	play(Fixed level, Fixed pan) Plays this sound clip with the specified level (0.0 to 1.0) and pan (-1.0 to 1.0).
Playback	play(Fixed level, Fixed pan, boolean loop) Plays this sound clip with the specified level (0.0 to 1.0) and pan (-1.0 to 1.0), optionally looping.

Methods inherited from class java.lang.Object

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

Constructor Detail

Sound

public Sound(int sampleRate)

Creates a new Sound with the specified sample rate.

Parameters:

sampleRate - the sample rate (samples per second, per channel).

Method Detail

getSampleRate

public final int getSampleRate()

Returns the sample rate - the number of samples played per second, per channel.

getSampleSize

public final int getSampleSize()

Returns the sample size - the number of bytes in each sample. This method always returns 2.

getDuration

public final long getDuration()

Gets the duration of this clip in milliseconds.

Returns:

the duration of this clip in milliseconds.

getNumFrames

public abstract int getNumFrames()

Gets the length of this sound, expressed in the number of frames. For mono sounds, a frame is one sample, for stereo sounds, a frame consists of two samples - one for the left channel, and one for the right channel.

getSamples

public abstract void getSamples(byte[] dest,
                                int destOffset,
                                int destChannels,
                                int srcFrame,
                                int numFrames)

Copies a sequence of samples from this Sound to a byte array as signed, little endian, 16-bit PCM format.

Parameters:

dest - the destination buffer.

destOffset - the offset, in bytes, in the destination buffer.

destChannels - The number of channels of the destination (1 or 2).

srcFrame - the frame position to start copying from.

numFrames - the number of frames to copy.

play

public final Playback play()

Plays this sound clip. The Sound is played at full volume with no panning.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

play

public final Playback play(Fixed level)

Plays this sound clip with the specified colume level (0.0 to 1.0). The level may have a property animation attached.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

play

public final Playback play(Fixed level,
                           Fixed pan)

Plays this sound clip with the specified level (0.0 to 1.0) and pan (-1.0 to 1.0). The level and pan may have a property animation attached.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

play

public Playback play(Fixed level,
                     Fixed pan,
                     boolean loop)

Plays this sound clip with the specified level (0.0 to 1.0) and pan (-1.0 to 1.0), optionally looping. The level and pan may have a property animation attached.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

loop

public final Playback loop()

Loops this sound clip. The Sound is played at full volume with no panning.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

loop

public final Playback loop(Fixed level)

Loops this sound clip with the specified volume level (0.0 to 1.0). The level may have a property animation attached.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

loop

public final Playback loop(Fixed level,
                           Fixed pan)

Loops this sound clip with the specified volume level (0.0 to 1.0) and pan (-1.0 to 1.0). The level and pan may have a property animation attached.

Returns:

a Playback object for this unique sound playback (one Sound can have many simultaneous Playback objects) or null if the sound could not be played.

See Also:

SoundEvent, CoreSystem.setMute(boolean), CoreSystem.isMute()

load

public static Sound load(byte[] data,
                         int sampleRate,
                         boolean stereo)

Creates an sound clip with the specified samples (signed, little endian, 16-bit PCM format).

Returns:

The sound, or a zero-length Sound on error.

load

public static Sound load(String soundAsset)

Loads a sound from the the asset catalog. The sound can either be a .au file (8-bit u-law) or a .wav file (16-bit, signed, PCM). Both mono and stereo is supported.

Ogg Vorbis is supported with an add-on. See http://code.google.com/p/pulpcore/wiki/OggHowTo for details.

This method never returns null. If the sound cannot be loaded, or there is no sound engine available, a zero-length Sound is returned.

Sounds are internally cached (using a WeakReference), and if the sound was previously loaded, this method may return the same reference.

Parameters:

soundAsset - The name of a AU, WAV, or OGG sound file.

Returns:

The sound, or a zero-length Sound on error.