Features

Music Playback

The core music system lets players paste YouTube URLs to play audio inside their vehicle.

URL Handling

Paste a YouTube video URL into the input field and press Play. The system extracts the video ID and fetches metadata (title, thumbnail) from the server.

Metadata Fetching

The server uses a multi-provider fallback chain for YouTube metadata:

Provider	Purpose	Fallback Order
noembed.com	Single video title and thumbnail	Primary
Piped API	Playlist track listing and metadata	Primary (playlists)
Invidious	Playlist track listing and metadata	Fallback (playlists)

If a provider is unreachable, the system automatically tries the next one. Single video playback only requires noembed.com.

Playback Controls

Control	Description
Play	Start playback of a pasted URL
Pause	Pause the current track
Resume	Resume paused playback
Next	Skip to the next track in the queue
Volume	Adjust playback volume (0-100)

3D Positional Audio

All music plays through xsound as 3D positional audio, making it audible to nearby players with realistic spatial effects.

Vehicle Openness Detection

The system calculates a vehicle "openness" value (0.0 to 1.0) based on door and window states. This affects how sound propagates:

State	Effect
All doors/windows closed	Volume reduced by VolumeMultClosed (default 0.15x)
Doors or windows open	Volume scales with openness (0.0-1.0)

Audio Range

Setting	Default	Description
AudioRange	12.0	Hearing distance in meters (doors/windows open)
AudioRangeClosed	2.0	Hearing distance in meters (fully closed vehicle)
SpeedRangeBonus	0.25	Extra range per unit of vehicle speed

The effective hearing range increases with vehicle speed, simulating the doppler-like effect of a passing car with music.

Distance Falloff

Volume decreases linearly with distance from the vehicle. At the edge of the audio range, volume reaches zero. The PositionUpdateInterval (default 150ms) controls how frequently the 3D audio position is updated to track vehicle movement.

Queue System

The queue holds upcoming tracks that play automatically after the current song ends.

Queue Limits

Setting	Default	Description
MaxQueueSize	20	Maximum tracks in the queue

Queue Operations

Action	Description
Add to Queue	Adds a track to the end of the queue
Remove from Queue	Removes a specific track by index
Play from Queue	Jumps to and plays a specific track, removing it from the queue
Next	Skips the current track and plays the next queued track

Auto-Advance

When the current track ends, xsound's onPlayEnd callback automatically triggers the next track in the queue. If the queue is empty, playback stops.

Playlist System

Playlists provide persistent storage for track collections that survive server restarts.

Playlist Limits

Setting	Default	Description
MaxPlaylists	10	Maximum saved playlists per character
MaxPlaylistTracks	50	Maximum tracks per playlist

Playlist Operations

Action	Description
Save as Playlist	Saves the current queue as a new playlist
Load	Replaces the current queue with the playlist's tracks
Add All	Appends the playlist's tracks to the current queue
Rename	Changes the playlist name
Delete	Permanently removes the playlist

YouTube Playlist Import

Paste a YouTube playlist URL into the input field to import all tracks at once. The server fetches track metadata via the Piped API (with Invidious as a fallback) and presents the tracks for saving as a local playlist.

Persistence

Playlists are stored per-character using FiveM's KVP system with the key format carplay:char:{charId}. Data persists across server restarts without any database. Each character has their own independent playlist library.

Multi-Passenger Sync

Music state is synchronized across all vehicle occupants using FiveM statebags.

How It Works

1. The controlling player's client sets the vehicle's oxide:carplay statebag with the current playback state
2. The server relays state changes to all clients
3. Passengers detect the statebag and start/stop xsound playback to match

Synced State

The statebag contains:

Field	Description
url	Currently playing YouTube URL
title	Track title
thumbnail	Track thumbnail URL
playing	Whether playback is active
volume	Current volume level
queue	Full queue contents
jailbroken	Whether the vehicle has been jailbroken

Desync Recovery

A proximity scan runs every ProximityScanInterval (default 2000ms) to discover nearby vehicles playing music. If a passenger's local state doesn't match the vehicle statebag, the system reconciles automatically by restarting playback with the correct state.

Navigation Map

The Map tab displays a tiled map of San Andreas with real-time player tracking.

Map Display

Feature	Description
Tiled background	20 JPG tiles covering the full GTA V map
Player marker	Shows current position and heading direction
Street label	Displays the current street name
Zone label	Displays the current area/neighborhood name
Weather	Shows current weather condition
Time	Displays current in-game time

The map updates at MapUpdateInterval (default 500ms) to track player movement.

Quick Nav

Quick Nav buttons let players set a GPS waypoint to the nearest location in each category:

Category	Description
Gas	27 gas station locations across the map
Store	Configurable store locations (empty by default)
Garage	5 garage locations
POI	Hidden locations unlocked via jailbreak

Tapping a Quick Nav button calculates the closest location and sets it as the GPS waypoint.

Jailbreak System

The jailbreak system is an optional progression mechanic that unlocks hidden POI locations on the navigation map.

Requirements

Setting	Default	Description
RequiredItem	'carplayjb_usb'	Item needed in inventory
RemoveItem	true	Whether the item is consumed on success

Jailbreak Flow

1. Item Use — Player uses the carplayjb_usb item while in a vehicle
2. Animation — A progress bar plays for Duration (default 8 seconds) with a configurable animation. The player can cancel during this phase
3. Circuit Trace Minigame — On progress bar completion, a wire-tracing minigame appears in the NUI
4. Result — Success unlocks POI locations on the map and sets the vehicle's jailbroken flag. Failure consumes the animation time but does not consume the item

Circuit Trace Minigame

The minigame presents procedurally generated wire paths that the player must trace:

Setting	Default	Description
Difficulty	'medium'	Difficulty level affecting wire complexity

The difficulty setting controls the number of wires, path complexity, and time pressure. Available levels: easy, medium, hard.

Hidden POIs

On successful jailbreak, 8 POI locations become visible on the navigation map:

Location	Area
Vinewood area	Central LS
LSIA warehouse	Airport
Sandy Shores	Desert
Grapeseed	North county
Paleto Bay	Far north
Underground bunker	Below ground
Airport hangar	LSIA
Port of LS dock	South docks

POI locations are configured in Config.Jailbreak.POIs and can be customized by server owners.

Vehicle State

The jailbreak flag is per-vehicle (stored on the vehicle's statebag). Jailbreaking one vehicle does not unlock others. The flag persists as long as the vehicle entity exists.

Keybind

Setting	Default	Description
Config.CarPlay.Keybind	'M'	Key to open/close CarPlay

CarPlay only opens when the player is inside a vehicle. Pressing the keybind outside a vehicle has no effect. The keybind is registered via FiveM's RegisterKeyMapping and can be rebound by players in their FiveM key settings.