ZeroDev Sound: install guide

This resource does not contain or provide any third-party audio or music integrations. Music plays only from audio files the server owner adds to the resource and GTA's built-in radio. Players cannot enter links. Only add audio you own or hold the rights to use and distribute; streaming content without permission can breach the Cfx.re Creator Platform License Agreement and the law.

Speakers players buy, carry, set down and link, and car audio they build into their own cars. This is the full reference. For the short version read docs/SETUP.md (5 steps); for problems, docs/TROUBLESHOOTING.md; coming from 1.x, UPGRADING.md.

Contents 1. Requirements 2. Install 3. Items for your inventory 4. First start: what you should see 5. Settings people change most 6. Controls 7. Car audio 8. Music sources 9. Pulse Phone 10. Police, neighbours and admins 11. Languages 12. Troubleshooting 13. Updating

1. Requirements

Nothing else: no ox_lib, no API key, no Google account.

Linux servers: use the Recommended server artifact, not Latest. On the FiveM server download page (docs.fivem.net/docs/server-download/) choose Linux and the Recommended update branch. A server on the latest Linux artifact crashed while loading (FXServer printed a /proc/self/maps dump), and switching to the recommended artifact fixed it. That is the only Linux report we have; we have not run ZeroDev Sound on a Linux server ourselves yet.

On a standalone server (no framework) everything is free: the store and car parts charge nothing.

2. Install

Step 1. Drop the folder in. Put the zerodev-sound folder in your resources folder (any sub-folder is fine, for example resources/[zerodev]/zerodev-sound). Keep the folder name zerodev-sound: the ox_inventory item entries call it by that name.

Step 2. Add it to server.cfg, after your database, framework and inventory:

ensure oxmysql
ensure es_extended        # or qb-core / qbx_core, or nothing on a standalone server
ensure ox_inventory       # or your inventory
ensure ox_target          # optional, or qb-target
ensure phone              # optional: Pulse Phone
ensure zerodev-sound

Step 3. Give your admins the admin permission (no speaker limit, the /soundadmin list, remote stop and remove):

add_ace group.admin zerodev.sound.admin allow

Step 4. Set up the items for your inventory: section 3. On the ESX inventory and on QBCore this is done for you.

Step 5. Restart the server (a full restart, not only the resource, so every player loads the models) and check the console: section 4.

3. Items for your inventory

There are 12 items: ten speakers, the Mic Stand and the repair kit.

The pictures are in zerodev-sound/web/img/items/. You never have to guess: whenever something is missing, the server console prints the exact entries for your inventory and names any picture that is not in place yet.

Which inventory do you have?

To add the items to qb-core by hand instead of letting the script do it, paste the QBCore block into qb-core/shared/items.lua.

Another inventory that copies one of these APIs: set Config.Inventory to that one (see section 5). An in-house inventory can be connected in server/bridge.lua, which is readable: each inventory there is three small functions (count, add, remove).

ox_inventory block

