Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pompom454/tea/llms.txt

Use this file to discover all available pages before exploring further.

An AudioList represents a playlist — a sequenced collection of audio tracks that plays one after another. You obtain an instance via SimpleAudio.lists.get(listId) after registering the playlist with SimpleAudio.lists.add(). Playlists support shuffle mode, looping, per-list volume and mute, and the same fade methods available on individual tracks.
Playlists are for sequential playback. If you want to apply simultaneous operations to multiple tracks without sequencing them, use a group instead.

Playback methods

<AudioList>.play()Promise

Begins playback of the playlist from the current track. Returns a Promise that resolves when playback starts, or rejects with an error.
// Basic usage.
aList.play();

// With a Promise.
aList.play()
  .then(() => { console.log('Playlist is playing.'); })
  .catch((problem) => { console.warn('Playback error:', problem); });

<AudioList>.playWhenAllowed()

Begins playback immediately if allowed, or queues the playlist to begin as soon as the player next interacts with the document. Use this when autoplay restrictions may block play().
aList.playWhenAllowed();

<AudioList>.pause()

Pauses playback of the playlist at the current track’s current position.
aList.pause();

<AudioList>.stop()

Stops playback of the playlist and resets it to the beginning of the current track.
aList.stop();

<AudioList>.skip()

Skips ahead to the next track in the playlist. If the playlist is at its last track, behavior depends on the loop state.
aList.skip();

<AudioList>.load()

Pauses playback and forces all tracks in the playlist to drop existing buffered data and reload from source.
Avoid calling this for network-hosted audio unless necessary — it forces the player to re-download all playlist tracks.
aList.load();

<AudioList>.unload()

Stops playback and forces all tracks in the playlist to drop their buffered data. Playback cannot resume until the tracks are reloaded.
Once unloaded, the playlist cannot play until its tracks have been loaded again.
aList.unload();

Fade methods

Fade methods operate on the currently playing track within the playlist.

<AudioList>.fade(duration, toVol [, fromVol])Promise

Starts playback and fades the current track from an optional starting volume to a destination volume over the given seconds.
When Config.audio.pauseOnFadeToZero is true (the default), tracks faded to 0 are automatically paused.
duration
number
required
Number of seconds for the fade.
toVol
number
required
Destination volume (0–1).
fromVol
number
Starting volume (0–1). Defaults to the current track’s current volume.
// Fade from 0 to 1 over 6 seconds.
aList.fade(6, 1, 0);

<AudioList>.fadeIn(duration [, fromVol])Promise

Starts playback and fades the current track up to 1 (loudest) over the given number of seconds.
duration
number
required
Number of seconds for the fade.
fromVol
number
Starting volume. Defaults to the current track’s current volume.
// Fade in from silence over 5 seconds.
aList.fadeIn(5, 0);

<AudioList>.fadeOut(duration [, fromVol])Promise

Starts playback and fades the current track down to 0 (silent) over the given number of seconds.
duration
number
required
Number of seconds for the fade.
fromVol
number
Starting volume. Defaults to the current track’s current volume.
// Fade out from full volume over 8 seconds.
aList.fadeOut(8, 1);

<AudioList>.fadeStop()

Interrupts an in-progress fade on the current track. The volume is left at whatever level it had reached.
aList.fadeStop();

State methods

Methods that set state return the AudioList instance for chaining.

<AudioList>.volume([level])number | AudioList

Gets or sets the playlist’s volume level (default: 1).
level
number
Volume level to set (0–1).
var vol = aList.volume();    // get
aList.volume(0.75);           // set to 75%

<AudioList>.mute([state])boolean | AudioList

Gets or sets the playlist’s mute state (default: false).
state
boolean
true to mute, false to unmute.
var muted = aList.mute();   // get
aList.mute(true);             // mute
aList.mute(false);            // unmute

<AudioList>.loop([state])boolean | AudioList

Gets or sets whether the playlist restarts after reaching the end of its last track (default: false).
state
boolean
true to loop, false to play once.
var looping = aList.loop();  // get
aList.loop(true);              // enable looping
aList.loop(false);             // disable looping

<AudioList>.shuffle([state])boolean | AudioList

Gets or sets the playlist’s shuffle state (default: false). When enabled, tracks are played in a randomly shuffled order.
state
boolean
true to enable shuffled playback, false for sequential.
var shuffled = aList.shuffle();  // get
aList.shuffle(true);              // enable shuffle
aList.shuffle(false);             // disable shuffle

<AudioList>.time()number

Returns the playlist’s current playback position within the active track in seconds, or NaN if no metadata exists.
Unlike AudioTrack.time(), the playlist version is read-only — it does not accept a value to seek to.
var pos = aList.time();

<AudioList>.duration()number

Returns the playlist’s total playtime in seconds across all tracks. Returns Infinity if any track is a stream, or NaN if metadata is unavailable.
var total = aList.duration();

<AudioList>.remaining()number

Returns how many seconds remain in the playlist. Returns Infinity if any track is a stream, or NaN if metadata is unavailable.
var secondsLeft = aList.remaining();

State query methods

All state-query methods return a boolean and take no arguments.
MethodReturns true when…
isPlaying()The playlist is actively playing.
isPaused()Playback has been paused.
isStopped()Playback has been stopped.
isEnded()The playlist played all tracks to the end (without looping).
isFading()A fade is in progress on the current track.
if (aList.isPlaying()) {
  aList.pause();
}

if (aList.isEnded() && !aList.loop()) {
  // Playlist finished, do something.
}

Event methods

These are thin wrappers over jQuery’s event methods applied to the underlying audio elements. Always use a custom namespace to avoid conflicts with Tea’s internal event handling.

<AudioList>.on(events, handler)AudioList

Attaches a persistent event handler.
aList.on('ended.myGame', () => {
  // A track in the playlist ended.
});

<AudioList>.one(events, handler)AudioList

Attaches a single-use event handler that fires once and then removes itself.
aList.one(':faded.myGame', () => {
  // A fade completed on a track in this playlist.
});

<AudioList>.off(events [, handler])AudioList

Removes event handlers from the playlist.
aList.off('ended.myGame');

Audio events

EventFires when…
:fadedA fade on the current track completes normally.
:fadingA fade on the current track starts.
:stoppedPlayback is stopped via .stop().
See the Events reference for full details.

Build docs developers (and LLMs) love