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.
Effects and categories
Section titled “Effects and categories”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:
// @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.
Adjust one listener’s mix
Section titled “Adjust one listener’s mix”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:
// @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.
Effect tails and cleanup
Section titled “Effect tails and cleanup”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.