AudioHelper

AudioHelper

A helper class to provide common functionality for working with the Web Audio API. https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API A singleton instance of this class is available as game#audio.

Constructor

new AudioHelper()

See:

Members

buffers :Map.<string, AudioBuffer>

The set of AudioBuffer objects which are cached for different audio paths

Type:
  • Map.<string, AudioBuffer>

context :AudioContext

The primary Audio Context used to play client-facing sounds. The context is undefined until the user's first gesture is observed.

Type:
  • AudioContext

levelAnalyserNativeInterval :number

The Native interval for the AudioHelper to analyse audio levels from streams Any interval passed to startLevelReports() would need to be a multiple of this value.

Type:
  • number

locked :boolean

A flag for whether video playback is currently locked by awaiting a user gesture

Type:
  • boolean

pending :Array.<function()>

See:

A user gesture must be registered before audio can be played. This Array contains the Sound instances which are requested for playback prior to a gesture. Once a gesture is observed, we begin playing all elements of this Array.

Type:

playing :Map.<number, Sound>

Get a map of the Sound objects which are currently playing.

Type:

sounds :Map.<string, Sound>

The set of singleton Sound instances which are cached for different audio paths

Type:

Methods

(static) _activateSocketListeners()

Open socket listeners which transact ChatMessage data

(static) getDefaultSoundName(src) → {string}

Given an input file path, determine a default name for the sound based on the filename

Parameters:
Name Type Description
src string

An input file path
Returns:

A default sound name for the path

Type
string

(static) hasAudioExtension(src) → {boolean}

Test whether a source file has a supported audio extension type

Parameters:
Name Type Description
src string

A requested audio source path
Returns:

Does the filename end with a valid audio extension?

Type
boolean

(static) inputToVolume(value, orderopt) → {number}

Returns the volume value based on a range input volume control's position. This is using an exponential approximation of the logarithmic nature of audio level perception

Parameters:
Name Type Attributes Default Description
value number | string

Value between [0, 1] of the range input
order number <optional>
 1.5

The exponent of the curve
Returns:
Type
number

(static) play(data, pushopt) → {Sound}

Play a one-off sound effect which is not part of a Playlist

Example
// Play the sound of a locked door for all players
AudioHelper.play({src: "sounds/lock.wav", volume: 0.8, loop: false}, true);
Parameters:
Name Type Attributes Description
data Object

An object configuring the audio data to play

Properties
Name Type Description
src string

The audio source file path, either a public URL or a local path relative to the public directory
volume number

The volume level at which to play the audio, between 0 and 1.
autoplay boolean

Begin playback of the audio effect immediately once it is loaded.
loop boolean

Loop the audio effect and continue playing it until it is manually stopped.
push boolean <optional>

Push the audio sound effect to other connected clients?
Returns:

A Sound instance which controls audio playback.

Type
Sound

(async, static) preloadSound(src) → {Promise.<Sound>}

Begin loading the sound for a provided source URL adding its

Parameters:
Name Type Description
src string

The audio source path to preload
Returns:

The created and loaded Sound ready for playback

Type
Promise.<Sound>

(static) registerSettings()

Register client-level settings for global volume overrides

(static) volumeToInput(volume, orderopt) → {number}

Counterpart to inputToVolume() Returns the input range value based on a volume

Parameters:
Name Type Attributes Default Description
volume number

Value between [0, 1] of the volume level
order number <optional>
 1.5

The exponent of the curve
Returns:
Type
number

awaitFirstGesture()

Register an event listener to await the first mousemove gesture and begin playback once observed

create(options) → {Sound}

Create a Sound instance for a given audio source URL

Parameters:
Name Type Description
options object

Audio creation options

Properties
Name Type Attributes Default Description
src string

The source URL for the audio file
singleton boolean <optional>
 true

Reuse an existing Sound for this source?
preload boolean <optional>
 false

Begin loading the audio immediately?
autoplay boolean <optional>
 false

Begin playing the audio as soon as it is ready?
autoplayOptions object <optional>
 {}

Additional options passed to the play method if autoplay is true
Returns:
Type
Sound

getAudioContext() → {AudioContext}

Returns a singleton AudioContext if one can be created. An audio context may not be available due to limited resources or browser compatibility in which case null will be returned

Returns:

A singleton AudioContext or null if one is not available

Type
AudioContext

(async) play(src, optionsopt) → {Promise.<Sound>}

Play a single Sound by providing its source.

Parameters:
Name Type Attributes Description
src string

The file path to the audio source being played
options object <optional>

Additional options passed to Sound#play
Returns:

The created Sound which is now playing

Type
Promise.<Sound>

preload(src) → {Promise.<Sound>}

Request that other connected clients begin preloading a certain sound path.

Parameters:
Name Type Description
src string

The source file path requested for preload
Returns:

A Promise which resolves once the preload is complete

Type
Promise.<Sound>

startLevelReports(id, stream, callback, interval, smoothing) → {boolean}

Registers a stream for periodic reports of audio levels. Once added, the callback will be called with the maximum decibel level of the audio tracks in that stream since the last time the event was fired. The interval needs to be a multiple of AudioHelper.levelAnalyserNativeInterval which defaults at 50ms

Parameters:
Name Type Default Description
id string

An id to assign to this report. Can be used to stop reports
stream MediaStream

The MediaStream instance to report activity on.
callback function

The callback function to call with the decibel level. callback(dbLevel)
interval number 50

(optional) The interval at which to produce reports.
smoothing number 0.1

(optional) The smoothingTimeConstant to set on the audio analyser. Refer to AudioAnalyser API docs.
Returns:

Returns whether or not listening to the stream was successful

Type
boolean

stopLevelReports(id)

Stop sending audio level reports This stops listening to a stream and stops sending reports. If we aren't listening to any more streams, cancel the global analyser timer.

Parameters:
Name Type Description
id string

The id of the reports that passed to startLevelReports.