Tea’s audio system is built on top of the browser’s HTML5Documentation 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.
<audio> API, abstracted through an internal SimpleAudio layer and exposed entirely through macros. You cache named tracks once (typically in StoryInit), then control them anywhere in your story with <<audio>>, group them with <<createaudiogroup>>, arrange them into sequential playlists with <<createplaylist>>, and adjust master volume with <<masteraudio>>. All audio macros are no-ops in environments where the Web Audio API is unavailable, so your story degrades gracefully.
Caching Audio Tracks
Before any audio can be played it must be registered with<<cacheaudio>>. The first argument is the track ID you’ll use to reference the track later; subsequent arguments are one or more source URLs. Tea picks the first format the browser can play.
In test mode, if no specified source format is supported by the browser,
<<cacheaudio>> will return an error so you can catch format problems early.Playing, Pausing, and Stopping
<<audio>> is the primary playback control macro. Its first argument is a track ID (or group/playlist selector — see below), followed by one or more option keywords.
- Basic playback
- Volume and looping
- Loading and unloading
Navigating to a passage when audio ends
Thegoto option navigates to a named passage when the track finishes playing.
Volume Fading
Tea supports smooth volume fading with three options:fadein, fadeout, and fadeto. All fades default to a 5-second duration; use fadeoverto to specify a custom duration.
Creating Audio Groups
Groups let you control multiple tracks at once under a single ID. Define a group with<<createaudiogroup>> and list its member tracks with <<track>> child tags.
<<audio>> with the group ID to act on all member tracks simultaneously:
Creating Playlists
Playlists play tracks in sequence. Define one with<<createplaylist>> and add tracks with <<track>> child tags. The own option gives each playlist entry its own independent copy of the track’s settings.
<<playlist>>:
Master Audio Control
<<masteraudio>> applies settings to all tracks at once — useful for a global mute or volume slider.
Preloading Audio with <<waitforaudio>>
<<waitforaudio>> blocks the story’s loading screen until all currently registered tracks have loaded. Place it in StoryInit after your <<cacheaudio>> calls to guarantee audio is ready before the first passage renders.
Best Practices
Always provide multiple audio formats
Always provide multiple audio formats
Browser support for audio formats varies. Providing both
.mp3 and .ogg (or .webm) versions ensures the widest compatibility. Tea will pick the first format the current browser supports.Cache all audio in StoryInit
Cache all audio in StoryInit
<<cacheaudio>> should be called before any passage tries to play a track. StoryInit runs before the first passage renders, making it the correct place to register all tracks, groups, and playlists.Use groups and playlists to avoid repetition
Use groups and playlists to avoid repetition
Rather than calling
<<audio "track1" stop>>, <<audio "track2" stop>>, etc., on every passage transition, create a group called "music" or "ambience" and call <<audio "music" stop>> once.Respect autoplay restrictions
Respect autoplay restrictions
Browsers block audio autoplay until the user interacts with the page. Tea’s
playWhenAllowed() mechanism queues playback and fires it on the first user interaction. Avoid assuming audio is playing immediately after <<audio "id" play>> on the very first passage.