Skip to main content

​
Load Tracks

Resolve audio tracks for use with player endpoints. Supports direct URLs, searches, and playlists. 
GET /v4/loadtracks?identifier={identifier}

​
Query Parameters

​
identifier
string
required
The track identifier to load. Can be:
  • Direct URL (YouTube, SoundCloud, etc.)
  • Search query with prefix: ytsearch:query, ytmsearch:query, or scsearch:query
  • Plugin-specific identifiers
Search Prefixes:
  • ytsearch: - Search YouTube
  • ytmsearch: - Search YouTube Music
  • scsearch: - Search SoundCloud
Plugins may add additional search prefixes. Note that disabling source managers will make their search prefixes non-functional.

​
Response

​
loadType
string
required
The type of result returned:
  • track - A single track was loaded
  • playlist - A playlist was loaded
  • search - Search results were returned
  • empty - No matches found
  • error - Loading failed with an error
​
data
varies
required
The result data. Structure varies based on loadType.

​
Load Result Types

​
Track Result

Returned when a single track is successfully loaded.
​
loadType
string
required
Always "track"
​
data
object
required
The loaded track
curl -X GET 'http://localhost:2333/v4/loadtracks?identifier=dQw4w9WgXcQ' \
  -H 'Authorization: youshallnotpass'

​
Playlist Result

Returned when a playlist is successfully loaded.
​
loadType
string
required
Always "playlist"
​
data
object
required
The loaded playlist
curl -X GET 'http://localhost:2333/v4/loadtracks?identifier=https://youtube.com/playlist?list=PLxx...' \
  -H 'Authorization: youshallnotpass'

​
Search Result

Returned when using a search prefix.
​
loadType
string
required
Always "search"
​
data
array
required
Array of track objects matching the search query
curl -X GET 'http://localhost:2333/v4/loadtracks?identifier=ytsearch:rick%20astley' \
  -H 'Authorization: youshallnotpass'

​
Empty Result

Returned when no matches are found for the identifier.
​
loadType
string
required
Always "empty"
​
data
object
required
Empty object
curl -X GET 'http://localhost:2333/v4/loadtracks?identifier=invalididentifier' \
  -H 'Authorization: youshallnotpass'

​
Error Result

Returned when track loading fails with an error.
​
loadType
string
required
Always "error"
​
data
object
required
The exception details
curl -X GET 'http://localhost:2333/v4/loadtracks?identifier=broken' \
  -H 'Authorization: youshallnotpass'

​
Decode Track

Decode a single base64 encoded track into its metadata. 
GET /v4/decodetrack?encodedTrack={base64}

​
Query Parameters

​
encodedTrack
string
required
The base64 encoded track data

​
Response

Returns a track object with decoded information. 
curl -X GET 'http://localhost:2333/v4/decodetrack?encodedTrack=QAAAjQIAJVJpY2sgQXN0bGV5...' \
  -H 'Authorization: youshallnotpass'

​
Decode Tracks (Batch)

Decode multiple base64 encoded tracks in a single request. 
POST /v4/decodetracks

​
Request Body

Array of base64 encoded track strings.
​
tracks
array
required
Array of base64 encoded track data strings

​
Response

Returns an array of track objects with decoded information. 
curl -X POST 'http://localhost:2333/v4/decodetracks' \
  -H 'Authorization: youshallnotpass' \
  -H 'Content-Type: application/json' \
  -d '[
    "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA=="
  ]'

Build docs developers (and LLMs) love

Get started for freeTalk to us