Sound

Sound

The Sound class is used to control the playback of audio sources using the Web Audio API.

Constructor

new Sound()

Members

container :AudioContainer

The AudioContainer which controls playback

Type:

context

A convenience reference to the sound context used by the application

currentTime

The current playback time of the sound

duration :number

The total sound duration, in seconds

Type:
  • number

events :Object

Registered event callbacks

Type:
  • Object

failed :boolean

Did the contained audio node fail to load?

Type:
  • boolean

gain :AudioParam

A reference to the GainNode parameter which controls volume

Type:
  • AudioParam

id :number

The numeric identifier for accessing this node

Type:
  • number

loaded :boolean

Is the contained audio node loaded and ready for playback?

Type:
  • boolean

loading :Promise

If this Sound source is currently in the process of loading, this attribute contains a Promise that will resolve when the loading process completes.

Type:
  • Promise

loop :boolean

Is the Sound current looping?

Type:
  • boolean

node

A reference to the audio source node being used by the AudioContainer

pausedTime :number

The time in seconds at which playback was paused

Type:
  • number

playing :boolean

Is the audio source currently playing?

Type:
  • boolean

src :string

The audio source path

Type:
  • string

startTime :number

The time in seconds at which playback was started

Type:
  • number

volume

The volume at which the Sound is playing

Methods

(protected) _onEnd()

Called when playback concludes naturally

(protected) _onLoad()

Called when the audio buffer is first loaded

(protected) _onPause()

Called when playback is paused

(protected) _onStart()

Called when the sound begins playing

(protected) _onStop()

Called when playback is stopped (prior to naturally reaching the end)

emit(eventName)

Trigger registered callback functions for a specific event name.

Parameters:
Name Type Description
eventName string

The event name being emitted

(async) fade(volume, optionsopt) → {Promise.<void>}

Fade the volume for this sound between its current level and a desired target volume

Parameters:
Name Type Attributes Default Description
volume number

The desired target volume level between 0 and 1
options object <optional>
 {}

Additional options that configure the fade operation

Properties
Name Type Attributes Default Description
duration number <optional>
 1000

The duration of the fade effect in milliseconds
from number <optional>

A volume level to start from, the current volume by default
type string <optional>
 linear

The type of fade easing, "linear" or "exponential"
Returns:

A Promise that resolves after the requested fade duration

Type
Promise.<void>

(async) load(optionsopt) → {Promise.<Sound>}

Load the audio source, creating an AudioBuffer. Audio loading is idempotent, it can be requested multiple times but only the first load request will be honored.

Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Additional options which affect resource loading

Properties
Name Type Attributes Default Description
autoplay boolean <optional>
 false

Automatically begin playback of the audio source once loaded
autoplayOptions object <optional>

Additional options passed to the play method when loading is complete
Returns:

The Sound once its source audio buffer is loaded

Type
Promise.<Sound>

off(eventName, fn)

Deactivate an event handler which was previously registered for a specific event

Parameters:
Name Type Description
eventName string

The event name being deactivated
fn number | function

The callback ID or callback function being un-registered

on(eventName, fn, optionsopt)

Register an event handler to take actions for a certain Sound event.

Parameters:
Name Type Attributes Default Description
eventName string

The event name being deactivated
fn function

The callback function to trigger when the event occurs
options object <optional>
 {}

Additional options that affect callback registration

Properties
Name Type Attributes Default Description
once boolean <optional>
 false

Trigger the callback once only and automatically un-register it

pause()

Pause playback, remembering the playback position in order to resume later.

play(optionsopt)

Begin playback for the sound node

Parameters:
Name Type Attributes Default Description
options object <optional>
 {}

Options which configure playback

Properties
Name Type Attributes Default Description
loop boolean <optional>
 false

Whether to loop the audio automatically
offset number <optional>

A specific offset in seconds at which to begin playback
volume number <optional>

The desired volume at which to begin playback
fade number <optional>
 0

Fade volume changes over a desired duration in milliseconds

schedule(fn, playbackTime) → {Promise.<null>}

Schedule a function to occur at the next occurrence of a specific playbackTime for this Sound.

Example
sound.schedule(() => console.log("Do something exactly 30 seconds into the track"), 30);
sound.schedule(() => console.log("Do something next time the track loops back to the beginning"), 0);
sound.schedule(() => console.log("Do something 5 seconds before the end of the track"), sound.duration - 5);
Parameters:
Name Type Description
fn function

A function that will be called with this Sound as its single argument
playbackTime number

The desired playback time at which the function should be called
Returns:

A Promise which resolves once the scheduled function has been called

Type
Promise.<null>

stop()

Stop playback, fully resetting the Sound to a non-playing state.