Skip to content

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.

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.

This example plays the file once and releases the object after completion or failure:

Client
// @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.

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

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

Audio (client), LocalAudio (client).