Paste inside the return { ... } table of ox_inventory/data/items.lua:

    ['zds_repair_kit'] = { label = 'Speaker Repair Kit', weight = 600, stack = false, close = true, description = 'Fixes a broken speaker. Use it next to one.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_repair_kit.png' } },
    ['zds_roam'] = { label = 'Roam Portable Speaker', weight = 2000, stack = false, close = true, description = 'Portable speaker with twin bass radiators. Carry it or set it down.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_roam.png' } },
    ['zds_room_ceiling'] = { label = 'Ceiling Speaker', weight = 2000, stack = false, close = true, description = 'Indoor. Round ceiling or wall speaker for background music in a business.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_room_ceiling.png' } },
    ['zds_room_shelf'] = { label = 'Shelf Speaker', weight = 4000, stack = false, close = true, description = 'Indoor. Bookshelf speaker: link several around a home or shop.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_room_shelf.png' } },
    ['zds_room_sub'] = { label = 'Home Subwoofer', weight = 8000, stack = false, close = true, description = 'Indoor. Cube subwoofer: link it to your indoor speakers for deep bass.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_room_sub.png' } },
    ['zds_room_tower'] = { label = 'Tower Speaker', weight = 10000, stack = false, close = true, description = 'Indoor. Floor-standing tower with two woofers: deep, clean sound for a whole room.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_room_tower.png' } },
    ['zds_stage_array'] = { label = 'Line Array Speaker', weight = 12000, stack = false, close = true, description = 'Concert. Line-array speaker for long throw over a big crowd. Stack them.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_stage_array.png' } },
    ['zds_stage_mic'] = { label = 'Mic Stand', weight = 3000, stack = false, close = true, description = 'Concert. A mic on a boom stand: link it to your concert speakers, stand at it and sing through them (/soundmic).',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_stage_mic.png' } },
    ['zds_stage_mixer'] = { label = 'DJ Mixer', weight = 5000, stack = false, close = true, description = 'Concert. Not a speaker: whoever stands at it runs every linked concert speaker (volume, bass, sound, timing).',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_stage_mixer.png' } },
    ['zds_stage_monitor'] = { label = 'Stage Monitor', weight = 6000, stack = false, close = true, description = 'Concert. Wedge monitor so the DJ or band hears the mix on stage.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_stage_monitor.png' } },
    ['zds_stage_pa'] = { label = 'PA Speaker', weight = 10000, stack = false, close = true, description = 'Concert. Powered 15" PA top on a tripod: link many for an event.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_stage_pa.png' } },
    ['zds_stage_sub'] = { label = 'Concert Subwoofer', weight = 15000, stack = false, close = true, description = 'Concert. Double 18" sub cabinet: the bass you feel at a show.',
        client = { export = 'zerodev-sound.useItem', image = 'nui://zerodev-sound/web/img/items/zds_stage_sub.png' } },

QBCore block

The QBCore item shape, which qb-, ps-, lj- and qs-inventory read:

    ['zds_repair_kit'] = { name = 'zds_repair_kit', label = 'Speaker Repair Kit', weight = 600, type = 'item', image = 'zds_repair_kit.png', unique = true, useable = true, shouldClose = true, description = 'Fixes a broken speaker. Use it next to one.' },
    ['zds_roam'] = { name = 'zds_roam', label = 'Roam Portable Speaker', weight = 2000, type = 'item', image = 'zds_roam.png', unique = true, useable = true, shouldClose = true, description = 'Portable speaker with twin bass radiators. Carry it or set it down.' },
    ['zds_room_ceiling'] = { name = 'zds_room_ceiling', label = 'Ceiling Speaker', weight = 2000, type = 'item', image = 'zds_room_ceiling.png', unique = true, useable = true, shouldClose = true, description = 'Indoor. Round ceiling or wall speaker for background music in a business.' },
    ['zds_room_shelf'] = { name = 'zds_room_shelf', label = 'Shelf Speaker', weight = 4000, type = 'item', image = 'zds_room_shelf.png', unique = true, useable = true, shouldClose = true, description = 'Indoor. Bookshelf speaker: link several around a home or shop.' },
    ['zds_room_sub'] = { name = 'zds_room_sub', label = 'Home Subwoofer', weight = 8000, type = 'item', image = 'zds_room_sub.png', unique = true, useable = true, shouldClose = true, description = 'Indoor. Cube subwoofer: link it to your indoor speakers for deep bass.' },
    ['zds_room_tower'] = { name = 'zds_room_tower', label = 'Tower Speaker', weight = 10000, type = 'item', image = 'zds_room_tower.png', unique = true, useable = true, shouldClose = true, description = 'Indoor. Floor-standing tower with two woofers: deep, clean sound for a whole room.' },
    ['zds_stage_array'] = { name = 'zds_stage_array', label = 'Line Array Speaker', weight = 12000, type = 'item', image = 'zds_stage_array.png', unique = true, useable = true, shouldClose = true, description = 'Concert. Line-array speaker for long throw over a big crowd. Stack them.' },
    ['zds_stage_mic'] = { name = 'zds_stage_mic', label = 'Mic Stand', weight = 3000, type = 'item', image = 'zds_stage_mic.png', unique = true, useable = true, shouldClose = true, description = 'Concert. A mic on a boom stand: link it to your concert speakers, stand at it and sing through them (/soundmic).' },
    ['zds_stage_mixer'] = { name = 'zds_stage_mixer', label = 'DJ Mixer', weight = 5000, type = 'item', image = 'zds_stage_mixer.png', unique = true, useable = true, shouldClose = true, description = 'Concert. Not a speaker: whoever stands at it runs every linked concert speaker (volume, bass, sound, timing).' },
    ['zds_stage_monitor'] = { name = 'zds_stage_monitor', label = 'Stage Monitor', weight = 6000, type = 'item', image = 'zds_stage_monitor.png', unique = true, useable = true, shouldClose = true, description = 'Concert. Wedge monitor so the DJ or band hears the mix on stage.' },
    ['zds_stage_pa'] = { name = 'zds_stage_pa', label = 'PA Speaker', weight = 10000, type = 'item', image = 'zds_stage_pa.png', unique = true, useable = true, shouldClose = true, description = 'Concert. Powered 15" PA top on a tripod: link many for an event.' },
    ['zds_stage_sub'] = { name = 'zds_stage_sub', label = 'Concert Subwoofer', weight = 15000, type = 'item', image = 'zds_stage_sub.png', unique = true, useable = true, shouldClose = true, description = 'Concert. Double 18" sub cabinet: the bass you feel at a show.' },

