SimpleAudio API — Tea Story Format Audio Systems

The SimpleAudio object is Tea’s core audio subsystem and the backend that powers all audio macros. It manages a registry of named tracks, groups, and playlists, and exposes a master volume and mute layer that sits above individual track volumes. All audio in Tea flows through this object.

The audio subsystem is built on the HTML Media Elements APIs and inherits several platform limitations. True gapless transitions between tracks are not supported. On mobile browsers, hardware controls the device volume, so software volume calls have no effect (though muting still works). Most browsers also require a user gesture before audio can play — see the guidance on playWhenAllowed() in the AudioTrack reference.

General methods

These methods operate on all currently registered tracks at once.

`SimpleAudio.load()`

Pauses playback of all currently registered tracks and, if they are not already loading, drops any existing buffered data and restarts loading from source.

This should not be called lightly when audio sources are hosted on a network — it forces every player to begin downloading all registered audio simultaneously.

SimpleAudio.load();

`SimpleAudio.loadWithScreen()`

Displays the loading screen until all currently registered audio tracks have either loaded to a playable state or aborted loading due to errors. The loading process is identical to SimpleAudio.load().

Like SimpleAudio.load(), this forces all network-hosted audio to begin downloading and should be used deliberately.

SimpleAudio.loadWithScreen();

`SimpleAudio.mute([state])` → `boolean` | `undefined`

Gets or sets the master volume mute state (default: false). Called without an argument it returns the current mute state; called with a boolean it sets the state and returns undefined.

state

boolean

The mute state to apply. true mutes all audio; false unmutes.

return (get)

boolean

The current master mute state when called without an argument.

// Get the current master mute state.
var isMuted = SimpleAudio.mute();

// Mute the master volume.
SimpleAudio.mute(true);

// Unmute the master volume.
SimpleAudio.mute(false);

`SimpleAudio.muteOnHidden([state])` → `boolean` | `undefined`

Gets or sets the mute-on-hidden state (default: false). When enabled, the master volume is automatically muted whenever the story’s browser tab loses visibility (switched away or minimized), and unmuted when it regains visibility.

state

boolean

true to enable automatic muting on tab hide; false to disable.

return (get)

boolean

The current mute-on-hidden state when called without an argument.

// Get the current mute-on-hidden state.
var isMuteOnHidden = SimpleAudio.muteOnHidden();

// Enable automatic muting when the tab is hidden.
SimpleAudio.muteOnHidden(true);

// Disable automatic muting when the tab is hidden.
SimpleAudio.muteOnHidden(false);

`SimpleAudio.select(selector)` → `AudioRunner`

Returns an AudioRunner instance for all tracks matching the given selector string. The AudioRunner exposes the same method surface as AudioTrack and applies every operation to all matched tracks simultaneously.

selector

string

required

A space-separated list of track IDs and/or group IDs. Predefined group IDs are :all, :looped, :muted, :paused, :playing, and :stopped. The :not() modifier syntax (groupId:not(selector)) excludes a subset of tracks from a group selection.

return

AudioRunner

An AudioRunner instance targeting all matched tracks.

Basic
Playback control

// Return the AudioRunner for tracks matching ":ui".
SimpleAudio.select(":ui");

// Play a specific track at full volume.
SimpleAudio.select("swamped").volume(1).play();

// Start all paused tracks.
SimpleAudio.select(":paused").play();

// Stop all playing tracks except those in the ":ui" group.
SimpleAudio.select(":playing:not(:ui)").stop();

// Set volume of all tracks except ":ui" to 40%.
SimpleAudio.select(":all:not(:ui)").volume(0.40);

`SimpleAudio.stop()`

Stops playback of all currently registered tracks.

SimpleAudio.stop();

`SimpleAudio.unload()`

Stops playback of all currently registered tracks and forces them to drop any buffered data.

Once unloaded, a track cannot play again until it is explicitly reloaded.

SimpleAudio.unload();

`SimpleAudio.volume([level])` → `number` | `undefined`

Gets or sets the master volume level (default: 1).

level

number

The master volume to set. Valid range is 0.0 (silent) to 1.0 (loudest).

return (get)

number

The current master volume level when called without an argument.

// Get the current master volume.
var masterVol = SimpleAudio.volume();

// Set the master volume to 75%.
SimpleAudio.volume(0.75);

`SimpleAudio.tracks`

The tracks namespace manages individual named audio tracks that can later be referenced by ID in macros, groups, and playlists.

`SimpleAudio.tracks.add(trackId, sources…)`

Registers a new audio track under the given ID.

trackId

string

required

The ID used to reference this track everywhere else in the API.

sources

string | string[]

required

One or more audio source URLs (absolute or relative), audio passage names, or data URIs. Supplying multiple formats is recommended for cross-browser compatibility. A format specifier prefix (formatId|) can be prepended when the format cannot be auto-detected from the URL.

