The Audio Playlist Entity

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 (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.playing

type: Array

Return the subset of Playlist entities which are currently playing


The Playlist Entity

class foundry.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.

foundry.Playlist.Entity.create(data, options)

Create a new entity using provided input data The data for entity creation is typically provided from the server through the ‘create<Entity>’ socket Alternatively, the creation event may originate locally and the new entity can be pushed back to the server

Arguments:
  • data (Object) – The data with which to create the entity
  • options (Object) – Additional options which customize the creation workflow
  • options.temporary (Boolean) – Create a temporary entity which is not saved to the world database. Default is false.
  • options.displaySheet (Boolean) – Show the configuration sheet for the created entity once it is created. Default is true.
Returns:

Promise – A Promise which resolves to contain the created Entity

foundry.Playlist.Entity.update(data)

Update the current entity using new data This new data is typically provided from the server through the ‘update<Entity>’ socket Alternatively, the update may originate locally, in which case it can be pushed back to the server

Arguments:
  • data (Object) – The data with which to update the entity
Returns:

Promise – A Promise which resolves to the updated Entity

foundry.Playlist.Entity.delete()

Delete the entity, removing it from its collection and deleting its data record

Returns:Promise – A Promise which resolves to the ID of the deleted Entity once handled by the server
foundry.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
foundry.Playlist.collection

type: Playlists

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

foundry.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?
foundry.Playlist.cycleMode()

Cycle the playlist mode

Returns:Promise.<Playlist> – A promise which resolves to the updated Playlist instance
foundry.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?
foundry.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.

foundry.Playlist.mode

type: Number

The playback mode for the Playlist instance

foundry.Playlist.playAll()

Begin simultaneous playback for all sounds in the Playlist

foundry.Playlist.playSound(sound)

Play (or stop) a single sound from the Playlist

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

type: Array

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

foundry.Playlist.sounds

type: Array

An Array of the sound data contained within this Playlist entity

foundry.Playlist.stopAll()

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

foundry.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?

Playlist Configuration Sheet

class PlaylistConfig()

Playlist Configuration Sheet

PlaylistConfig.getData()

Provide data to the form

Returns:Object – The data provided to the template when rendering the form
PlaylistConfig.title

Dynamic application window title


Playlist Track Configuration Sheet

class PlaylistSoundConfig(playlist, sound, options)

Playlist Sound Configuration Sheet

PlaylistSoundConfig.getData()

Provide data to the form

Returns:Object – The data provided to the template when rendering the form
PlaylistSoundConfig.title

Dynamic application window title