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.
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:
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
endCall 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.
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.
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 mAdd them when your resource starts, and again on <res>:ready, in case Sound starts after you.
Server events
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 loadedThese 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.
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.
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
sourcetoControl, or check permission yourself before you usesrc = 0. - Read
GetBassat 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.