com.crickettechnology.audio
Class Sound

java.lang.Object
  com.crickettechnology.audio.Sound

public final class Sound
extends java.lang.Object

A sound (either memory-resident or streamed).

SOUND_SPEED_CENTIMETERS_PER_SECOND

public static final float SOUND_SPEED_CENTIMETERS_PER_SECOND

The speed of sound in dry air at 20 degrees C, in centimeters per second. This value is provided as a convenience for set3dSoundSpeed().

See Also:

Constant Field Values

SOUND_SPEED_METERS_PER_SECOND

public static final float SOUND_SPEED_METERS_PER_SECOND

The speed of sound in dry air at 20 degrees C, in meters per second. This value is provided as a convenience for set3dSoundSpeed().

See Also:

Constant Field Values

SOUND_SPEED_INCHES_PER_SECOND

public static final float SOUND_SPEED_INCHES_PER_SECOND

The speed of sound in dry air at 20 degrees C, in inches per second. This value is provided as a convenience for set3dSoundSpeed().

See Also:

Constant Field Values

SOUND_SPEED_FEET_PER_SECOND

public static final float SOUND_SPEED_FEET_PER_SECOND

The speed of sound in dry air at 20 degrees C, in feet per second. This value is provided as a convenience for set3dSoundSpeed().

See Also:

Constant Field Values

setMixer

public void setMixer(Mixer mixer)

Sets the mixer to which this sound is assigned. Setting null will assign it to the master mixer.

getMixer

public Mixer getMixer()

Gets the mixer to which this sound is assigned.

isReady

public boolean isReady()

Returns true if the sound is ready. Bank sounds are ready immediately after creation; stream sounds may not be.

isFailed

public boolean isFailed()

Returns true if an error occurred while creating the sound.

play

public void play()

Play the sound.

stop

public void stop()

Stop the sound.

isPlaying

public boolean isPlaying()

Gets whether the sound is playing.

setPaused

public void setPaused(boolean paused)

Sets whether the sound is paused.

isPaused

public boolean isPaused()

Gets whether the sound is paused.

setLoop

public void setLoop(int startFrame,
                    int endFrame)

Set the loop start and end. Default is to loop over all sample frames. EndFrame is defined as one frame after the last frame of the loop. Setting endFrame = -1 is equivalent to setting it to getLength().

getLoop

public void getLoop(IntRef startFrame,
                    IntRef endFrame)

Get the loop start and end.

setLoopCount

public void setLoopCount(int loopCount)

Sets the number of times the sound should loop.

• 0 means no looping (play once and then stop).
• 1 means it will play twice; 2 means it will play 3 times; etc.
• -1 means it will loop indefinitely until the sound is stopped or releaseLoop() is called.

getLoopCount

public int getLoopCount()

Gets the number of times the sound should loop.

• 0 means no looping (play once and then stop).
• 1 means it will play twice; 2 means it will play 3 times; etc.
• -1 means it will loop indefinitely until the sound is stopped or releaseLoop() is called.

getCurrentLoop

public int getCurrentLoop()

Gets the number of the current loop. For example, returns 0 if this is the first time playing through this sample; returns 1 if it is on its second loop through the sample; etc.

releaseLoop

public void releaseLoop()

Makes the current loop the last. This is useful when you don't know in advance how many times you will want to loop; set the loop count to -1, and call releaseLoop() when you want it to stop looping and play to the end.

setPlayPosition

public void setPlayPosition(int frame)

Set the play position in the sound, in sample frames. This can be called before playing, to start from an offset into the sound; or during playback, to jump to a new location.

This is not supported for streams in formats other than .cks; use setPlayPositionMs() instead when possible.

setPlayPositionMs

public void setPlayPositionMs(float ms)

Set the play position in the sound, in milliseconds. This can be called before playing, to start from an offset into the sound; or during playback, to jump to a new location.

getPlayPosition

public int getPlayPosition()

Get the current play position in the sound, in sample frames.

This is not supported for streams in formats other than .cks; use getPlayPositionMs() instead when possible.

getPlayPositionMs

public float getPlayPositionMs()

Get the current play position in the sound, in milliseconds.

setVolume

public void setVolume(float volume)

Sets the volume. The volume can range from 0 to 1. The default value is 1.

getVolume

public float getVolume()

Gets the volume. The volume can range from 0 to 1. The default value is 1.

getMixedVolume

public float getMixedVolume()

Gets the volume value used for mixing. This is the product of the volume set with setVolume() and the mixed volume value of the mixer to which the sound is assigned.

setPan

public void setPan(float pan)

Sets the pan. The pan can range from -1 (left) to +1 (right). The default is 0 (center).

getPan

public float getPan()

Gets the pan. The pan can range from -1 (left) to +1 (right). The default is 0 (center).

