Construct a Sound by providing the source URL and other options.
The audio source path, either a relative path or a remote URL
Optionaloptions: { context?: AudioContext; forceBuffer?: boolean } = {}Additional options which configure the Sound
Optionalcontext?: AudioContextA non-default audio context within which the sound should play
OptionalforceBuffer?: booleanForce use of an AudioBufferSourceNode even if the audio duration is long
Internal_An internal reference to some object which is managing this Sound instance.
An AudioBuffer instance, if this Sound uses an AudioBufferSourceNode for playback.
The AudioNode destination which is the output target for the Sound.
A pipeline of AudioNode instances to be applied to Sound playback.
An HTMLAudioElement, if this Sound uses a MediaElementAudioSourceNode for playback.
The GainNode used to control volume for this sound.
A unique integer identifier for this sound.
The time in seconds at which playback was paused.
The audio source path. Either a relative path served by the running Foundry VTT game server or a remote URL.
The time in seconds at which playback was started.
Protected_The life-cycle state of the sound.
StaticemittedStaticMAX_The maximum duration, in seconds, for which an AudioBufferSourceNode will be used. Otherwise, a MediaElementAudioSourceNode will be used.
StaticSTATESThe sequence of container loading states.
The audio context within which this Sound is played.
The current playback time of the sound.
The total duration of the audio source in seconds.
Did the audio file fail to load.
A convenience reference to the GainNode gain audio parameter.
Does this Sound use an AudioBufferSourceNode? Otherwise, the Sound uses a streamed MediaElementAudioSourceNode.
Has the audio file been loaded either fully or for streaming.
Is the sound looping?
Is this sound currently playing?
The AudioSourceNode used to control sound playback.
The currently playing volume of the sound. Undefined until playback has started for the first time.
Add a new event listener for a certain type of event.
The type of event being registered for
The listener function called when the event occurs
Optionaloptions: { once?: boolean } = {}Options which configure the event listener
Optionalonce?: booleanShould the event only be responded to once and then removed
Update the array of effects applied to a Sound instance. Optionally a new array of effects can be assigned. If no effects are passed, the current effects are re-applied.
Optionaleffects: AudioNode[]An array of AudioNode effects to apply
Dispatch an event on this target.
The Event to dispatch
Was default behavior for the event prevented?
Fade the volume for this sound between its current level and a desired target volume.
The desired target volume level between 0 and 1
Optionaloptions: { duration?: number; from?: number; type?: string } = {}Additional options that configure the fade operation
Optionalduration?: numberThe duration of the fade effect in milliseconds
Optionalfrom?: numberA volume level to start from, the current volume by default
Optionaltype?: stringThe type of fade easing, "linear" or "exponential"
A Promise that resolves after the requested fade duration
Load the audio source and prepare it for playback, either using an AudioBuffer or a streamed HTMLAudioElement.
Optionaloptions: { autoplay?: boolean; autoplayOptions?: SoundPlaybackOptions } = {}Additional options which affect resource loading
Optionalautoplay?: booleanAutomatically begin playback of the sound once loaded
OptionalautoplayOptions?: SoundPlaybackOptionsPlayback options passed to Sound#play, if autoplay
A Promise which resolves to the Sound once it is loaded
Pause playback of the Sound. For AudioBufferSourceNode this stops playback after recording the current time. Calling Sound#play will resume playback from the pausedTime unless some other offset is passed. For a MediaElementAudioSourceNode this simply calls the HTMLAudioElement#pause method directly.
Begin playback for the Sound. This method is asynchronous because playback may not start until after an initially provided delay. The Promise resolves before the fade-in of any configured volume transition.
Optionaloptions: SoundPlaybackOptions = {}Options which configure the beginning of sound playback
A Promise which resolves once playback has started (excluding fade)
Play a one-shot Sound originating from a predefined point on the canvas. The sound plays locally for the current client only. To play a sound for all connected clients use foundry.canvas.layers.SoundsLayer#emitAtPosition. A helper which does not depend on a pre-existing Sound instance is available at foundry.canvas.layers.SoundsLayer#playAtPosition.
The canvas coordinates from which the sound originates
The radius of effect in distance units
Additional options which configure playback
A Promise which resolves to the played Sound, or null
const sound = new Sound("modules/my-module/sounds/spring-trap.ogg", {context: game.audio.environment});
await sound.load();
const origin = {x: 5200, y: 3700}; // The origin point for the sound
const radius = 30; // Audible in a 30-foot radius
await sound.playAtPosition(origin, radius);
const sound = new Sound("modules/my-module/sounds/spells-sprite.ogg", {context: game.audio.environment});
const origin = token.center; // The origin point for the sound
const radius = 60; // Audible in a 60-foot radius
await sound.playAtPosition(origin, radius, {
walls: false, // Not constrained by walls and surfaces with a lowpass muffled effect
muffledEffect: {type: "lowpass", intensity: 6},
sourceData: {
angle: 120, // Sound emitted at a limited angle
rotation: 270 // Configure the direction of sound emission
}
playbackOptions: {
loopStart: 12, // Audio sprite timing
loopEnd: 16,
fade: 300, // Fade-in 300ms
onended: () => console.log("Do something after the spell sound has played")
}
});
Remove an event listener for a certain type of event.
The type of event being removed
The listener function being removed
Schedule a function to occur at the next occurrence of a specific playbackTime for this Sound.
A function that will be called with this Sound as its single argument
The desired playback time at which the function should be called
A Promise which resolves to the returned value of the provided function once it has been evaluated.
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);
Stop playback for the Sound. This method is asynchronous because playback may not stop until after an initially provided delay. The Promise resolves after the fade-out of any configured volume transition.
Optionaloptions: SoundPlaybackOptions = {}Options which configure the stopping of sound playback
A Promise which resolves once playback is fully stopped (including fade)
Cancel one scheduled event created with Sound#schedule. You may pass either the AudioTimeout returned internally or the Promise returned by Sound#schedule.
The handle to cancel.
Cancel all events that are still scheduled for this sound.
Wait a certain scheduled duration within this sound's own AudioContext.
The duration to wait in milliseconds
A promise which resolves after the waited duration
Protected_ProtectedCreate the audio pipeline used to play this Sound. The GainNode is reused each time to link volume changes across multiple playbacks. The AudioSourceNode is re-created every time that Sound#play is called.
Protected_ProtectedCreate any AudioNode instances required for playback of this Sound.
Protected_ProtectedDisconnect the audio pipeline once playback is stopped. Walk backwards along the Sound##pipeline from the Sound#destination, disconnecting each node.
Protected_ProtectedAn inner method which handles loading so that it can be de-duplicated under a single shared Promise resolution. This method is factored out to allow for subclasses to override loading behavior.
A Promise which resolves once the sound is loaded
Protected_ProtectedPause playback of the Sound. This method is factored out so that subclass implementations of Sound can implement alternative behavior.
Protected_ProtectedBegin playback for the configured pipeline and playback options. This method is factored out so that subclass implementations of Sound can implement alternative behavior.
Protected_ProtectedStop playback of the Sound. This method is factored out so that subclass implementations of Sound can implement alternative behavior.
A container around an AudioNode which manages sound playback in Foundry Virtual Tabletop. Each Sound is either an AudioBufferSourceNode (for short sources) or a MediaElementAudioSourceNode (for long ones). This class provides an interface around both types which allows standardized control over playback.
See