SimpleAudio.tracks.add("boom", "media/audio/explosion.mp3");

`SimpleAudio.tracks.clear()`

Deletes all registered audio tracks.

Tracks that are solely owned by a playlist cannot be deleted this way.

SimpleAudio.tracks.clear();

`SimpleAudio.tracks.delete(trackId)`

Deletes the audio track with the given ID.

Deleting a track does not remove it from any groups or playlists that reference it. Rebuild any affected groups or playlists after deletion.

trackId

string

required

The ID of the track to delete.

SimpleAudio.tracks.delete("bgm_space");

`SimpleAudio.tracks.get(trackId)` → `AudioTrack | null`

Returns the AudioTrack instance for the given track ID, or null if no track with that ID exists.

trackId

string

required

The ID of the track to retrieve.

return

AudioTrack | null

The matching AudioTrack instance, or null on failure.

To operate on multiple tracks at once, use SimpleAudio.select() instead.

// Retrieve and immediately chain playback.
SimpleAudio.tracks.get("swamped").volume(1).play();

`SimpleAudio.tracks.has(trackId)` → `boolean`

Returns true if a track with the given ID exists, false otherwise.

trackId

string

required

The ID of the track to check.

if (SimpleAudio.tracks.has("bgm_space")) {
  // Track exists, safe to use.
}

`SimpleAudio.groups`

Groups are named collections of track IDs. They let you apply operations to multiple tracks simultaneously and let you use the :not() selector modifier to exclude them from broader selections.

Groups are for simultaneous operations. If you need tracks to play one after another, use a playlist instead.

`SimpleAudio.groups.add(groupId, trackIds…)`

Creates a new audio group containing the specified track IDs.

groupId

string

required

The group ID, which must begin with a colon (e.g., :ui). The IDs :all, :looped, :muted, :paused, :playing, :stopped, and :not are reserved and cannot be used.

trackIds

string | string[]

required

The IDs of the tracks to include in the group.

// Create a ":ui" group from three sound-effect tracks.
SimpleAudio.groups.add(":ui", "ui_beep", "ui_boop", "ui_swish");

`SimpleAudio.groups.clear()`

Deletes all audio groups. Does not affect the tracks themselves.

SimpleAudio.groups.clear();

`SimpleAudio.groups.delete(groupId)`

Deletes the audio group with the given ID. Does not affect the tracks contained in the group.

groupId

string

required

The ID of the group to delete.

SimpleAudio.groups.delete(":ui");

`SimpleAudio.groups.get(groupId)` → `string[] | null`

Returns the array of track IDs in the given group, or null if the group does not exist.

groupId

string

required

The ID of the group.

return

string[] | null

An array of track ID strings belonging to the group, or null on failure.

SimpleAudio.groups.get(":ui"); // → ["ui_beep", "ui_boop", "ui_swish"]

`SimpleAudio.groups.has(groupId)` → `boolean`

Returns true if a group with the given ID exists.

groupId

string

required

The ID of the group to check.

if (SimpleAudio.groups.has(":ui")) {
  // Group exists.
}

`SimpleAudio.lists`

Playlists play a sequence of tracks one after another. They support shuffle, loop, skip, and all the same volume/mute controls as individual tracks.

If you only need to apply simultaneous actions to multiple tracks without sequencing, use a group instead.

`SimpleAudio.lists.add(listId, sources…)`

Creates a new playlist. Sources may be bare track IDs or descriptor objects that specify per-track volume and ownership.

listId

string

required

The ID used to reference this playlist.

sources

string | Object | Array<string | Object>

required

Track IDs or descriptor objects. Two descriptor forms are supported:Existing track form { id, [own], [volume] }

id — ID of an existing registered track.
own (optional) — When true, the playlist creates an independent copy of the track. Owned copies cannot be selected via SimpleAudio.tracks.get() or SimpleAudio.select().
volume (optional) — Base volume for this track within the playlist (0–1). Defaults to the track’s current volume.

New track form { sources, [volume] }

sources — Array of source URLs/passages for an inline track.
volume (optional) — Base volume (0–1). Defaults to 1.

SimpleAudio.lists.add("bgm_lacuna",
  "swamped", "heavens_a_lie", "closer", "to_the_edge"
);

`SimpleAudio.lists.clear()`

Deletes all playlists.

SimpleAudio.lists.clear();

`SimpleAudio.lists.delete(listId)`

Deletes the playlist with the given ID.

listId

string

required

The ID of the playlist to delete.

SimpleAudio.lists.delete("bgm_lacuna");

`SimpleAudio.lists.get(listId)` → `AudioList | null`

Returns the AudioList instance for the given list ID, or null if no such playlist exists.

listId

string

required

The ID of the playlist.

return

AudioList | null

The matching AudioList instance, or null on failure.

// Start looping a playlist at full volume.
SimpleAudio.lists.get("bgm_lacuna").volume(1).loop(true).play();