setPanMatrix

public void setPanMatrix(float ll,
                         float lr,
                         float rl,
                         float rr)

Sets the pan matrix explicitly. The pan matrix determines how the left and right channels of an input are weighted during mixing. Usually it is set by setPan(), but you can use setPanMatrix() if you need more control. For a mono input, the left channel of the output is the input scaled by ll, and the right channel of the output is the input scaled by rr. The off-diagonal lr and rl terms are ignored. For a stereo input, the left channel of the output is the left channel of the input scaled by ll plus the right channel of the input scaled by lr. The right channel of the output is the left channel of the input scaled by rl plus the right channel of the input scaled by rr.

getPanMatrix

public void getPanMatrix(FloatRef ll,
                         FloatRef lr,
                         FloatRef rl,
                         FloatRef rr)

Gets the pan matrix. The pan matrix determines how the left and right channels of an input are weighted during mixing. Usually it is set by setPan(), but you can use setPanMatrix() if you need more control. For a mono input, the left channel of the output is the input scaled by ll, and the right channel of the output is the input scaled by rr. The off-diagonal lr and rl terms are ignored. For a stereo input, the left channel of the output is the left channel of the input scaled by ll plus the right channel of the input scaled by lr. The right channel of the output is the left channel of the input scaled by rl plus the right channel of the input scaled by rr.

setPitchShift

public void setPitchShift(float halfSteps)

Sets the pitch shift value, in half-steps. This also changes the playback speed of the sound. Positive values mean higher pitch (and faster playback); lower values mean lower pitch (and slower playback). The default value is 0.

This does not work for streams in formats other than .cks.

getPitchShift

public float getPitchShift()

Gets the pitch shift value, in half-steps. Positive values mean higher pitch (and faster playback); lower values mean lower pitch (and slower playback). The default value is 0.

This does not work for streams in formats other than .cks.

setSpeed

public void setSpeed(float speed)

Sets the playback speed. Values greater than 1 mean faster playback; values less than 1 mean slower playback. The default value is 1.

This does not work for streams in formats other than .cks.

getSpeed

public float getSpeed()

Gets the playback speed. Values greater than 1 mean faster playback; values less than 1 mean slower playback. The default value is 1.

This does not work for streams in formats other than .cks.

getLength

public int getLength()

Gets the total duration of the sound, in sample frames. Stream sounds will return -1 if they are not ready.

This does not work for streams in formats other than .cks; use getLengthMs() instead.

getLengthMs

public float getLengthMs()

Gets the total duration of the sound, in milliseconds. Stream sounds will return -1 if they are not ready.

getSampleRate

public int getSampleRate()

Gets the sample rate of the sound, in Hz. Stream sounds will return -1 if they are not ready.

This does not work for streams in formats other than .cks.

getChannels

public int getChannels()

Gets the number of channels in the sound (1 for mono, 2 for stereo). Stream sounds will return -1 if they are not ready.

set3dEnabled

public void set3dEnabled(boolean enabled)

Sets whether 3D positioning is enabled. If enabled, pan will be determined by the sound and listener positions, ignoring the value set by setPan(). Volume will be attenuated based on the sound and listener positions and the attenuation settings.

is3dEnabled

public boolean is3dEnabled()

Gets whether 3D positioning is enabled. If enabled, pan will be determined by the sound and listener positions, ignoring the value set by setPan(). Volume will be attenuated based on the sound and listener positions and the attenuation settings.

set3dPosition

public void set3dPosition(float x,
                          float y,
                          float z)

Sets the position of the sound emitter in 3D space. This is used for pan and volume calculations when 3D positioning is enabled.

get3dPosition

public void get3dPosition(FloatRef x,
                          FloatRef y,
                          FloatRef z)

Gets the position of the sound emitter in 3D space. This is used for pan and volume calculations when 3D positioning is enabled.

set3dVelocity

public void set3dVelocity(float x,
                          float y,
                          float z)

Sets the velocity of the sound emitter in 3D space. This is used for doppler shift calculations when 3D positioning is enabled.

get3dVelocity

public void get3dVelocity(FloatRef x,
                          FloatRef y,
                          FloatRef z)

Gets the velocity of the sound emitter in 3D space. This is used for doppler shift calculations when 3D positioning is enabled.

set3dListenerPosition

public static void set3dListenerPosition(float eyeX,
                                         float eyeY,
                                         float eyeZ,
                                         float lookAtX,
                                         float lookAtY,
                                         float lookAtZ,
                                         float upX,
                                         float upY,
                                         float upZ)

Sets the listener position and rotation in 3D space. This is used for pan and volume calculations when 3D positioning is enabled.

Parameters:

eyeX - The listener's position (x coordinate)

eyeY - The listener's position (y coordinate)

