Playing your first sound
Use LocalAudio in client scripts for sounds heard by that player, such as a
notification or menu music. Server scripts create Audio objects to control
playback for an audience on a shared timeline.
Add an audio file
Section titled “Add an audio file”Place notification.mp3 in an audio/ directory inside the client content root
configured by resources.pack.path. In the
example project layout, its path would be
resources/first-mod/client/audio/notification.mp3.
Use resources://audio/notification.mp3 as the source URI. The path after
resources:// starts at the client content root, so it stays the same regardless
of which script creates the sound. The file is packaged and downloaded with the
other client files. Spaces and other special characters can be percent-encoded
in the URI.
MP3, Ogg Vorbis and PCM WAV/AIFF are supported. Use mono or stereo audio at 8–48 kHz. The channel count and sample rate must stay constant during playback, including live broadcasts.
Play it on the client
Section titled “Play it on the client”This example plays the file once and releases the object after completion or failure:
// @ts-check/// <reference types="@revomp/types-client" />import * as revo from 'revo-client';
const sound = new revo.LocalAudio( 'resources://audio/notification.mp3', { volume: -6 },);
function cleanup() { revo.off('audioEnded', onEnded); revo.off('audioFailed', onFailed); sound.destroy();}
/** @param {revo.Audio} audio */function onEnded(audio) { if (audio === sound) cleanup();}
/** * @param {revo.Audio} audio * @param {string} error */function onFailed(audio, error) { if (audio !== sound) return;
revo.log('Notification audio failed:', error); cleanup();}
revo.on('audioEnded', onEnded);revo.on('audioFailed', onFailed);LocalAudio waits in Loading while GTA audio initializes, then loads the
source asynchronously and starts playback. Calling stop() or destroy()
while it waits cancels playback.
Omitting pos creates non-spatial playback, suitable for UI sounds and music.
Supplying pos creates a sound at that world position. The spatial mode is fixed
when the object is created.
volume accepts -100 to 100 dB and defaults to 0. -100 mutes the
sound, 0 preserves its level, and positive values amplify it. High gain can
cause clipping. This example uses -6 dB to reduce the level. Looping is off
by default.
Remote sources
Section titled “Remote sources”Both LocalAudio and server Audio accept an HTTP(S) URL as the source string.
These sources use recorded playback by default. For a live broadcast, pass
{ live: true } in the options. The mode is explicit and remains fixed for the
object’s lifetime.
Live sources cannot loop or seek. Resuming joins the broadcast again.
resources:// sources always use recorded playback and reject live: true.
Read audio.live to inspect the mode. The server’s audio.source returns the
source URI.
Seeking, resuming or joining a recorded HTTP source partway through can take time. The client reopens the source and decodes from the beginning to reach the requested position. Prefer a packaged resource file for long recordings that need frequent seeks or late listeners.
Read playback state
Section titled “Read playback state”Read sound.state to follow playback:
| State | Meaning |
|---|---|
Loading |
Waiting for GTA audio, opening the source or preparing its initial audio. |
Buffering |
Playback is waiting for more audio data. |
Playing |
Playback is active. |
Paused |
The shared playback timeline is paused. |
StreamedOut |
Spatial playback is outside the client’s current stream. |
Finished |
Playback reached the end, including any effect tail. |
Stopped |
Playback was stopped. |
Failed |
Playback failed. Read sound.error for details. |
Client scripts can subscribe to audio events:
| Event | Arguments | When it fires |
|---|---|---|
audioLoaded |
audio, sampleRate, channels |
The first native stream is prepared. The source may still be buffering. |
audioStateChanged |
audio, oldState, newState |
Playback changes state after creation. |
audioEnded |
audio |
Playback finishes naturally, including effect tails. |
audioFailed |
audio, error |
Loading or playback fails asynchronously. |
These events cover both local and server-created audio on that client. The
example filters by the sound object and removes its handlers during cleanup.
Queued events for destroyed audio are discarded. State arguments describe the
transition, so audio.state may have advanced by the time a handler runs.
Stopping, destruction, streaming out and loop boundaries do not emit
audioEnded. Use audioStateChanged to handle Stopped.
Invalid constructor arguments or a missing named category can throw during
creation. File-opening, decoding and deferred category lookup failures emit
audioFailed and appear through Failed and error.
Release the sound
Section titled “Release the sound”Finished, Stopped and Failed objects remain valid. Call destroy() when a
local sound is no longer needed. stop() ends playback while retaining the
object. To play the same local sound again, create another LocalAudio.
Local sounds are also destroyed when their creating resource stops. Explicit cleanup keeps completed sounds from accumulating while the resource runs.
Server-controlled playback
Section titled “Server-controlled playback”Server Audio is created stopped. Configure its audience and call play() to
start the shared timeline. The default audience is all players, and spatial
audio also follows distance and dimension limits. Each listener loads and plays
the source locally.
Loading, buffering, errors and completion are tracked per listener. The server’s
AudioPlaybackState reflects its playback commands, and remains Playing when
a recording finishes on a client. Keep the server object for later playback or
call its destroy() method when the mod no longer needs it.