🎵 Dynamic Jukebox

Positional business music system for QBCore + xsound

Add ambient music to any business on your server. Music plays from the center of each location as 3D positional audio, and players control playback from a separate jukebox interaction point with a clean NUI panel.

---

Features

• 3D Positional Audio — Music radiates from a configurable center point using xsound. Volume fades naturally as players walk away.
• Separate Jukebox Control — Players interact at a dedicated jukebox location to manage playback, keeping the sound origin and control point independent.
• Playlist Looping — Songs auto-advance and loop back to the start. Add as many MP3s per business as you want.
• Shuffle Mode — Toggle per-business random playback with proper Fisher-Yates shuffling.
• NUI Control Panel — Play/pause, skip forward/back, volume slider, full track list with click-to-play, and shuffle toggle.
• Server-Synced — All players hear the same track at the same volume. State is server-authoritative.
• Per-Business Config — Each business gets its own playlist, volume, sound distance, and optional job lock.
• Optional Jukebox Prop — Automatically spawns a GTA jukebox prop at each control point, or disable it if your MLO already has one placed.
• Flexible Interaction — Supports qb-target, ox_target, or simple drawtext + E key.
• Admin Commands — Start/stop all jukeboxes, set volume per-business from console.

---

Dependencies

Resource	Required
qb-core	✅
xsound	✅
qb-target	Optional (if Config.UseTarget = true)
ox_target	Optional (alternative to qb-target)

---

Installation

1. Download and place the dynamic-jukebox folder in your server's resources/ directory
2. Add your .mp3 files to the dynamic-jukebox/music/ folder
3. Edit config.lua to configure your businesses (coords, playlists, options)
4. Add ensure dynamic-jukebox to your server.cfg (after qb-core and xsound)
5. Restart your server

---

Configuration

Adding a Business

Each business in config.lua needs two sets of coordinates:

• soundCoords — The center of the business interior. This is where the music plays from. Place it in the middle of the room for the best 3D audio spread.
• jukeboxCoords — Where the jukebox prop spawns and where players walk up to interact. Place it against a wall or in a corner where a jukebox would naturally sit.

{
    name = 'my_bar',                                        -- Unique ID (no spaces)
    label = 'My Bar',                                       -- Display name in UI
    soundCoords = vector3(-1387.08, -588.41, 30.32),        -- Center of room
    jukeboxCoords = vector4(-1385.20, -590.10, 30.32, 210), -- Jukebox location + heading
    playlist = {
        'rock_anthem.mp3',
        'blues_jam.mp3',
        'country_roads.mp3',
    },
    defaultVolume = 0.5,     -- 0.0 to 1.0 (optional)
    maxDistance = 50.0,       -- How far music carries in GTA units (optional)
    jobLock = nil,            -- Job name to restrict access, or nil for public (optional)
}

Jukebox Prop

The script can automatically spawn a GTA prop at each jukebox location:

Config.JukeboxProp = 'prop_jukebox_01'  -- Spawn a jukebox prop
Config.JukeboxProp = 'prop_radio_01'    -- Or use a radio prop
Config.JukeboxProp = false              -- Disable prop spawning (use with MLO-placed props)

Interaction Method

Config.UseTarget = true                 -- Use qb-target or ox_target
Config.UseTarget = false                -- Use floating 3D text + E key (no target dependency)
Config.TargetResource = 'qb-target'     -- 'qb-target' or 'ox_target'

---

Commands

Player Commands

Command	Description
/jukeboxreload	Re-sync jukebox state from server
/jukeboxhelp	List all available commands

Admin Commands

Command	Description
/jukeboxstop	Stop all jukeboxes server-wide
/jukeboxstart	Start all jukeboxes server-wide
/jukeboxvol [business] [0-100]	Set volume for a specific business

---

Adding Music

Place .mp3 files in the music/ folder and reference them by filename in each business's playlist table:

dynamic-jukebox/
└── music/
    ├── chill_lounge.mp3
    ├── jazz_cafe.mp3
    ├── rock_bar.mp3
    └── country_saloon.mp3

Keep file sizes reasonable — large MP3s take longer to stream to clients. 128-192kbps is plenty for in-game ambient music.

---

Troubleshooting

Music doesn't auto-advance to the next track? The script listens for the xsound:Finish event. Some xsound versions use a different event name. Check the comment in client.lua near the RegisterNetEvent('xsound:Finish' line for alternatives to try.

Jukebox prop not appearing? Make sure Config.JukeboxProp is set to a valid GTA prop model name, not false. Run with Config.Debug = true to see console output.

Can't interact with the jukebox? Check that your target resource matches Config.TargetResource, or set Config.UseTarget = false to use drawtext instead.

Music cuts out when walking away? Increase maxDistance for that business in the config. Default is 50 GTA units.

---

Credits

Dynamic Scripts — Development & design

---

License

MIT — See LICENSE for details.

---

License & Contributing

This resource is source-available, all rights reserved under the Dynamic Scripts Proprietary License. You may view the code, but you may not redistribute, resell, or publish modified or "improved" versions.

Found a bug, fix, or improvement? Please don't fork or republish - instead DM the author at wax@waxthe.dev, and it may be incorporated (with credit).