A nearly dependency-free package for custom positional sounds.
Built with WEB AUDIO API


PREVIEW · Report Bug · Request Feature

It started as test project to understand scripting for gta-server more. Since I didn't find any resources that feature a real 3d sound, I've started creating my own resource.

I tried my best to make it as simple as possible for potential user of this resource.

You might experience some "crackling" but it should not be the norm. That crackling is a chromium bug that is under investigation: https://bugs.chromium.org/p/chromium/issues/detail?id=1242647 I've tested a lot and with all the background noises of the game, I've heared very little crackings that weren't that loud.

If you have bigger issue with that cracklings than I'm sorry to say that you have to wait for a bugfix.

• Positional sound
• Positional sound attached to an entity.
• Server-side created sounds are time-synced on every client
• create and use custom Filter/Effects
• Underwater effect
  • If the sound source and/or the listener are underwater the sound gets muffled

You have an idea? Submit it here.

1. Take a look into the release section and download the newest version of sounity
2. Unzip the Zip-file in your resource folder
3. Add `ensure sounity" to your server.cfg
4. Play sounds

Basic example of using this library. For a detailed list of all methods scroll down to #API

-- create a sound instance
local soundId = exports.sounity:CreateSound("URL TO MP3 nui:// supported!", json.encode({
    posX = 3,
    posY = 5,
    posZ = 8,
}));

-- start playback of that sound
exports.sounity:StartSound(soundId);

-- create a sound instance
local soundId = exports.sounity:CreateSound("URL TO MP3 nui:// supported!");

-- attach it to the player ped
local ped = GetPlayerPed(source);
local pedId = NetworkGetNetworkIdFromEntity(ped);

exports.sounity:AttachSound(soundId, pedId)

-- start playback of that sound
exports.sounity:StartSound(soundId);

The API is nearly identical on server and client.
The biggest difference is, that on client side there is no sync to other players.
For the most cases I recommend a server side usage.

All Methods are available through exports

Creates a new sound instance and returns the sound's identifier.

Starts the playback of a sound

Set a new location for a sound This does not work if an entity is attached!

Set a orientation for a sound This does not work if an entity is attached!

Stops playback of a sound

Attachs a sound to an entity

Detachs a sound from an entity

Destroys a sound

Create a filter with a unique name.

You can choose between a biquad filter or a convolver filter.

Biquad is a low-order filter. The options are identical to the official documentation

A more complex filter type is the convolver. This filter is often used to get a reverb-effect. You need a impulse-response file.

official documentation

free reverb impulse responses

• url: string
  • url to impulse response
• disableNormalization: bool
  • A boolean value controlling whether the impulse response from the buffer will be scaled by an equal-power normalization, or not. The default is 'false'.

Add a filter to a sound

Remove a filter from a sound

Add filter to listener. (Global Filter on client)

Remove filter from listener.

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Distributed under the MIT License. See LICENSE for more information.