Browse docs
Installation
Requirements
| Requirement | Purpose |
|---|---|
| FiveM server with OneSync enabled | Shared club state, routing buckets and server-side position checks |
ESX with RunStaticPlayerMethod support | Player access and framework integration |
ox_lib | Callbacks and shared utilities |
sky_base with a working database connection | Framework bridge, interactions and automatic SQL persistence |
Optional ox_target | Target interaction when selected in Sky Base |
Use the database provider already configured for Sky Base, such as oxmysql or mysql-async. Sky DJ includes its audio engine; a separate sound resource and sky_jobs_base are not required.
The customer package already contains the built frontend. Neither music mode requires customers to install Node.js, Yarn, npm modules, Python, FFmpeg or a webserver. FiveM supplies the embedded runtime used by Experimental delivery. No domain, certificate or additional music port is needed.
Install the resource
Copy the complete resource
Extract the release package and copy the complete sky_dj resource into your server's resources directory. The standalone drag-and-drop package contains resources/[sky]/sky_dj/; a central resource ZIP may contain sky_dj/ directly.
Keep the resource name sky_dj and retain its complete config, source and stream folders. Your installation must contain fxmanifest.lua directly inside sky_dj, without an extra nested sky_dj directory:
resources/
└── [sky]/
└── sky_dj/
├── fxmanifest.lua
├── config/
│ └── music/
├── source/
│ └── html/
└── stream/
Keep package-root instructions beside your extracted package; they are not resources to start. There is one resource for both music modes and no separate Normal or Experimental package to install.
Configure the database and start order
Start your database provider and ESX before the Sky resources. This example uses an existing oxmysql installation; retain your own database connection settings and provider:
set onesync on
ensure oxmysql
ensure es_extended
ensure ox_lib
ensure sky_base
ensure sky_dj
OneSync must be enabled before resource startup. See the official FiveM resource commands and OneSync setting.
Sky Base creates the sky_dj_state table and missing initial records automatically. The database account must be able to create or alter the resource's tables and read and write their data. No manual SQL import is required. Preserve existing records when updating; do not reset the table to change music delivery.
Choose who owns the settings
The default Config.IngameSettings = true uses saved SQL settings. On first startup, shipped defaults seed missing settings; existing saved values take precedence. Open /djadmin → Settings as an authorized administrator and save global changes there. Other global entries in the customer's config/config.lua do not override SQL settings in this mode.
For file-owned global configuration, change the existing IngameSettings entry to false, edit config/config.lua, and restart sky_dj. Global settings writes are then disabled in-game while the saved SQL row is retained. Club layouts, placed devices and playlists remain in SQL in either mode.
Administrator access defaults to ESX admin / superadmin or ACE sky.dj.admin. See Configuration for permissions, language and configuration ownership.
Add original MP3s
Put your own original MP3 files in sky_dj/config/music/, then restart sky_dj. Both delivery modes use this same folder. The customer package does not include a music library.
- Use at most 500 MP3 files in the selected directory. Subfolders are not scanned.
- Files may be up to 50 MiB each. Names may contain ASCII letters, numbers, spaces, underscores, hyphens and periods, must start with a letter, number, underscore or hyphen, and must end in lowercase
.mp3. Maximum length is 160 characters;..is rejected. - Keep paths and filename capitalization consistent, especially on Linux. Folder paths use forward slashes; symlinked folders are not supported.
- Upload audio through your server's file manager or SFTP. The in-game library manages playlists and settings; it does not upload files.
- Preserve original filenames when updating or moving music: playlist track IDs use those filenames.
- Restart the owning resource after adding, removing or replacing files so FiveM rebuilds the optional music pack and Sky DJ refreshes its catalogue.
Original MP3 bytes are used without conversion. Leave Music folder at config/music for the built-in setup.
Create a playlist and test playback
Open /djadmin → Settings → Music & Playlists, create a playlist and add tracks. Assign that playlist to a club and save the club. At its DJ booth, load an assigned track into deck A or B and test playback.
For a new custom club, place its DJ booth and at least one speaker before saving. The fixed festival is configured separately from your own clubs. Music synchronization is optional and starts disabled; ordinary playback does not require it.
Choose music delivery
The Experimental on-demand MP3 checkbox under Settings → Music & Playlists → Library & Queues selects delivery for the same original files:
| Checkbox | Delivery | When audio is received |
|---|---|---|
| Off — Normal MP3 (default) | FiveM mounts the complete optional sky_dj_music music pack into its native cache. | The first local MP3 use, including playback or PFL, can request the complete library. The pack is not automatically requested during connection. |
| On — Experimental / not stable | Only currently needed songs transfer through FiveM's internal events. The optional music pack is not requested. | An eligible listener near a playing club or a DJ loading a deck/PFL receives needed songs. Each selected MP3 finishes loading before playback. |
With SQL-owned settings, enable Experimental only after acknowledging its warning, then save. Sources on loaded decks and queues update live; switching modes does not require moving music, replacing the package or restarting the resource. Existing SQL settings, playlist filename IDs and club assignments are retained.
For file-owned settings, edit these existing entries and restart sky_dj:
IngameSettings = false,
MusicDirectory = 'config/music',
MusicOnDemandExperimental = false, -- Normal; true selects Experimental
The shipped default is MusicOnDemandExperimental = false. Existing saved choices are preserved. File-library changes still require a resource restart, even though an in-game mode change applies live.
Connection downloads and loading
The supplied manifest keeps library MP3s in the optional set:
file_set 'sky_dj_music' {
'config/music/*.mp3',
}
Keep this declaration. Do not also add library MP3s to ordinary client files, client_script, shared_script or streamed-asset folders; those locations can download independently of the music checkbox.
No automatic full-library download during connection does not mean that players never receive music. After joining, a player near an active club may immediately need its playing songs. In Normal mode, that first local music use can start the complete optional-pack download. In Experimental mode, only currently needed songs load, and the complete selected MP3 is received before decoding and playback. Spawning inside a playing club can therefore cause audio transfer soon after joining.
Experimental transfers retain listener authorization, routing-bucket checks, bandwidth budgets and a bounded transfer window. Cold tracks can take time to load; slow links, large files and many simultaneous listeners need testing on your server. This mode does not promise a fixed loading time.
Existing custom music sources
The built-in optional-pack setup applies to sky_dj/config/music/. For restart-free switching between these two modes, keep that folder and the supplied manifest.
An advanced existing Normal source such as @sky_dj_music/music requires its owning resource to publish the MP3s through ordinary client files and to start before Sky DJ. Such music still downloads when players connect, independently of the Sky DJ checkbox. Sky DJ cannot mount another resource's optional file set on its behalf. Custom Normal folders inside sky_dj likewise need ordinary client publication. Experimental rejects a selected source whose MP3s are already client-published.
Absolute operating-system paths and symlinked folders are unsupported. See Configuration before changing Music folder.
Updating an existing installation
Back up config/, original music files and the sky_dj_state database table before updating. Replace the complete published runtime together so Lua, the built NUI and streamed assets match. Preserve your original MP3 names and SQL records.
The former external HTTPS/Opus delivery and its settings are retired. Generated Opus exports are not used; keep the original MP3s in config/music/. No converter, domain or external music host is needed. If updating the earlier private-folder experiment, move its original MP3s from config/music-private/ back to config/music/ and restart sky_dj. Do not replace saved settings or playlists with empty records.
An existing custom Music folder is retained during migration. If it points at an old export folder, open Settings → Music & Playlists → Library & Queues, set Music folder to config/music, and save. In file mode, update the existing MusicDirectory value instead and restart. Moving MP3s without updating that saved folder leaves the catalogue pointed at the old location.
Final check
Test playback, seeking, A/B transitions and optional music synchronization with two FiveM clients. Verify that saved settings and club assignments survive a restart.
Use a fresh-cache client outside any playing club to check that joining does not automatically request the music library. Then test Normal's first-use complete-pack download separately from Experimental's needed-song transfer. Also join or walk into an active club and check that its current music loads and joins the correct playback position.
After a map update, fully exit and relaunch FiveM before checking streaming and collision.
Continue with Overview and Configuration. For missing tracks, downloads, playback or access errors, use Troubleshooting.