If you changed a label, price or weight in config/catalogue.lua, copy the entries from your own console instead: it prints them from your settings.

4. First start: what you should see

In the server console

ZeroDev Sound prints one check box (type soundcheck in the server console to print it again): database and schema, framework, money, inventory and items, the garage table, targeting, Pulse Phone, models, install bays and settings changed in game. Every line that is not OK says what to do; docs/SETUP.md shows a sample and docs/TROUBLESHOOTING.md explains each line.

• The framework line names what was found. If it is wrong, set Config.Framework or Config.Inventory in config/config.lua.
• A yellow line Add these to ox_inventory/data/items.lua ... (or ... if these items are not in ... yet, add them) followed by item entries: do section 3 for your inventory, then restart. The ox_inventory message stops once the items are in. On qs-, codem-, origen- and tgiann-inventory the entries are printed at every start as a reminder, whether or not you have added them.
• A yellow line Copy zds_....png from zerodev-sound/web/img/items into ...: those pictures are not in your inventory's picture folder yet. It names the folder.
• Pulse Phone app not registered: ...: Pulse Phone is running but refused the app. See section 9.

In game (five checks)

1. The map shows a ZeroDev Sound blip in Legion Square and a Car audio bay blip at Benny's.
2. At the store, a clerk stands at a stand with the speakers on show. Target the clerk (or press E when there is no target resource) and buy a Roam Portable Speaker.
3. Use it from your inventory. It comes out in your hands. Press E, open Library and play Night Drive (a demo track that ships with the script). People around you hear it.
4. Get into a car. The first few times, the corner of the screen says which key opens the car stereo (K by default).
5. Drive into the car audio bay as the driver and press E. The installer opens on your car.

5. Settings people change most

In game: /soundadmin > Settings changes the common ones live for everyone (install bays, who can install, which cars, prices, loudest volume, quiet hours, limits, store, police and damage). They are saved in the database and win over config.lua until you press Reset to config in the panel.

Everything is in config/config.lua unless noted. Products, prices and car parts are in config/catalogue.lua; the factory sound of each car is in config/vehicles.lua.

Item names. If another script already uses one of the zds_ item names, rename that product's key in Catalogue.Speakers (for example zds_roam = { ... }), then use the new name in your inventory and rename its picture to match.

6. Controls

In the remote: Music (your server's library), Queue (up next, saved playlists), Speakers (each speaker's power and level, linking, packing up), and Tune (six sound modes, a three-band equaliser, who picks the music, opening hours, and "Real distance" for concert rigs). Who picks the music: Only me; Party, where anyone nearby can request songs for the owner to approve; or Anyone, where people nearby can play, pause, skip, queue and seek. Opening hours plays one of the owner's playlists by itself between two hours, for a shop or club.

The mic (needs pma-voice). While you hold it, everyone near any speaker of that system hears your voice through it, with a PA sound, as loud as that speaker plays music and as far as it carries; walk 4 m away from the mixer or mic stand, disconnect, or put the mic back, and your voice is normal again. Only the system's owner (and admins, for a car) can sing through it; give other players the zds.mic ace to let them use any system. Your voice is not heard from each speaker's spot: voice chat cannot place a voice there, so people near a speaker hear you at that speaker's loudness instead. Settings: Config.Mic.

7. Car audio

How players build

