AudioHelper

AudioHelper

A helper class to provide common functionality for working with HTML5 audio and Howler instances A singleton instance of this class is available as game.audio

Audio playback in Foundry VTT is managed by Howler.js (https://howlerjs.com/). Several methods and attributes in this API return :class:Howl instances. See the Howler documentation for details and example usage of the Howl API.

Constructor

new AudioHelper()

Source:

Members

(static) levelAnalyserNativeInterval :Number

Source:

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. Defaults to 50ms.

Type:

_audioContext :AudioContext

Source:

Audio Context singleton used for analysing audio levels of each stream Only created if necessary to listen to audio streams.

Type:
  • AudioContext

locked :Boolean

Source:

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

Type:
  • Boolean

pending :Array

Source:

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

Type:

sounds :Object

Source:

The set of Howl instances which have been created for different audio paths

Type:
  • Object

Methods

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

Source:

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 Based on https://www.dr-lex.be/info-stuff/volumecontrols.html We're using x^3 by default instead of x^4 otherwise the audio becomes nearly silent around the 40% mark.

Parameters:
Name Type Default Description
value number | string

Value between [0, 1] of the range input
order number 2

[optional] the exponent of the curve (default: 2)
Returns:
Type
number

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

Source:

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, autoplay: true, 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 Howl instance which controls audio playback.

Type
Howl

(static) preload(data)

Source:

Create a Howl object and load it to be ready for later playback

Parameters:
Name Type Description
data Object

The audio data to preload

(static) registerSettings()

Source:

Register client-level settings for global volume overrides

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

Source:

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

Parameters:
Name Type Default Description
volume number

Value between [0, 1] of the volume level
order number 2

[optional] the exponent of the curve (default: 2)
Returns:
Type
number

_onFirstGesture(event)

Source:

Handle the first observed user gesture

Parameters:
Name Type Description
event Event

The mouse-move event which enables playback

awaitFirstGesture()

Source:

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

create(src, preload, autoplay) → {Howl}

Source:

Create a Howl instance

Parameters:
Name Type Description
src
preload
autoplay
Returns:
Type
Howl

getAudioContext() → {AudioContext}

Source:

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

play(src, id)

Source:

Play a single audio effect by it's source path and Howl ID

Parameters:
Name Type Description
src String
id Number

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

Source:

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 media stream to report on its audio tracks
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)

Source:

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.