eyeZ - The listener's position (z coordinate)

lookAtX - The listener's look-at point (x coordinate)

lookAtY - The listener's look-at point (y coordinate)

lookAtZ - The listener's look-at point (z coordinate)

upX - The listener's up vector (x coordinate)

upY - The listener's up vector (y coordinate)

upZ - The listener's up vector (z coordinate)

get3dListenerPosition

public static void get3dListenerPosition(FloatRef eyeX,
                                         FloatRef eyeY,
                                         FloatRef eyeZ,
                                         FloatRef lookAtX,
                                         FloatRef lookAtY,
                                         FloatRef lookAtZ,
                                         FloatRef upX,
                                         FloatRef upY,
                                         FloatRef upZ)

Gets the listener position and rotation in 3D space. This is used for pan and volume calculations when 3D positioning is enabled.

Parameters:

eyeX - The listener's position (x coordinate)

eyeY - The listener's position (y coordinate)

eyeZ - The listener's position (z coordinate)

lookAtX - The listener's look-at point (x coordinate)

lookAtY - The listener's look-at point (y coordinate)

lookAtZ - The listener's look-at point (z coordinate)

upX - The listener's up vector (x coordinate)

upY - The listener's up vector (y coordinate)

upZ - The listener's up vector (z coordinate)

set3dListenerVelocity

public static void set3dListenerVelocity(float x,
                                         float y,
                                         float z)

Sets the listener velocity in 3D space. This is used for doppler shift calculations when 3D positioning is enabled.

get3dListenerVelocity

public static void get3dListenerVelocity(FloatRef x,
                                         FloatRef y,
                                         FloatRef z)

Gets the listener velocity in 3D space. This is used for doppler shift calculations when 3D positioning is enabled.

set3dAttenuation

public static void set3dAttenuation(AttenuationMode mode,
                                    float nearDist,
                                    float farDist,
                                    float farVol)

Sets parameters used for 3D volume attenuation.

Parameters:

mode - The attenuation mode

nearDist - The near distance; sounds closer than this distance will not be attenuated.

farDist - The far distance; sounds further than this will be at the far volume.

farVol - The far volume; sounds further than farDist will be at this volume.

get3dAttenuation

public static void get3dAttenuation(ObjectRef<AttenuationMode> mode,
                                    FloatRef nearDist,
                                    FloatRef farDist,
                                    FloatRef farVol)

Gets parameters used for 3D volume attenuation.

Parameters:

mode - The attenuation mode

nearDist - The near distance; sounds closer than this distance will not be attenuated.

farDist - The far distance; sounds further than this will be at the far volume.

farVol - The far volume; sounds further than farDist will be at this volume.

set3dSoundSpeed

public static void set3dSoundSpeed(float speed)

Sets the speed of sound. This is used for doppler shift calculations when 3D positioning is enabled. If no doppler shift is desired, this can be set to 0 (which is the default value). You may want to use the predefined constants for the speed of sound (such as SOUND_SPEED_METERS_PER_SECOND); use the constant that corresponds to the unit system you are using for your velocity and position values. You can also exaggerate the doppler effect by using a smaller value.

get3dSoundSpeed

public static float get3dSoundSpeed()

Gets the speed of sound. This is used for doppler shift calculations when 3D positioning is enabled.

newBankSound

public static Sound newBankSound(Bank bank,
                                 int index)

Creates a sound from a bank.

Parameters:

bank - The bank

index - Index of the sound in the bank to create

Returns:

The sound, or null if it could not be created

newBankSound

public static Sound newBankSound(Bank bank,
                                 java.lang.String name)

Creates a sound from a bank.

Parameters:

bank - The bank; if null, all loaded banks will be searched for a sound with a matching name

name - Name of the sound in the bank to create; should be 31 characters or less

Returns:

The sound, or null if it could not be created

newStreamSound

public static Sound newStreamSound(java.lang.String filename,
                                   PathType pathType)

Creates a streaming sound.

Parameters:

filename - Path to the file to stream.

pathType - Indicates how the path is to be interpreted.

Returns:

The sound, or null if it could not be created

newStreamSound

public static Sound newStreamSound(java.lang.String filename)

Creates a streaming sound from an asset in the .apk. Equivalent to newStreamSound(filename, PathType.Asset).

Parameters:

filename - Path to the file to stream.

Returns:

The sound, or null if it could not be created

newNetworkStreamSound

public static Sound newNetworkStreamSound(java.lang.String url)

Creates an HTTP network streaming sound

Parameters:

url - URL of the file to play

Returns:

The sound, or null if it could not be created

destroy

public void destroy()

Destroy this object. This is called when the object is finalized by the garbage collector; however, it is better to call it explicitly, so the object is destroyed predictably.