Skip to content

Spatial and attached audio

Spatial audio has a position in the world. Its direction and attenuation follow GTA’s audio engine. Supply pos when creating Audio or LocalAudio to enable it. You can then move the sound through pos or attach it to an entity.

Place music.ogg under audio/ in the client content root, as described in Playing your first sound. This server example creates a vehicle with a looping sound that follows it:

Server
// @ts-check
/// <reference types="@revomp/types-server" />
import * as revo from 'revo-server';
const vehicle = new revo.Vehicle(
'sultan',
{ x: -1220, y: -1765, z: 3.9 },
Math.PI / 2,
);
const sound = new revo.Audio('resources://audio/music.ogg', {
pos: vehicle.pos,
streamDistance: 60,
volume: -12,
loop: true,
});
sound.attachTo(vehicle);
sound.play();

attachTo() follows the entity’s position automatically and preserves the playback timeline. It returns whether the attachment succeeded. The sound must have been created with pos, even when it will be attached immediately.

For a stationary emitter, set pos to its world coordinates and call play() without attaching it. For playback heard only on the current client, create a LocalAudio with the same spatial options. Local audio starts automatically.

streamDistance sets the streaming radius in metres. It must be positive. When omitted, server audio uses stream_distance from the server config. In the example, the explicit value overrides that default, so listeners can stream the sound within 60 metres of the vehicle. Attached audio also requires the entity to be streamed in. A small margin around the boundary prevents repeated streaming changes when a player moves near the edge.

GTA applies distance attenuation while the sound is streamed in. Increasing streamDistance alone does not make it louder or change its attenuation curve. Choose a radius that covers the area where the sound should be heard, and check the level at several distances. Category volume and the player’s audio settings also affect the result.

Stereo sources are mixed down to mono for the world emitter, so a mono file is sufficient for a sound heard from a single point.

Unattached spatial audio starts in dimension 0. Set sound.dimension to place it in another dimension, or use globalDimension to make it visible across dimensions. The listener must still meet the distance and audience rules.

Attached audio inherits the entity’s dimension and follows subsequent changes. Detach it before assigning a separate dimension. See Dimensions for the shared visibility rules.

Playback depends on how the sound was created:

Source When the listener returns
Server Audio, recorded source Joins the current point on the shared timeline, including loop progress.
LocalAudio, resource file Resumes from its saved position.
LocalAudio, recorded HTTP(S) URL Reopens the source from the beginning.
Live HTTP(S) source Reconnects to the current broadcast.

An attached sound waits while its entity is unavailable on the client. Streaming back in can require loading or buffering before the sound becomes audible.

sound.detach() leaves the sound playing at the last attachment position and retains its dimension. Assigning pos also detaches it. Call detach() before destroying an entity if the sound should continue at that location.

Destroying the attached entity stops its audio. The audio object remains valid, so call sound.destroy() when it is no longer needed. Server audio can also be repositioned or attached to another entity and started again with play().