Skip to content

Audio effects and mixing

Use LocalAudio.effects to process one local sound, AudioCategory to group playback settings, and Audio.setMix() to adjust what one listener hears.

Place machinery.ogg under audio/ in the client content root. This example adds reverb to a looping sound and assigns it to a custom category:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
const ambienceMix = new revo.AudioCategory('ProjectAmbience');
ambienceMix.volume = -6;
const ambience = new revo.LocalAudio('resources://audio/machinery.ogg', {
pos: { x: -1220, y: -1765, z: 3.9 },
category: ambienceMix.name,
loop: true,
effects: [
{ type: 'reverb', mixDb: -12, timeMs: 1200 },
],
});

ambience.effects affects this sound. ambienceMix.volume and ambienceMix.muted affect every sound assigned to ProjectAmbience on this client. Put a chain in ambienceMix.effects to apply it to all of them.

Processing runs through the sound’s effects, its category and parent categories, then its listener mix and GTA output. Effects process in array order. Replace effects with a new array to update a chain, or assign [] to clear it. See Voice categories and effects for the shared effect types, category hierarchy and ownership rules.

For server-created audio, create the category on each listening client and pass its name in the server Audio constructor’s category option. Playback waits for a missing category. Create custom categories before constructing a LocalAudio that uses them. Custom categories can be created while GTA audio is still initializing.

The category is fixed for the sound’s lifetime. With no category specified, playback uses GTA’s SFX_SLIDER. Selecting MUSIC_SLIDER routes it through the game’s music volume control. To use a GTA category as the parent of a custom category, create the child after AudioCategory.available becomes true. The category.native controls also require GTA audio to be ready.

setMix(settings, fadeSeconds) works on both LocalAudio and server-created audio. Its changes apply on the calling client and preserve the playback position. The following example fades between the default volume/filter mix and a muffled sound:

Client
// @ts-check
/// <reference types="@revomp/types-client" />
import * as revo from 'revo-client';
/**
* @param {revo.Audio} sound
* @param {boolean} muffled
*/
function setMuffled(sound, muffled) {
sound.setMix({
volumeDb: muffled ? -12 : 0,
lowPassCutoffHz: muffled ? 1200 : 20000,
}, 0.4);
}

Call setMuffled(sound, true) when your interaction or area logic should muffle the sound, and pass false to restore the example’s defaults.

Setting Values
volumeDb Additional gain from -100 to 100 dB. Defaults to 0. -100 mutes.
lowPassCutoffHz 100 to 20000 Hz. Lower values reduce high frequencies. 20000 bypasses the filter.
spatialBlend 0 for non-positional playback with the source’s original channels, 1 for positional mono, or a value between them.

Omitted settings keep their previous values. The fade lasts 0 to 60 seconds and defaults to 0. Changes affect newly processed audio, so already queued audio can introduce a short delay. Read mix for a snapshot of the requested settings, including the target values during a fade.

Spatial sounds start with spatialBlend: 1. You can blend towards 0, for example to hear an attached car radio without distance attenuation while inside the vehicle. Its streaming radius and dimension still apply. Sounds created without pos always use spatialBlend: 0.

The mix survives playback commands and temporary streaming changes while the same client audio object exists. Reapply it if the object is removed and later created again, such as when server audio leaves and re-enters the client’s stream. On resource shutdown, saved mix settings are restored if the current settings still match that resource’s last change.

For a sound that ends naturally, effectTailSeconds allows its echo or reverb to continue after the source ends. Set it in the LocalAudio options from 0 to 10 seconds. The default is 2. Category effects also contribute to the tail. audioEnded fires after the tail finishes.

Calling stop() or destroy() ends playback immediately, including its tail. For the looping example, call ambience.destroy() when the sound is no longer needed. Categories remain separate objects. Their destroy() method returns false while playback or child categories still retain them.

AudioCategory (client).