Get Players Retrieve all players for a specific session.
GET /v4/sessions/{sessionId}/players
Path Parameters The session ID from the WebSocket ready event
Response Returns an array of player objects.
Array of player objects, each containing: The currently playing track (null if no track is playing)
The player volume (0-1000, where 100 is 100%)
Whether the player is paused
The current player state Unix timestamp in milliseconds
Current track position in milliseconds
Whether connected to voice gateway
Voice server ping in milliseconds (-1 if not connected)
curl -X GET 'http://localhost:2333/v4/sessions/xtaug914v9k5032f/players' \ -H 'Authorization: youshallnotpass'
Get Player Retrieve a specific player by guild ID.
GET /v4/sessions/{sessionId}/players/{guildId}
Path Parameters The session ID from the WebSocket ready event
Response Returns a player object (same structure as Get Players array item).
curl -X GET 'http://localhost:2333/v4/sessions/xtaug914v9k5032f/players/817327181659111454' \ -H 'Authorization: youshallnotpass'
Update Player Update or create a player. Use this to play tracks, control playback, adjust volume, apply filters, and manage voice connections.
PATCH /v4/sessions/{sessionId}/players/{guildId}?noReplace=false
Path Parameters The session ID from the WebSocket ready event
Query Parameters If true, the current track will not be replaced if a new track is provided. Defaults to false.
Request Body All fields are optional. Only include fields you want to update.
The track to play Base64 encoded track data. Use null to stop the current track. Mutually exclusive with identifier.
Track identifier to load (e.g., YouTube video ID or URL). Lavalink will resolve it as a single track. Returns HTTP 400 if it resolves to a playlist or search result. Mutually exclusive with encoded.
Custom user data to attach to the track. This will be returned in track objects.
The track position in milliseconds to seek to
The track end time in milliseconds (must be > 0). Use null to reset.
The player volume (0-1000, where 100 is 100%)
Whether to pause the player
Audio filters to apply. This completely replaces all previously applied filters. Volume multiplier (0.0 to 5.0, where 1.0 is 100%). Values > 1.0 may cause clipping.
Array of equalizer band adjustments Gain multiplier (-0.25 to 1.0)
Eliminates vocals from audio Effect level (0.0 to 1.0)
Mono effect level (0.0 to 1.0)
Changes speed, pitch, and rate Show Timescale Properties
Volume oscillation effect Oscillation frequency (> 0.0)
Effect depth (0.0 < x ≤ 1.0)
Pitch oscillation effect Oscillation frequency (0.0 < x ≤ 14.0)
Effect depth (0.0 < x ≤ 1.0)
Audio panning effect Rotation frequency in Hz (e.g., 0.2 for slow rotation)
Audio distortion effect Show Distortion Properties
Mixes left and right audio channels Show Channel Mix Properties
Left to left factor (0.0 to 1.0)
Left to right factor (0.0 to 1.0)
Right to left factor (0.0 to 1.0)
Right to right factor (0.0 to 1.0)
Filters higher frequencies Smoothing factor (> 1.0). Values ≤ 1.0 disable the filter.
Plugin-specific filters. Keys are plugin names, values are plugin-specific configurations.
Voice connection information from Discord Discord voice token from Voice Server Update event
Discord voice endpoint from Voice Server Update event
Discord voice session ID from Voice State Update event
Discord voice channel ID the bot is connecting to
Deprecated Fields:
encodedTrack (use track.encoded instead)identifier (use track.identifier instead) These fields are mutually exclusive with the new track object and will be removed in a future version. Response Returns the updated player object.
Play Track
Play by Identifier
Pause Player
Set Volume
Apply Equalizer
Apply Timescale
Example Request
Example Response
curl -X PATCH 'http://localhost:2333/v4/sessions/xtaug914v9k5032f/players/817327181659111454' \ -H 'Authorization: youshallnotpass' \ -H 'Content-Type: application/json' \ -d '{ "track": { "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5..." } }'
Destroy Player Destroy a player and disconnect from the voice channel.
DELETE /v4/sessions/{sessionId}/players/{guildId}
Path Parameters The session ID from the WebSocket ready event
Response Returns 204 No Content on success.
curl -X DELETE 'http://localhost:2333/v4/sessions/xtaug914v9k5032f/players/817327181659111454' \ -H 'Authorization: youshallnotpass'
Equalizer Bands Reference The equalizer has 15 bands (0-14) with the following frequencies:
Band Frequency 0 25 Hz 1 40 Hz 2 63 Hz 3 100 Hz 4 160 Hz 5 250 Hz 6 400 Hz 7 630 Hz 8 1000 Hz 9 1600 Hz 10 2500 Hz 11 4000 Hz 12 6300 Hz 13 10000 Hz 14 16000 Hz
Gain values range from -0.25 (muted) to 1.0 (doubled). A value of 0 is the default with no modification.