ZeroDev Sound docs

ZeroDev Sound developer API

ZeroDev Sound has an open API for other resources: read what is playing, run a speaker system or a car stereo for a player from your own menu, follow changes, place speakers and install bays of your own, and drive lights from the real bass. Everything here is taken from ZeroDev Sound 3.0.5. The API files are not escrowed, so you can read the contract yourself: server/devapi.lua and client/devapi.lua.

For ZeroDev Sound 3.0.66 min readUpdated

ZeroDev Sound checks every value it is given and keeps working when your resource is missing, stopped or broken. Quiet hours, police silencing and the owner's volume cap apply to everything that plays.

Finding the resource

The resource carries the manifest marker audio_extensions 'v1'. Find it by that, not by its folder name, because servers may rename the folder:

Lua
local function soundResource()
    for i = 0, GetNumResources() - 1 do
        local res = GetResourceByFindIndex(i)
        if res and GetResourceState(res) == 'started' and GetResourceMetadata(res, 'audio_extensions', 0) == 'v1' then return res end
    end
end

Call it with exports[res]:.... Event names start with the resource name: res .. ':session'.

A session is one song stream: a group of linked speakers in the world (kind = 'speakers') or one car's stereo (kind = 'car', key car:<plate>). A song is picked by a reference: library:<n> (a song in Config.Library), file:<name> (a file in web/library) or request:<n> (a song request the owner added).

Server exports

Export Returns
GetSessions() every session on the server
GetSession(key) one session, or nil
GetCarSession(vehicle) the session of a vehicle (entity or plate text), or nil
Targets(src) what this player may run right now: { key, kind, label, canPlay, why }
Control(src, key, action, data) ok, reason
Ready() true once Sound has loaded
ApiVersion() 2

Control runs an action with the same rules as Sound's own remote: anyone in the car runs its stereo; a placed system follows its owner and its party or public setting, and the player must be within reach. Pass src = 0 to act with your script's own authority, after your script has decided who may.

Action Data
play { text = reference } (without text: resume)
queue { text = reference }
resume, pause, next, previous, stop none
volume { value = 0.0 - 1.0 }
seek { at = seconds }
mode { value = 'studio' }, or bass, club, vocal, concert, night, chipeo
eq { low, mid, high } in dB, -12 to 12
repeatMode { value = 'off' }, or one, all

When ok is false, reason is one of no_session, bad_action, no_player, not_inside, out_of_range, not_allowed, mixer_alone, no_text, catalogue_only or error.

Example: the club speakers play the house song when the DJ clocks in.

Lua
RegisterNetEvent('myclub:clockIn', function()
    local src = source
    for _, t in ipairs(exports[res]:Targets(src)) do
        if t.kind == 'speakers' then
            exports[res]:Control(src, t.key, 'play', { text = 'library:3' })
            exports[res]:Control(src, t.key, 'mode', { value = 'club' })
        end
    end
end)

Fixed speakers and install bays

A shop, club or garage script can put its own speakers and an install bay in its building. They have no owner and no item, are never saved, and go when your resource stops. Players cannot move or pack them up; police can still silence them.

Lua
local id, key = exports[res]:AddFixedSpeaker({
    id = 'radio_1',              -- yours to name; adding the same id again moves it
    item = 'zds_room_ceiling',   -- any placed Sound speaker item
    coords = vector3(x, y, z), heading = 90.0,
    pitch = -90.0,               -- on a ceiling, grille down; 0 on a floor or wall
    label = 'Store radio',
    group = 'store',             -- same group = one system
})
exports[res]:RemoveFixedSpeaker('radio_1')
exports[res]:GetFixedSpeakers()  -- { { id, speaker, key } } of your resource

exports[res]:AddBay({ id = 'garage', label = 'Garage audio bay', coords = vector3(x, y, z), radius = 6.0, blip = true })
exports[res]:RemoveBay('garage') -- up to 8 bays per resource, radius 3 to 15 m

Add them when your resource starts, and again on <res>:ready, in case Sound starts after you.

Server events

Lua
AddEventHandler(res .. ':session', function(key, session) end)   -- any change: song, pause, volume, mode, queue
AddEventHandler(res .. ':songStarted', function(session) end)    -- a different song started
AddEventHandler(res .. ':sessionRemoved', function(key) end)     -- speakers packed up, a car session ended
AddEventHandler(res .. ':ready', function() end)                 -- Sound started and loaded

These are server-local events, never sent from a client, so a client cannot fake them.

Client exports (read-only)

Export Returns
GetSessions() the sessions this client knows: nearby and its own
GetCarSession(vehicle) the car's session, or nil
GetBass(key) 0.0 to 1.0: the bass of the real song this frame, 0 when silent
CarAudioState(vehicle) the head unit's state, for car screens

Example: underglow that pulses with the car's subs.

Lua
CreateThread(function()
    while true do
        local veh = GetVehiclePedIsIn(PlayerPedId(), false)
        local s = veh ~= 0 and exports[res]:GetCarSession(veh)
        if s and s.title and not s.paused then
            SetVehicleNeonLightsColour(veh, 255, math.floor(40 + 200 * exports[res]:GetBass(s.key)), 255)
            Wait(0)
        else
            Wait(500)
        end
    end
end)

Config examples

The settings are in zerodev-sound/config/config.lua, and every one can be changed in game in /soundadmin.

Lua
Config.Framework = 'auto'        -- or 'esx', 'qb', 'qbox', 'standalone'
Config.Inventory = 'auto'        -- or 'ox', 'qb', 'qs', 'codem', 'core', 'origen', 'tgiann', 'esx', 'none'
Config.MaxPlacedPerPlayer = 8
Config.QuietHours = { enabled = true, from = 23, to = 7, maxVolume = 0.35 }

Rules for integrations

  • Do not change ZeroDev Sound's files; use the API. A changed escrowed file stops the resource from loading.
  • Pass the real source to Control, or check permission yourself before you use src = 0.
  • Read GetBass at most once a frame, and sleep when nothing plays.
  • The API is versioned (audio_extensions 'v1', ApiVersion() 2). A breaking change gets a new version and a line in the changelog.

Frequently asked questions

How do I find ZeroDev Sound from my script?

Look for the resource whose manifest has audio_extensions 'v1', as in the first example. The folder may have another name on some servers.

Can my script play music on a player's speakers?

Yes, with Control(src, key, 'play', { text = 'library:1' }). The same rules as Sound's own remote apply: the player must be allowed to run that system and be within reach.

Can lights or props follow the music?

Yes. The client export GetBass(key) gives the bass of the song playing, every frame, from 0 to 1.