Examples

Some of good examples

In general, examples are given on the client side. Because playing on the server side works in the same way. Only the first parameter is must be a source id

Play sound via file

local coords = GetEntityCoords(PlayerPedId())
local soundId = exports['mx-surround']:Play(nil, '/ui/sounds/beltalarm.ogg', coords)

---

Play sound via url (Youtube, Spotify, SoundCloud)

local coords = GetEntityCoords(PlayerPedId())
local url = 'https://www.youtube.com/watch?v=RP0_8J7uxhs&ab_channel=RHINO'

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

local soundId = exports['mx-surround']:Play(nil, url, coords)

---

Play sound via another resource

local path = 'https://cfx-nui-qs-smartphone-pro/'
local sound_path = path .. 'html/sounds/test.mp3'
local soundId = exports['mx-surround']:Play(nil, sound_path, coords)

---

Play sound in an interior (with special 3d properties)

What we do is that the sound gets more out and the sound behavior changes. So you don't need to specify whether a sound is interior or not. Script detects it directly.

local url = 'https://www.youtube.com/watch?v=r2LpOUwca94&ab_channel=MajorLazerOfficial'
local unicornLocation = vec(108.65, -1288.81, 28.86) -- Vanilla Unicorn' location
local panner = {
    panningModel = 'HRTF',                           -- https://developer.mozilla.org/en-US/docs/Web/API/PannerNode
    refDistance = 20.0,                              -- Distance of the volume dropoff start
    rolloffFactor = 1.8,                             -- How fast the volume drops off 
    distanceModel = 'exponential',                   -- How the volume drops off (linear, inverse, exponential)
    coneInnerAngle = 360.0,                          -- https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/coneInnerAngle
    coneOuterAngle = 0.0,                            -- https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/coneOuterAngle
}

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

exports['mx-surround']:Play(nil, url, unicornLocation, false, 1.0, panner)

Don't think this complicated. You can do it without special panner.

local url = 'https://www.youtube.com/watch?v=OiC1rgCPmUQ&ab_channel=DuaLipa'
local unicornLocation = vec(108.65, -1288.81, 28.86) -- Vanilla Unicorn' location

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

exports['mx-surround']:Play(nil, url, unicornLocation)

---

Attach a sound to an entity

local url = 'https://open.spotify.com/track/2NsQVeehDvIpi3B4p20YSV?si=7cd044d4632d4e12'
local ped = PlayerPedId()
local coords = GetEntityCoords(ped)
local vehicle = GetVehiclePedIsIn(ped, false)

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

local soundId = exports['mx-surround']:Play(nil, url, coords)
if not soundId then return end
if vehicle then
    local networkId = VehToNet(vehicle)
    exports['mx-surround']:attachEntity(soundId, networkId)
end

---

Attach a sound to a player

The difference from attachEntity is that it detects whether the player is getting into the car or not. And performs filtering.

local url = 'https://open.spotify.com/track/2NsQVeehDvIpi3B4p20YSV?si=7cd044d4632d4e12'
local coords = GetEntityCoords(PlayerPedId())

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

local soundId = exports['mx-surround']:Play(nil, url, coords)
local playerId = GetPlayerServerId(PlayerId())
exports['mx-surround']:attachPlayer(soundId, playerId)

---

Add handler to a sound

local coords = GetEntityCoords(PlayerPedId())
local url = 'https://soundcloud.com/666astra666-ffdd/metamorphosis?utm_source=clipboard&utm_medium=text&utm_campaign=social_sharing'

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

local soundId = exports['mx-surround']:createUniqueId()
exports['mx-surround']:onStop(soundId, function(soundData)
    print('stopped', soundId)
end)
exports['mx-surround']:onPause(soundId, function(soundData)
    print('paused', soundId)
end)
exports['mx-surround']:onResume(soundId, function(soundData)
    print('resumed', soundId)
end)
exports['mx-surround']:onDestroy(soundId, function(soundData)
    print('destroyed', soundId)
end)
exports['mx-surround']:Play(soundId, url, coords)
print('Started', soundId)
Wait(1000)
exports['mx-surround']:Stop(soundId)
Wait(1000)
exports['mx-surround']:Resume(soundId)
Wait(1500)
exports['mx-surround']:Pause(soundId)
Wait(2000)
exports['mx-surround']:Resume(soundId)
Wait(5000)
exports['mx-surround']:Destroy(soundId)

Another way to add handler to a sound

local coords = GetEntityCoords(PlayerPedId())
local url = 'https://soundcloud.com/666astra666-ffdd/metamorphosis?utm_source=clipboard&utm_medium=text&utm_campaign=social_sharing'

local response = exports['mx-surround']:Prepare(url)
if not response.success then
    print('Error: ' .. response.error, 'Code:', response.errorCode)
    return
end

local soundId = exports['mx-surround']:createUniqueId()
exports['mx-surround']:setSoundHandler(soundId, {
    loading = function()
        print('loading', soundId)
    end,
    stop = function()
        print('stopped', soundId)
    end,
    pause = function()
        print('paused', soundId)
    end,
    resume = function()
        print('resumed', soundId)
    end,
    destroy = function()
        print('destroyed', soundId)
    end
})
exports['mx-surround']:Play(soundId, url, coords)
print('Started', soundId)
Wait(1000)
exports['mx-surround']:Stop(soundId)
Wait(1000)
exports['mx-surround']:Resume(soundId)
Wait(1500)
exports['mx-surround']:Pause(soundId)
Wait(2000)
exports['mx-surround']:Resume(soundId)
Wait(5000)
exports['mx-surround']:Destroy(soundId)

---

Play Async (Server Side)

RegisterCommand('asset', function(source, args)
    local sound = 'beltalarm'
    local player = GetPlayerPed(source)
    local vehicle = GetVehiclePedIsIn(player, true)
    local vehNetId = NetworkGetNetworkIdFromEntity(vehicle)
    local coords = GetEntityCoords(vehicle)
    exports['mx-surround']:PlayAsync(-1, nil, '/ui/sounds/' .. sound .. '.ogg', coords, false, 1.0, nil, {
        attachEntity = vehNetId
    })
end, false)