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.

Properties

analyzer: AnalysisData

Analyzers for each context, plus an internal ticker. Each context key holds data about its AnalyserNode, a Float32Array for FFT data, and so on.

buffers: AudioBufferCache = ...

A singleton cache used for audio buffers.

environment: AudioContext

A singleton audio context used for playback of environmental audio.

interface: AudioContext

A singleton audio context used for playback of interface sounds and effects.

locked: boolean = true

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

music: AudioContext

A singleton audio context used for playback of music.

pending: Function[] = []

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.

playing: Map<number, Sound> = ...

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

sounds: Map<string, WeakRef<Sound>> = ...

The set of singleton Sound instances which are shared across multiple uses of the same sound path.

unlock: Promise<void>

A Promise which resolves once the game audio API is unlocked and ready to use.

ANALYSIS_TIMEOUT_MS: number = 1000

A static inactivity threshold for audio analysis, in milliseconds. If no band value is requested for a channel within this duration, the analyzer is disabled to conserve resources (unless the analyzer is enabled with the keepAlive=true option)

AUDIO_CONTEXTS: readonly ContextName[] = ...

An array containing all possible audio context names.

levelAnalyserNativeInterval: number = 50

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.

THRESHOLD_CACHE_SIZE_BYTES: number = ...

The cache size threshold after which audio buffers will be expired from the cache to make more room. 1 gigabyte, by default.

Accessors

  • get context(): AudioContext

    For backwards compatibility, AudioHelper#context refers to the context used for music playback.

    Returns AudioContext

  • get globalMute(): boolean

    A global mute which suppresses all 3 audio channels.

    Returns boolean

Methods

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

    Returns Promise<void>

    The unlocked audio context

  • Log a debugging message if the audio debugging flag is enabled.

    Parameters

    • message: string

      The message to log

    Returns void

  • Disable the analyzer for a given context, disconnecting the AnalyserNode.

    Parameters

    Returns void

  • Enable the analyzer for a given context (music, environment, interface), attaching an AnalyserNode to its gain node if not already active.

    Parameters

    • contextName: ContextName
    • Optionaloptions: { keepAlive?: boolean } = {}
      • OptionalkeepAlive?: boolean

        If true, this analyzer will not auto-disable after inactivity.

    Returns void

  • 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 AudioContext

    A singleton AudioContext or null if one is not available

  • Returns a normalized band value in [0,1]. Optionally, we can subtract the actual gainNode (global) volume from the measurement.

    • Important:
      • Local gain applied to foundry.audio.Sound source can't be ignored.
      • If this method needs to activate the analyzer, the latter requires a brief warm-up. One or two frames may be needed before it produces meaningful values (instead of returning 0).

    Parameters

    • contextName: ContextName
    • bandName: BandName
    • Optionaloptions: { ignoreVolume?: boolean } = {}
      • OptionalignoreVolume?: boolean

        If true, remove the real-time channel volume from the measurement.

    Returns number

    The normalized band value in [0,1].

  • Retrieve a single "peak" analyzer value across the three main audio contexts (music, environment, interface). This takes the maximum of the three normalized [0,1] values for a given frequency band.

    Parameters

    • Optionalband: BandName = "all"

      The frequency band for which to retrieve an analyzer value.

    • Optionaloptions: { ignoreVolume?: boolean } = {}
      • OptionalignoreVolume?: boolean

        If true, remove the real-time channel volume from the measurement.

    Returns number

    A number in the [0,1] range representing the loudest band value among the three contexts.

  • Play a single Sound by providing its source.

    Parameters

    • src: string

      The file path to the audio source being played

    • Optionaloptions: { context?: AudioContext } = {}

      Additional options which configure playback

      • Optionalcontext?: AudioContext

        A specific AudioContext within which to play

    Returns Promise<Sound>

    The created Sound which is now playing

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

    Parameters

    • src: string

      The source file path requested for preload

    Returns Promise<Sound>

    A Promise which resolves once the preload is complete

  • 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

    • 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)

    • Optionalinterval: number = 50

      The interval at which to produce reports.

    • Optionalsmoothing: number = 0.1

      The smoothingTimeConstant to set on the audio analyser.

    Returns boolean

    Returns whether listening to the stream was successful

  • 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

    • id: string

      The id of the reports that passed to startLevelReports.

    Returns void

  • Open socket listeners which transact ChatMessage data

    Parameters

    • socket: Socket<DefaultEventsMap, DefaultEventsMap>

    Returns void

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

    Parameters

    • src: string

      An input file path

    Returns string

    A default sound name for the path

  • Test whether a source file has a supported audio extension type

    Parameters

    • src: string

      A requested audio source path

    Returns boolean

    Does the filename end with a valid audio extension?

  • 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

    • value: string | number

      Value between [0, 1] of the range input

    • Optionalorder: number = 1.5

      The exponent of the curve

    Returns number

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

    Parameters

    • data: {
          autoplay?: boolean;
          channel?: string;
          loop?: boolean;
          src: string;
          volume?: number;
      }

      An object configuring the audio data to play.

      • Optionalautoplay?: boolean

        Begin playback of the audio effect immediately once it is loaded. Default: false.

      • Optionalchannel?: string

        An audio channel in CONST.AUDIO_CHANNELS where the sound should play. Default: "interface".

      • Optionalloop?: boolean

        Loop the audio effect and continue playing it until it is manually stopped. Default: false.

      • src: string

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

      • Optionalvolume?: number

        The volume level at which to play the audio, between 0 and 1. Default: 1.

    • OptionalsocketOptions: boolean | { recipients: string[] }

      Options which only apply when emitting playback over websocket. As a boolean, emits (true) or does not emit (false) playback to all other clients. As an object, can configure which recipients (an array of User IDs) should receive the event (all clients by default). Default: false.

    Returns void | Sound

    A Sound instance which controls audio playback, or nothing if data.autoplay is false.

    AudioHelper.play({src: "sounds/lock.wav", volume: 0.8, loop: false}, true);
    
  • Begin loading the sound for a provided source URL adding its

    Parameters

    • src: string

      The audio source path to preload

    Returns Promise<Sound>

    The created and loaded Sound ready for playback

  • Register client-level settings for global volume controls.

    Returns void

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

    Parameters

    • volume: number

      Value between [0, 1] of the volume level

    • Optionalorder: number = 1.5

      The exponent of the curve

    Returns number

  • Converts a volume level to a human-readable percentage value.

    Parameters

    • volume: number

      Value in the interval [0, 1] of the volume level.

    • Optionaloptions: { decimalPlaces?: number; label?: boolean } = {}
      • OptionaldecimalPlaces?: number

        The number of decimal places to round the percentage to.

      • Optionallabel?: boolean

        Prefix the returned tooltip with a localized 'Volume: ' label. This should be used if the returned string is intended for assistive technologies, such as the aria-valuetext attribute.

    Returns string