Skip to main content
Code9
Discord

Music Player

YouTube playback with 3D positional audio, parametric equalizer, playlists and HUD widget.

This section

Music Player

The Music app is a full-featured player with YouTube playback, 3D positional audio, a 5-band parametric equalizer, playlists, liked songs, recently played and a floating HUD widget.

Features​

  • YouTube playback — paste any YouTube URL, the script fetches the video info via the YouTube Data API v3 and plays the audio
  • 3D positional audio — sound originates from the vehicle's position; players nearby hear it with distance-based fading
  • Configurable distance — set how far other players can hear via Config.Distance
  • Server-wide volume cap — limit max output via Config.MaxVolume (slider scales accordingly)
  • 5-band parametric equalizer — sub-bass (60Hz), bass (250Hz), mid (1kHz), treble (4kHz), brilliance (12kHz); ±12 dB per band
  • EQ presets — Flat / Bass Boost / Rock / Pop / Vocal / Classical (all editable, all customizable, all extendable)
  • Personal playlists — create, name, cover image (URL), reorder, delete
  • Liked Songs library
  • Recently Played list
  • Search — search any song via YouTube
  • Server-wide public playlist — set defaults in Config.MainMusics
  • Floating HUD widget — currently-playing card on the dashboard

Music Search & API Key​

To enable music search, you must provide a YouTube Data API v3 key in server/config.lua:

lua
ServerConfig.YouTubeAPIKey = "YOUR_API_KEY"

Free key — get one at console.cloud.google.com with YouTube Data API v3 enabled. Each search call counts as 100 units against your daily quota (10,000 units/day default), so a single API key easily supports a busy server.

How It Works​

  1. Open the Music app from the sidebar
  2. Search for a song or paste a YouTube URL
  3. Tap to play — audio starts via the in-game sound system, attached to the vehicle
  4. Players within Config.Distance meters can hear the music
  5. Volume fades linearly with distance from the vehicle
  6. Use the EQ tab to apply a preset or customize the 5 bands
  7. Save songs to Liked or to a Playlist

3D Positional Audio​

Music is broadcast to all clients within range via a server-side network event. Each receiving client plays the audio attached to the vehicle entity, with volume scaled by:

volume = ConfiguredVolume × (1 - distance / Config.Distance)

When the listener leaves the radius, audio stops on their client.

Equalizer​

A 5-band parametric EQ applied client-side. Presets are defined in Config.EQPresets:

lua
Config.EQPresets = {
    flat       = { label = "Flat",       subBass = 0,  bass = 0,  mid = 0,  treble = 0,  brilliance = 0 },
    bass_boost = { label = "Bass Boost", subBass = 6,  bass = 4,  mid = 0,  treble = -1, brilliance = 0 },
    rock       = { label = "Rock",       subBass = 4,  bass = 3,  mid = -1, treble = 3,  brilliance = 4 },
    pop        = { label = "Pop",        subBass = -1, bass = 2,  mid = 4,  treble = 3,  brilliance = 0 },
    vocal      = { label = "Vocal",      subBass = -3, bass = -1, mid = 5,  treble = 3,  brilliance = 1 },
    classical  = { label = "Classical",  subBass = 0,  bass = 0,  mid = -2, treble = 3,  brilliance = 5 },
}
  • Add new presets by appending to the table
  • Remove presets by deleting the entry
  • Each band is in dB, range −12 to +12
  • The label field is what shows in the UI

Server-Wide Public Playlist​

Songs in Config.MainMusics appear under the Home tab for every player. Set defaults the server should always offer:

lua
Config.MainMusics = {
    {url = "https://www.youtube.com/watch?v=VIDEO_ID", title = "Artist - Song"},
    -- add as many as you like
}

Data Persistence​

Per-player music data is stored in MySQL:

ColumnPurpose
liked_songsJSON array of liked songs
playlistJSON array of user playlists
volumePlayer's last volume setting (0-100)

See Database for the full schema.

Music HUD Widget​

A small Now Playing card can be shown on the in-vehicle dashboard widget area. It shows:

  • Album art (YouTube thumbnail)
  • Song title
  • Marquee for long titles
  • Quick play / pause / skip controls

Configuration​

OptionDefaultDescription
Config.Distance30.0How far others can hear (meters)
Config.MaxVolume100Server-wide cap on output volume
Config.MainMusics{}Default playlist shown to all players
Config.EQPresets(six)Equalizer presets
Config.Modules.MusicPlayertrueShow the music player module
ServerConfig.YouTubeAPIKey(empty)YouTube Data API v3 key (server-only)
On this page