Skip to content

Entry Music & Lyrics

Entry Music & Lyrics

Every character can have its own entry song. When a character is shown on the selector, their saved track plays through xsound and its lyrics float behind the 3D ped, scrolling in sync with the audio. Players search and pick the song from the settings panel — no file uploads, no manual URLs.

ℹ

The whole feature degrades gracefully. If xsound is not started, search, song selection and the lyrics UI still work — there is simply no audio. Lyrics are pulled from a free, keyless source, so they work even without a YouTube key (only search needs the key).

How it works

  1. Search — the player types a query; the client calls the server, which queries the YouTube Data API v3 with your key and returns up to 8 results (title, channel, thumbnail).
  2. Select — the chosen song is saved to that character's KVP and starts playing immediately via xsound:PlayUrl from the YouTube stream.
  3. Lyrics — the server derives an artist/track from the YouTube title, fetches LRC lyrics, parses the synced timestamps, and hands them back. The client streams the playback position roughly every 250ms so the lyric layer stays in time.
  4. Autoplay memory — each character remembers its song and whether it should auto-play on entry. A player can start/stop it manually or cancel it entirely (that choice is remembered too).

Configuration

settings/options.lua
music = {
    enabled = true,
    youtubeApiKey = 'YOUR_OWN_YOUTUBE_DATA_API_V3_KEY',
    volume = 0.4,          -- 0.0 - 1.0
    -- Optional: a song that plays for EVERY character that hasn't chosen one.
    -- Players can still pick their own or cancel it.
    defaultSong = false,
    -- defaultSong = { id = 'https://youtu.be/kXYiU_JCYtU', title = 'Numb', channel = 'Linkin Park' },
},
Option Meaning
enabled Master switch for the music feature.
youtubeApiKey Your own YouTube Data API v3 key. Used server-side only.
volume Playback volume, 0.0–1.0.
defaultSong A fallback entry song for characters with no chosen track. Accepts a YouTube id or full URL, or false to disable.
⚠

Replace the demo YouTube key. The shipped key is a placeholder and may be rate-limited or revoked at any time. When search returns nothing, a rate-limited demo key is the most common cause — see Troubleshooting.

Lyrics matching

Lyrics are resolved server-side, best-effort, and cached so re-opening a character is instant (up to 400 songs cached):

  • The raw YouTube title is cleaned of noise ((Official Video), [4K], feat. ..., VEVO/Topic tags) and split into artist and track.
  • The track length reported by xsound is sent along so the lyrics source can match by exact signature and return quickly.
  • Titles with diacritics (e.g. Turkish İ, ğ, ş) are ASCII-folded before lookup — this turns a query that would otherwise time out into an instant match.
  • Both synced (timed, karaoke-style) and plain lyrics are supported; synced is preferred. If timed lyrics can't be found, a plain-lyrics fallback provider is tried.
  • Any failure returns nothing and simply hides the lyric layer — the selector never breaks.

If a song has no findable lyrics, the audio still plays; only the floating lyric layer stays hidden.

PreviousShowcase & CameraNext Spawning & Creation