PDG engine v0.9.5
 All Classes Namespaces Functions Variables Groups Pages
Public Member Functions | List of all members
Sound Class Reference

handles both short sounds and music (GUI Only) More...

Inheritance diagram for Sound:
Inheritance graph
[legend]
Collaboration diagram for Sound:
Collaboration graph
[legend]

Public Member Functions

 changeOffsetX (int targetOffset, int msDuration, int easing=linearTween)
 change the left/right positioning of the sound's origin over time
 
 changePitch (number targetOffset, int msDuration, int easing=easeInOutQuad)
 change the pitch of a sound over time (NOT IMPLEMENTED)
 
 changeVolume (number level, uint fadeMs, int easing=linearTween)
 change sounds volume to target level over time
 
 fadeIn (uint fadeMs, int easing=linearTween)
 fade the sound in from zero to full volume over time
 
 fadeOut (uint fadeMs, int easing=linearTween)
 fade the sound out to silence over time
 
number getVolume ()
 get the current volume level for this sound
 
boolean isLooping ()
 find out if this sound is set to loop
 
boolean isPaused ()
 find out if a sound is paused
 
IEventHandler on (int eventCode, function func)
 set a handler for a particular sound event
 
IEventHandler onDonePlaying (function func)
 set a handler for when the sound finishes playing
 
IEventHandler onFailedToPlay (function func)
 set a handler for if the sound fails to play
 
IEventHandler onLooping (function func)
 set a handler for when the sound reaches the end and loops
 
 pause ()
 stop a sound playing until resumed
 
 play (number vol=1.0, int offsetX=0, number pitch=0, uint fromMs=0, int lenMs=ENTIRE_LENGTH)
 play a sound once with given settings
 
 resume ()
 unpause a sound that was paused
 
Sound setLooping (boolean loopingOn)
 set if the sound should loop or not
 
Sound setOffsetX (int offsetX)
 set the left/right positioning of the sound's origin
 
Sound setPitch (number pitchOffset)
 set the pitch of a sound
 
Sound setVolume (number inVolume)
 set the volume level for a sound
 
Sound skip (int skipMilliseconds)
 skip ahead or back in a sound
 
Sound skipTo (uint timeMs)
 skipTo a particular time position in a sound
 
 start ()
 start playing a sound
 
 stop ()
 stop a sound from playing
 
- Public Member Functions inherited from EventEmitter
 addHandler (IEventHandler inHandler, int inEventType=all_events)
 add a new handler for some event type, or for all events if no type specified.
 
 blockEvent (int inEventType)
 temporarily ignore all events of a particular type.
 
 clear ()
 remove all handlers
 
 removeHandler (IEventHandler inHandler, int inEventType=all_events)
 remove a handler for some event type, or for all events (see note) if no type specified.
 
 unblockEvent (int inEventType)
 stop ignoring events of a particular type
 

Detailed Description

handles both short sounds and music (GUI Only)

Note
API Stability: 2 - Unstable. The API is in the process of settling, but has not yet had sufficient real-world testing to be considered stable. Backwards-compatibility will be maintained if reasonable.

Fire and Forget Playback

This mode is typically used for short sound effects, like a footstep, an explosion, a single note of music, or some other momentary sound that doesn't need to be altered while playing. Use play() for that sort of fire and forget sound.

Fire and Forget Example:

PDG terminal v0.9.4
> pdg.run(); // must be running for sounds to play
> var snd = new pdg.Sound("test/clink1.mp3");
> snd.play();
> snd.play(0.3);

Dynamic Playback

For longer sound effects and music, you will often want more dynamic control over the sound as it plays. The hum of a motor might change pitch and location as the sprite that generates it moves around on the screen. Background music may need to be paused or have it's volume changed independent of other sounds as it plays. Use start() to play those sorts of sounds, then call other methods as needed to alter the sound playback.

Dynamic Playback Example:

PDG terminal v0.9.4
> pdg.run(); // must be running for sounds to play
> var snd = new pdg.Sound("test/Peppy_The-Firing-Squad_YMXB.mp3");
> snd.start();
> snd.setVolume(0.3);
> snd.skip(2000);
> snd.setPitch(1.0); // doesn't work on Windows
> snd.setPitch(0);
> snd.setOffsetX(1000); // full right
> snd.setOffsetX(-500); // half left
> snd.setOffsetX(0); // center
> snd.fadeOut(10000); // fade out over 10 seconds
See Also
play
start

Member Function Documentation

changeOffsetX ( int  targetOffset,
int  msDuration,
int  easing = linearTween 
)

change the left/right positioning of the sound's origin over time

Adjust the apparent left/right positioning of the sound over a period of time to make the sound appear to be coming from a particular location in the view port.

Note
since different speaker setups and screen sizes can change the apparent location, this is a relative location only.
Warning
On Mac OS X this only works if the sound is in stereo, and the OS is version 10.7 (aka Lion) or later. It will fail silently on earlier versions or with mono or multichannel sounds; and the sound will play with center balance.
Parameters
targetOffsetthe target X offset from the center of the main view port
msDurationthe amount of time to get there
easingthe function for calculating the movement rate. Defaults to linearTween (smooth movement with no acceleration or deceleration).
See Also
setOffsetX
GraphicsManager.getMainPort
Easing
changePitch ( number  targetOffset,
int  msDuration,
int  easing = easeInOutQuad 
)

change the pitch of a sound over time (NOT IMPLEMENTED)

