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

Inheritance diagram for Sound:

Collaboration diagram for Sound:

Public Member Functions
	changeOffsetX (int targetOffset, int msDuration, int easing=linearTween)
	change the left/right positioning of the sound's origin over time More...

	changePitch (number targetOffset, int msDuration, int easing=easeInOutQuad)
	change the pitch of a sound over time (NOT IMPLEMENTED) More...

	changeVolume (number level, uint fadeMs, int easing=linearTween)
	change sounds volume to target level over time More...

	fadeIn (uint fadeMs, int easing=linearTween)
	fade the sound in from zero to full volume over time More...

	fadeOut (uint fadeMs, int easing=linearTween)
	fade the sound out to silence over time More...

number	getVolume ()
	get the current volume level for this sound More...

boolean	isLooping ()
	find out if this sound is set to loop More...

boolean	isPaused ()
	find out if a sound is paused More...

IEventHandler	on (int eventCode, function func)
	set a handler for a particular sound event More...

IEventHandler	onDonePlaying (function func)
	set a handler for when the sound finishes playing More...

IEventHandler	onFailedToPlay (function func)
	set a handler for if the sound fails to play More...

IEventHandler	onLooping (function func)
	set a handler for when the sound reaches the end and loops More...

	pause ()
	stop a sound playing until resumed More...

	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 More...

	resume ()
	unpause a sound that was paused More...

Sound	setLooping (boolean loopingOn)
	set if the sound should loop or not More...

Sound	setOffsetX (int offsetX)
	set the left/right positioning of the sound's origin More...

Sound	setPitch (number pitchOffset)
	set the pitch of a sound More...

Sound	setVolume (number inVolume)
	set the volume level for a sound More...

Sound	skip (int skipMilliseconds)
	skip ahead or back in a sound More...

Sound	skipTo (uint timeMs)
	skipTo a particular time position in a sound More...

	start ()
	start playing a sound More...

	stop ()
	stop a sound from playing More...

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. More...

	blockEvent (int inEventType)
	temporarily ignore all events of a particular type. More...

	clear ()
	remove all handlers More...

	removeHandler (IEventHandler inHandler, int inEventType=all_events)
	remove a handler for some event type, or for all events (see note) if no type specified. More...

	unblockEvent (int inEventType)
	stop ignoring events of a particular type More...

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

targetOffset	the target X offset from the center of the main view port
msDuration	the amount of time to get there
easing	the 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

level	the target level
fadeMs	the time to take for sound to reach the new volume level
easing	the 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

fadeMs	the time to take for sound to reach full volume
easing	the 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

fadeMs	the time to take for sound to fade out completely
easing	the 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

vol	the volume level from 0.0 to 1.0, defaults to 1.0
offsetX	the 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).
pitch	the amount to shift the pitch -1.0 is down one octave, +1.0 is up one octave.
fromMs	start the sound from a particular ms time mark
lenMs	the 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

offsetX the 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

pitchOffset a 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

inVolume a 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

skipMilliseconds the amount of time to skip. Negative values are backwards.

skipTo ( uint timeMs )

skipTo a particular time position in a sound

Parameters

timeMs the 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

Public Member Functions

Detailed Description

Fire and Forget Playback

Dynamic Playback

Member Function Documentation

User Comments