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 (https://howlerjs.com/). Several methods and attributes in this API return Howl() instances. See the Howler documentation for details and example usage of the Howl API.

Playlists.Collection.insert(entity)

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

Arguments:
  • entity (Entity) – The entity instance to add to the collection
Playlists.Collection.remove(id)

Remove an Entity from the Collection by its ID.

Arguments:
  • id (String) – The entity ID which should be removed
Playlists.Collection.get(id)

Get an element from the collection by ID

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

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

Playlists.Collection.index(id)

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

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

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

Playlists.Collection.render()

Re-render any currently visible applications associated with this Collection

Playlists.play(data, push)

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

Arguments:
  • 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?
Returns:

Howl – A Howl instance which controls audio playback.

Examples:

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

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.

Playlist._onUpdate(data)

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

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

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.

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

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

Arguments:
  • trackId (Number) – ID of the track to remove
  • push (Boolean) – Push the track deletion to other clients?
Playlist.howls

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.

Playlist.mode

type: Number

The playback mode for the Playlist instance

Playlist.playAll()

Begin simultaneous playback for all sounds in the Playlist

Playlist.playSound(sound)

Play (or stop) a single sound from the Playlist

Arguments:
  • sound (Object) – The sound object to begin playback
Playlist.shuffleOrder

type: Array

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

Playlist.sounds

type: Array

An Array of the sound data contained within this Playlist entity

Playlist.stopAll()

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

Playlist.updateSound(data, push=false)

Update a single sound track within the Playlist

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