Todo:
NOT IMPLEMENTED
changeVolume ( number  level,
uint  fadeMs,
int  easing = linearTween 
)

change sounds volume to target level over time

The change can go in either direction, louder or quieter.

Parameters
levelthe target level
fadeMsthe time to take for sound to reach the new volume level
easingthe function that describes how the volume change should happen, defaults to linearTween (constant rate of change)
See Also
Easing
linearTween
fadeIn ( uint  fadeMs,
int  easing = linearTween 
)

fade the sound in from zero to full volume over time

Parameters
fadeMsthe time to take for sound to reach full volume
easingthe function that describes how the fading should happen, defaults to linearTween (constant rate of change)
See Also
fadeOut
changeVolume
Easing
linearTween
fadeOut ( uint  fadeMs,
int  easing = linearTween 
)

fade the sound out to silence over time

The sound is stopped once it fades out completely.

Parameters
fadeMsthe time to take for sound to fade out completely
easingthe function that describes how the fading should happen, defaults to linearTween (constant rate of change)
See Also
fadeIn
changeVolume
Easing
linearTween
getVolume ( )

get the current volume level for this sound

Returns
a number from 0.0 to 1.0 representing the volume level for this sound.
Note
This is not the absolute volume of the sound, since even at full volume (1.0) the sound's volume is scaled by the SoundManager's master volume
See Also
SoundManager.setVolume
isLooping ( )

find out if this sound is set to loop

Returns
true if the sound will loop when it reaches the end, false if it will not
isPaused ( )

find out if a sound is paused

Returns
true if the sound is currently paused, false if not
Note
a sound that was never started is not considered paused
on ( int  eventCode,
function  func 
)

set a handler for a particular sound event

Remarks
Generally you should use the specific on{Event} calls.
See Also
onDonePlaying()
onFailedToPlay()
onLooping()
onDonePlaying ( function  func)

set a handler for when the sound finishes playing

onFailedToPlay ( function  func)

set a handler for if the sound fails to play

onLooping ( function  func)

set a handler for when the sound reaches the end and loops

pause ( )

stop a sound playing until resumed

play ( number  vol = 1.0,
int  offsetX = 0,
number  pitch = 0,
uint  fromMs = 0,
int  lenMs = ENTIRE_LENGTH 
)

play a sound once with given settings

Can be called multiple times on same sound object, creating overlapping sounds. Internally, play() creates a new sound instance that is automatically cleaned up when the sound has finished playing.

Note
Once you've called play(), the sound will play without interruption as specified. Calling stop(), pause(), setVolume(), etc.. will have no effect; because they operate on the sound you actually have a reference to, not the internally created instance that is actually playing. Only SoundManager.setVolume() and SoundManager.setMute() will affect it. Use start() if you need to affect the sound after it is playing.
Parameters
volthe volume level from 0.0 to 1.0, defaults to 1.0
offsetXthe left/right position offset from the center of the screen for the sound source. The pan/balance for the sound is adjusted accordingly. Negative numbers are from the left, positive to the right. Defaults to zero (no balance adjustment).
pitchthe amount to shift the pitch -1.0 is down one octave, +1.0 is up one octave.
fromMsstart the sound from a particular ms time mark
lenMsthe maximum number of ms to play the sound. If longer than the length of the sound this parameter is ignored. Defaults to playing the entire length of the sound.
See Also
start
Todo:
pitch is not implemented on Windows, and offsetX doesn't work on Mac OS X 10.6 due to an API limitation.
resume ( )

unpause a sound that was paused

Play continues from where it was before it was paused.

setLooping ( boolean  loopingOn)

set if the sound should loop or not

Note
Sounds started with play() never loop
setOffsetX ( int  offsetX)

set the left/right positioning of the sound's origin

Set the apparent left/right positioning of the sound to make the sound appear to be coming from a particular location in the view port.

Note
Since different speaker setups and screen sizes can change the apparent location, this is a relative location only.
Warning
On Mac OS X this only works if the sound is in stereo, and the OS is version 10.7 (aka Lion) or later. It will fail silently on earlier versions or with mono or multichannel sounds; and the sound will play with center balance.
Parameters
offsetXthe target X offset from the center of the main view port
See Also
changeOffsetX
GraphicsManager.getMainPort
setPitch ( number  pitchOffset)

set the pitch of a sound

Raise or lower the pitch of a sound by up to an octave.

Parameters
pitchOffseta value between -1.0 and 1.0, with -1.0 meaning down an octave, and +1.0 being up an octave.
See Also
changePitch
Todo:
Not implemented on Windows
setVolume ( number  inVolume)

set the volume level for a sound

Sets the volume level for this specific sound.

Parameters
inVolumea value between 0.0 and 1.0, where 0 is silent and 1.0 is the max volume allowed by the master volume.
See Also
getVolume
SoundManager.setVolume
SoundManager.setMute
skip ( int  skipMilliseconds)

skip ahead or back in a sound

Parameters
skipMillisecondsthe amount of time to skip. Negative values are backwards.
skipTo ( uint  timeMs)

skipTo a particular time position in a sound

Parameters
timeMsthe location within the sound to skip to
start ( )

start playing a sound

Starts the sound playing. Use start() instead of play() when you want to manipulate the sound as it is playing, since this call allows the use of setVolume(), skip(), skipTo(), pause(), set/changePitch(), and set/changeXOffset() to actually affect playback.

See Also
play
stop
stop ( )

stop a sound from playing

This will free buffers and deallocate other memory, so use pause() if you want to restart the sound again.

See Also
start
pause

User Comments