Audio Playlists

Audio in Foundry VTT provides a key layer to improve immersion and enrich gameplay. The core software provides APIs for audio effects which are triggered programmatically as well as audio Playlists which are user-defined Entities. Overall audio management is controlled by the Playlists() collection while the Playlist() class implements the individual playlist entity.

The Audio Collection

class Playlists(data, apps)

The Playlists collection serves a dual purpose in Foundry VTT. Firstly, it is the collection of pre-defined Playlist entities. Secondly, it provides convenience APIs for programmatically triggering playback of audio effects.

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


Add a new Entity to the Collection, asserting that they are of the correct type

  • entity (Entity) – The entity instance to add to the collection

Remove an Entity from the Collection by its ID.

  • id (String) – The entity ID which should be removed

Get an element from the collection by ID

  • id (String) – The entity ID to retrieve from the collection

Entity – The retrieved Entity, if the ID was found, otherwise null;


Retrieve the index of an entity within the collection by its ID

  • id (String) – The entity ID to retrieve from the collection

Number – The index of the Entity within the collection, if found, otherwise -1;


Re-render any currently visible applications associated with this Collection, push)

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

  • data (Object) – An object configuring the audio data to play
  • data.src (String) – The audio source file path, either a public URL or a local path relative to the public directory
  • data.volume (Number) – The volume level at which to play the audio, between 0 and 1.
  • data.autoplay (Boolean) – Begin playback of the audio effect immediately once it is loaded.
  • data.loop (Boolean) – Loop the audio effect and continue playing it until it is manually stopped.
  • push (Boolean) – Push the audio sound effect to other connected clients?

Howl – A Howl instance which controls audio playback.


// Play the sound of a locked door for all players{src: "sounds/lock.wav", volume: 0.8, autoplay: true, loop: false}, true);

type: Array

Return the subset of Playlist entities which are currently playing

The Playlist Entity

class Playlist(data, apps)

The Playlist class provides an API for managing the playlist entities which are configured and saved to the World database.

Each playlist has a unique _id and may contain one or more sounds. Each sound (or track) may be played individually or simultaneously with other tracks in the playlist.


Additional updating steps for the Playlist entity when new data is saved which trigger some related updates.

Modify the playing status of each track Modify the status of the overall playlist

  • data (Object) – The new data object which was used to update the Playlist

type: Playlists

Return a reference to the Playlists collection to which each Playlist belongs

Playlist.createSound(data, push=false)

Create a new sound track within this Playlist. The creation request is submitted to the server where the item is assigned an ID The return item (with itemID) is then added to the Playlist.

  • data (Object) – Data for the new audio track
  • push (Boolean) – Push the track creation request to other clients?

Cycle the playlist mode

Returns:Promise.<Playlist> – A promise which resolves to the updated Playlist instance
Playlist.deleteSound(trackId, push=false)

Delete a sound track from the Playlist The deletion request is submitted to the server where it is removed by ID

  • trackId (Number) – ID of the track to remove
  • push (Boolean) – Push the track deletion to other clients?

type: Object

Each sound which is played within the Playlist has a created Howl instance. The keys of this object are the sound IDs and the values are the Howl instances.


type: Number

The playback mode for the Playlist instance


Begin simultaneous playback for all sounds in the Playlist


Play (or stop) a single sound from the Playlist

  • sound (Object) – The sound object to begin playback

type: Array

Playlists may have a shuffle order which gets chosen when the playback is started on shuffle mode


type: Array

An Array of the sound data contained within this Playlist entity


End playback for any/all currently playing sounds within the Playlist

Playlist.updateSound(data, push=false)

Update a single sound track within the Playlist

  • data (Object) – New sound data
  • push (Boolean) – Push the updated track data to other clients?