Forks Stargazers Issues MIT License


Sounity

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


PREVIEW · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Important Note at the start
  3. Features
  4. Upcoming features
  5. Installation
  6. Examples
  7. API
  8. Contributing
  9. License
  10. Acknowledgements

About The Project

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.

Important Note at the start

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.

Features

Upcoming Features

You have an idea? Submit it here.

Installation

  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

Example Usages

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

Play a sound on a specific location (lua example)

-- 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 and attach it to the player (lua example)

-- 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);

API

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.

Methods

All Methods are available through exports

CreateSound(source: string [, options: json_string]):string

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

options
name(key) description possible values default value
volume Defines volume in percent positive numbers 1
outputType Choose which volume setting will be used 'sfx' \| 'music' 'sfx'
loop If true the sound will repeat until you stop it bool false
posX position on x axis float 0
posY position on y axis float 0
posZ position on z axis float 0
rotX rotation on x axis float 0
rotY rotation on y axis float 0
rotZ rotation on z axis float 0
panningModel defines the spatialisation algorithm read more here 'equalpower' \| 'HRTF' 'HRTF'
distanceModel defines the algorithm reducing the volume on distance read more here 'linear' \| 'inverse' \| 'exponential' 'inverse'
maxDistance this value is only used by the linear distanceModel read more here positive numbers 500
refDistance this value is used by all distance models read more here positive numbers 3
rolloffFactor this value is used by all distance models read more here on linear: 0-1, others: 0-INFINITY 1
coneInnerAngle inner angle of sound without sound reduction here float (degree) 360
coneOuterAngle outer angle with a volume set to a defined constant here float (degree) 0
coneOuterGain volume in outer angle (0 means no sound at all) here 0-1 0

StartSound(identifier: string): void

Starts the playback of a sound

MoveSound(identifier: string, x: float, y: float, z: float): void

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

RotateSound(identifier: string, x: float, y: float, z: float): void

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

StopSound(identifier: string): void

Stops playback of a sound

AttachSound(identifier: string, entity_networkid: int): void

Attachs a sound to an entity

DetachSound(identifier: string)

Detachs a sound from an entity

DisposeSound(identifier: string)

Destroys a sound

[CLIENT ONLY] CreateFilter(filterName: string, filterType: 'biquad' | 'convolver', options: json_string)

Create a filter with a unique name.

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

filterType: ‘biquad’

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

filterType: ‘convolver’

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

options

AddSoundFilter(identifier: string, filterName: string)

Add a filter to a sound

RemoveSoundFilter(identifier: string, filterName: string)

Remove a filter from a sound

[SERVER] AddListenerFilter(playerId: int, filterName: string)

[CLIENT] AddListenerFilter(filterName: string)

Add filter to listener. (Global Filter on client)

[SERVER] AddListenerFilter(playerId: int, filterName: string)

[CLIENT] RemoveListenerFilter(filterName: string)

Remove filter from listener.

Contributing

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

License

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