1. Drive into the car audio bay (Benny's by default) and press E as the driver.
2. Start from a ready kit (Daily thump, Competition, Trunk wall, Sound quality, Clean and hidden) or pick parts: subwoofers (8" to 18"), boxes, amplifiers, door speakers, tweeters, pods, false floors, panels, plexi, capacitor, second battery, LED strip and head unit.
3. Drag each part into place on the car. Subs drop into their box's cut-outs. Each part takes a finish (eight colours), and subs and speakers a grille and light ring. Mirror copies a part to the other side; Fine position moves it in small steps. Five camera views: Boot, Cabin, Side, Front, Top. Size: subs come in 8", 10", 12", 15" and 18" (every sub in a box is one size and the box is built around them, up to 30% bigger or smaller than it was made for); door speakers in 5.25", 6.5" and 6x9"; every other part from 80% to 130% in 5% steps (the head unit is a standard size). Bigger boxes and panels cost more; a part made smaller costs nothing. Cones move further on bigger drivers, and a bigger door speaker reaches lower.
4. Press Test system to hear the build play through the car before paying. It plays the first song in Config.Library (the shipped demo track unless you changed it).
5. Press Install. Only parts that are new to the car are charged; parts kept from the last install are not charged again.

The install is saved against the plate and comes back whenever the car does: from any garage, impound or respawn. Nothing to edit in your garage script.

What players hear

• Every car already has a factory sound by class and model: a 4-speaker system, a premium 10-speaker or a reference 13-speaker system, fairing speakers on motorbikes; bicycles, aircraft and trains have none. Fitted speakers replace the factory speakers nearest to them; subs add to it.
• Outside the car, mostly the bass gets through the body. Open doors, open windows and an open boot each let more out, toward the side they face.
• A car with subs bounces gently on its springs with the bass while it is parked or crawling (never while driving), and everyone inside feels the kick.
• The stereo (K) has volume, sub level, fader and balance.
• Subs driven far past what their amplifier and rating allow, near full volume, for a while can blow. Everyone near the car sees a thin wisp of smoke from that sub and hears a dull pop. A blown sub stops moving, the bass drops, and its cone stays charred until it is replaced in the bay (a new sub is paid for; clearing the mark is not a free repair). Staff can show it: /soundblow in the car, or soundblow <plate> in the server console.

Which cars can be built (Config.Install.vehicles)

• 'owned' (default): only cars in your framework's owned-vehicles table (owned_vehicles on ESX, player_vehicles on QBCore and Qbox).
• 'any': also cars nobody owns (NPC cars, spawned cars, rentals).
• Either way, a car another player owns stays theirs: only its owner, an on-duty mechanic from Config.Install.jobs, or an admin can change it. On a standalone server every car counts as owned.

Garages, plates and impounds

• Plates are matched trimmed and in capitals, so garages that pad or re-case plates still match.
• A car with a fake or changed plate does not find its install until it has its saved plate again.
• Cars that exist only on one player's screen (garage previews, some showroom cars) never get an install: they are not real cars to anyone else.

Other sound or stereo scripts

ZeroDev Sound is its own resource with its own commands (/sound, /caraudio, ...), events and vehicle state bags, so it does not replace or change other scripts (while it plays in a car it only turns off GTA's own car radio). Running two car-audio scripts on the same car at once has not been tested together: use one stereo per car.

8. Music sources

Music plays only from audio files you add to the resource. Players pick from your list; they cannot enter links, and no web address is ever played. Only add audio you own or hold the rights to use and distribute.

• Put mp3 or ogg files in zerodev-sound/web/library/ and list each in Config.Library as { title = '...', artist = '...', file = 'name.mp3' }. They get the full experience: 3D sound, rooms and walls, car cabins, sound modes, EQ, and cones that move with the real bass.
• Config.Sources.library = false turns the library off.
• GTA's own car radio still works in any car while no song from this resource is playing in it.
• The start-up box shows how many songs players can pick, and warns about any entry it skipped (a file name that is not an mp3 or ogg inside web/library/).
• Updating from 3.0.0: saved songs, recent songs and playlist entries that were links are no longer shown or played. Library songs keep working.

9. Pulse Phone

Nothing to set up. When Pulse Phone runs on the server (resource name phone, either edition):

• Every phone gets a Sound app on its Home Screen. It is the same remote as /sound: connect to a speaker or the car, pick music, run the whole group. Players can remove it and get it back from the App Hub.
• What is playing on the connected speaker or car, with the time left, shows on the Island and the Lock Screen. A tap opens the Sound app.
• Pulse Drive (Pulse's car screen, F10 by default) shows the stereo of the car you sit in: song, artist and cover, with play, pause, previous, next and volume, and an Open button for the Sound app. This needs Pulse Phone 1.2.9 or newer; older versions simply do not show it.

Players without the phone use /sound and K, which do everything the app does.

If you renamed the phone's folder, add this line to config/config.lua with its name:

Config.PulseResource = 'phone'

10. Police, neighbours and admins

11. Languages

The script ships in the same 25 languages as Pulse Phone. Set one in config/config.lua:

Config.Locale = 'de', for example. The default, 'auto', follows Pulse Phone: the server takes Pulse's Config.Locale, and each player gets Sound in the language they picked on their phone. Without Pulse it is English. Game messages, key prompts, item names and the stereo key name are in locales/<code>.lua; the interface (remote, car stereo, store, installer, Pulse app) is in locales/<code>_ui.lua. Anything missing falls back to English.

To change a line, edit it in that language's file. Keep every %s, %d, %.1f, %% and ~a~ as they are. To add a language of your own, copy locales/en.lua to locales/xx.lua, change Locales['en'] to Locales['xx'] (both places), translate the text between the quotes and set Config.Locale = 'xx'. locales/ui_strings.txt lists every interface key for an xx_ui.lua.

12. Troubleshooting

Players cannot use the speaker items

• ox_inventory: the entries must be inside ox_inventory/data/items.lua with their client line, and ox_inventory must be restarted after pasting. The folder must still be called zerodev-sound (the entries call zerodev-sound.useItem).
• QBCore / ESX: zerodev-sound must start after your framework in server.cfg.
• codem-inventory on QBCore: complete codem-inventory's own step that points QBCore.Functions.UseItem at it.
• No inventory: speakers are not items. Players open /sound and press Set up under Your speakers.

Item pictures are missing

• ox_inventory: nothing to copy; the picture path points at zerodev-sound. If they are blank, check the entry's image = 'nui://zerodev-sound/...' line and the folder name.
• Other inventories: read the console line Copy ... into ...: it lists the missing pictures and the folder they go in. Copy them from zerodev-sound/web/img/items/ and restart the inventory.

A player cannot play a link

That is by design: players pick from your library only. Add the song to Config.Library (section 8).

No sound at all

• FiveM's built-in browser starts sound without a click, so players never need to press anything to "allow" audio. If one player hears nothing while others do, check FiveM in their Windows volume mixer.
• Check the speaker in the remote's Speakers tab: it may be switched off, or Broken.
• Police may have turned it off (for Config.Police.silenceMinutes), or quiet hours may be capping the volume (Config.QuietHours).
• A player hears at most Config.Streaming.maxAudibleSessions separate songs at once (6), nearest first.
• Test system in the installer is silent when Config.Library is empty or Config.Sources.library = false: it plays the first library song.

The store is not there

• Config.Shop.enabled must be true.
• The clerk and the stand appear only when a player is within about 70 m of Config.Shop.locations, and only on that player's screen. Check the coordinates you set.
• With ox_target or qb-target, target the clerk. Without one, stand at the clerk: E Browse speakers.

A speaker shows as a plain GTA speaker, or not at all

The stream/ folder is missing or was renamed, or the player joined before the resource started. Restart the server and reconnect.

Car audio messages and what they mean

Police cannot see their options

Add your police job names to Config.Police.jobs. Players must be on duty.

13. Updating

Coming from 1.x to 2.0: read UPGRADING.md. Between 2.x versions:

1. Back up your config/ folder, locales/ if you translated it, and any songs you added to web/library/.
2. Stop the server. Replace the zerodev-sound folder with the new one (keep the name).
3. Put your config/ files back. If the update notes mention new settings, copy those lines from the new files into yours.
4. Start the server and read the console. New items, if any, are printed for your inventory.

Placed speakers, car installs and playlists are kept in the database (zds_speakers, zds_car_builds, zds_playlists, zds_stash) and are not touched by an update.

Going back: keep the previous zerodev-sound folder outside resources until the new version runs well, and back up the database before updating. To go back, stop the server, put the previous folder and your config/ back, and start it. Going back from 3.0 to 2.x on the same database has not been tested, so restore the database backup if anything looks wrong.