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

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


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?