`SimpleAudio.lists.has(listId)` → `boolean`

Returns true if a playlist with the given ID exists.

listId

string

required

The ID of the playlist to check.

if (SimpleAudio.lists.has("bgm_lacuna")) {
  // Playlist exists.
}

Core APIs

UI & Interaction

Saves & Settings

Macros & Scripting

Audio

Functions & Methods

SimpleAudio API — Tea Story Format Audio Systems

General methods

`SimpleAudio.load()`

`SimpleAudio.loadWithScreen()`

`SimpleAudio.mute([state])` → `boolean` | `undefined`

`SimpleAudio.muteOnHidden([state])` → `boolean` | `undefined`

`SimpleAudio.select(selector)` → `AudioRunner`

`SimpleAudio.stop()`

`SimpleAudio.unload()`

`SimpleAudio.volume([level])` → `number` | `undefined`

`SimpleAudio.tracks`

`SimpleAudio.tracks.add(trackId, sources…)`

`SimpleAudio.tracks.clear()`

`SimpleAudio.tracks.delete(trackId)`

`SimpleAudio.tracks.get(trackId)` → `AudioTrack | null`

`SimpleAudio.tracks.has(trackId)` → `boolean`

`SimpleAudio.groups`

`SimpleAudio.groups.add(groupId, trackIds…)`

`SimpleAudio.groups.clear()`

`SimpleAudio.groups.delete(groupId)`

`SimpleAudio.groups.get(groupId)` → `string[] | null`

`SimpleAudio.groups.has(groupId)` → `boolean`

`SimpleAudio.lists`

`SimpleAudio.lists.add(listId, sources…)`

`SimpleAudio.lists.clear()`

`SimpleAudio.lists.delete(listId)`

`SimpleAudio.lists.get(listId)` → `AudioList | null`

`SimpleAudio.lists.has(listId)` → `boolean`

Build docs developers (and LLMs) love

Core APIs

UI & Interaction

Saves & Settings

Macros & Scripting

Audio

Functions & Methods

Documentation Index

​General methods

​SimpleAudio.load()

​SimpleAudio.loadWithScreen()

​SimpleAudio.mute([state]) → boolean | undefined

​SimpleAudio.muteOnHidden([state]) → boolean | undefined

​SimpleAudio.select(selector) → AudioRunner

​SimpleAudio.stop()

​SimpleAudio.unload()

​SimpleAudio.volume([level]) → number | undefined

​SimpleAudio.tracks

​SimpleAudio.tracks.add(trackId, sources…)

​SimpleAudio.tracks.clear()

​SimpleAudio.tracks.delete(trackId)

​SimpleAudio.tracks.get(trackId) → AudioTrack | null

​SimpleAudio.tracks.has(trackId) → boolean

​SimpleAudio.groups

​SimpleAudio.groups.add(groupId, trackIds…)

​SimpleAudio.groups.clear()

​SimpleAudio.groups.delete(groupId)

​SimpleAudio.groups.get(groupId) → string[] | null

​SimpleAudio.groups.has(groupId) → boolean

​SimpleAudio.lists

​SimpleAudio.lists.add(listId, sources…)

​SimpleAudio.lists.clear()

​SimpleAudio.lists.delete(listId)

​SimpleAudio.lists.get(listId) → AudioList | null

​SimpleAudio.lists.has(listId) → boolean

Build docs developers (and LLMs) love

General methods

`SimpleAudio.load()`

`SimpleAudio.loadWithScreen()`

`SimpleAudio.mute([state])` → `boolean` | `undefined`

`SimpleAudio.muteOnHidden([state])` → `boolean` | `undefined`

`SimpleAudio.select(selector)` → `AudioRunner`

`SimpleAudio.stop()`

`SimpleAudio.unload()`

`SimpleAudio.volume([level])` → `number` | `undefined`

`SimpleAudio.tracks`

`SimpleAudio.tracks.add(trackId, sources…)`

`SimpleAudio.tracks.clear()`

`SimpleAudio.tracks.delete(trackId)`

`SimpleAudio.tracks.get(trackId)` → `AudioTrack | null`

`SimpleAudio.tracks.has(trackId)` → `boolean`

`SimpleAudio.groups`

`SimpleAudio.groups.add(groupId, trackIds…)`

`SimpleAudio.groups.clear()`

`SimpleAudio.groups.delete(groupId)`

`SimpleAudio.groups.get(groupId)` → `string[] | null`

`SimpleAudio.groups.has(groupId)` → `boolean`

`SimpleAudio.lists`

`SimpleAudio.lists.add(listId, sources…)`

`SimpleAudio.lists.clear()`

`SimpleAudio.lists.delete(listId)`

`SimpleAudio.lists.get(listId)` → `AudioList | null`

`SimpleAudio.lists.has(listId)` → `boolean`