Custom Music API

By default, the Music app searches the built-in music library (roadshop_music_library), which is filled through player submissions and the in-app admin panel. With the Custom Music API you can replace that library entirely and serve songs from your own HTTP server — the same server-to-server pattern used by Custom Upload.

How It Works

┌─────────┐         ┌──────────────┐         ┌──────────────────┐
│  Phone   │         │  FiveM       │         │  Your Music      │
│  NUI     │         │  Server      │         │  API Server      │
└────┬─────┘         └──────┬───────┘         └────────┬─────────┘
     │  1. search "query"   │                          │
     │ ───────────────────> │  2. GET ?search=query    │
     │                      │ ───────────────────────> │
     │                      │                          │  3. Filter songs
     │                      │  4. JSON song array      │
     │                      │ <─────────────────────── │
     │  5. search results   │                          │
     │ <─────────────────── │                          │
     │                      │                          │
     │  6. Player taps a song → plays via YouTube id or direct URL

Server-Side Only

The request runs on the FiveM server via PerformHttpRequest. Your API key never leaves the server — the NUI frontend never sees your endpoint or credentials.

No Frontend Changes

The Music app works exactly as before: search, playlists, and playback are untouched. Only the data source changes.

Unlimited Catalog

Every search hits your server live, so your catalog can be as large as you want — your server does the filtering.

YouTube & Direct Files

Each song can either be a YouTube video id or a direct link to an audio file (mp3/ogg) on your own CDN.

While the Custom Music API is enabled, the built-in music library, song submissions, and the music admin panel are bypassed. Songs already saved in player playlists keep working, since playlists store the song id and type directly.

Configuration

Edit MusicAPI.lua in the resource root (it is escrow_ignore, so you can edit it freely):

MusicAPI.lua

MusicAPI.Enabled = true                                 -- Enable your own music source
MusicAPI.URL = 'https://your-server.com/api/music'      -- Your music search endpoint
MusicAPI.APIKey = 'your-secret-key'                     -- Optional, sent as Authorization header

That’s it — no config.lua changes and no frontend rebuild needed. Restart the resource after changing these values.

Request Format

For every search in the Music app, RoadPhone sends:

GET <MusicAPI.URL>?search=<urlencoded search term>
Authorization: <MusicAPI.APIKey>

The Authorization header is only sent when MusicAPI.APIKey is set.
An empty search parameter is sent when the player opens the search view. Return your newest or featured songs in that case.

Response Format

Your endpoint must respond with HTTP 200 and a JSON array of songs (RoadPhone uses at most the first 50):

[
  {
    "id": "dQw4w9WgXcQ",
    "url_type": "youtube",
    "title": "Never Gonna Give You Up",
    "artist": "Rick Astley",
    "thumbnail": "https://your-cdn.example.com/covers/rick.jpg",
    "length": "3:32"
  },
  {
    "id": "https://your-cdn.example.com/songs/track.mp3",
    "url_type": "direct",
    "title": "My Custom Track",
    "artist": "Server DJ",
    "thumbnail": "https://your-cdn.example.com/covers/track.jpg",
    "length": "2:45"
  }
]

Wrapping the array in an object is also supported: { "songs": [ ... ] }

Song Fields

Field	Required	Description
`id`	✅	YouTube video id when `url_type` is `youtube`, or a full `https://` URL to an audio file when `url_type` is `direct`
`title`	✅	Song title shown in the app
`artist`	✅	Artist name shown in the app
`url_type`	❌	`"youtube"` or `"direct"` — defaults to `"youtube"`
`thumbnail`	❌	Cover image URL
`length`	❌	Song length as `mm:ss` — defaults to `0:00`

Songs without an id or title are skipped. On any error (non-200 status, invalid JSON), the app shows an empty result list and a warning is printed to the FiveM server console.

Example: Building Your Own Endpoint

A minimal music API using Node.js and Express:

const express = require('express')
const app = express()

const API_KEY = 'your-secret-key'

const LIBRARY = [
  {
    id: 'dQw4w9WgXcQ',
    url_type: 'youtube',
    title: 'Never Gonna Give You Up',
    artist: 'Rick Astley',
    thumbnail: 'https://your-cdn.example.com/covers/rick.jpg',
    length: '3:32',
  },
  {
    id: 'https://your-cdn.example.com/songs/track.mp3',
    url_type: 'direct',
    title: 'My Custom Track',
    artist: 'Server DJ',
    thumbnail: 'https://your-cdn.example.com/covers/track.jpg',
    length: '2:45',
  },
]

app.get('/api/music', (req, res) => {
  // Validate API key (skip this block if you don't use one)
  if (req.headers.authorization !== API_KEY) {
    return res.status(401).json({ error: 'Unauthorized' })
  }

  const search = (req.query.search || '').toLowerCase()

  // Empty search: return newest/featured songs
  if (!search) {
    return res.json(LIBRARY.slice(0, 50))
  }

  const results = LIBRARY.filter(
    (song) =>
      song.title.toLowerCase().includes(search) ||
      song.artist.toLowerCase().includes(search)
  )

  res.json(results.slice(0, 50))
})

app.listen(3000)

In production, serve the library from a database, add rate limiting, and cache popular queries. Direct audio files must be publicly reachable from every player’s game client (they are streamed via xSound/mx-surround).

Troubleshooting

Search always shows an empty list

Check the FiveM server console for [RoadPhone] MusicAPI ... warnings
Verify your endpoint is reachable from the FiveM server (try curl on the machine)
Confirm the response is a JSON array (or { "songs": [...] }) with id and title on every song
Make sure the API key in MusicAPI.lua matches what your endpoint expects

Songs appear but won't play

For url_type: "youtube", id must be the plain video id (e.g. dQw4w9WgXcQ), not a full URL
For url_type: "direct", id must be a full https:// URL to an audio file that players’ game clients can reach
Test a direct URL in your browser — it should download/stream the audio file without a login

The built-in library still shows up

Ensure MusicAPI.Enabled = true in MusicAPI.lua (resource root, next to API.lua)
Restart the resource completely after changing the file
Check that MusicAPI.lua is listed in fxmanifest.lua under server_scripts

Home

RoadPhone-Pro

RoadPhone

RoadPad

RoadCarPlay

RoadPods

RoadBackup

Custom Music API

Custom Music API

How It Works

Server-Side Only

No Frontend Changes

Unlimited Catalog

YouTube & Direct Files

Configuration

Request Format

Response Format

Song Fields

Example: Building Your Own Endpoint

Troubleshooting

​Custom Music API

​How It Works

Server-Side Only

No Frontend Changes

Unlimited Catalog

YouTube & Direct Files

​Configuration

​Request Format

​Response Format

​Song Fields

​Example: Building Your Own Endpoint

​Troubleshooting

Custom Music API

How It Works

Configuration

Request Format

Response Format

Song Fields

Example: Building Your Own Endpoint

Troubleshooting