diff --git a/docs/api/index.md b/docs/api/index.md index 603560215..49a142ca3 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -4,125 +4,11 @@ description: Lavalink API Implementation guidelines # API Implementation guidelines -How to write your own client. - ## Required capabilities of your Discord library * You must be able to send messages via a shard's gateway connection. * You must be able to intercept voice server & voice state updates from the gateway on your shard connection. -## Insomnia Collection - -You can find an [Insomnia](https://insomnia.rest/) collection in the [here](Insomnia.json) which contains all the endpoints and their respective payloads. - -## Significant changes - -### v3.7.0 -> v4.0.0 - -* removed all non version `/v3` or `/v4` endpoints (except `/version`). -* `/v4/websocket` does not accept any messages anymore. -* `v4` uses the `sessionId` instead of the `resumeKey` for resuming. -* `v4` now returns the tracks `artworkUrl` and `isrc` if the source supports it. -* removal of deprecated json fields like `track`. -* addition of `artworkUrl` and `isrc` fields to the [Track Info](#track-info) object. -* addition of the full [Track](#track) object in [TrackStartEvent](#trackstartevent), [TrackEndEvent](#trackendevent), [TrackExceptionEvent](#trackexceptionevent) and [TrackStuckEvent](#trackstuckevent). -* updated capitalization of [Track End Reason](#track-end-reason) and [Severity](#severity) -* reworked [Load Result](#track-loading-result) object - -
-v4.0.0 Migration Guide - -All websocket ops are removed as of `v4.0.0` and replaced with the following endpoints and json fields: - -* `play` -> [Update Player Endpoint](#update-player) `encodedTrack` or `identifier` field -* `stop` -> [Update Player Endpoint](#update-player) `encodedTrack` field with `null` -* `pause` -> [Update Player Endpoint](#update-player) `pause` field -* `seek` -> [Update Player Endpoint](#update-player) `position` field -* `volume` -> [Update Player Endpoint](#update-player) `volume` field -* `filters` -> [Update Player Endpoint](#update-player) `filters` field -* `destroy` -> [Destroy Player Endpoint](#destroy-player) -* `voiceUpdate` -> [Update Player Endpoint](#update-player) `voice` field -* `configureResuming` -> [Update Session Endpoint](#update-session) - -
- -
-Older versions - -### v3.6.0 -> v3.7.0 - -* Moved HTTP endpoints under the new `/v3` path with `/version` as the only exception. -* Deprecation of the old HTTP paths. -* WebSocket handshakes should be done with `/v3/websocket`. Handshakes on `/` are now deprecated. -* Deprecation of all client-to-server messages (play, stop, pause, seek, volume, filters, destroy, voiceUpdate & configureResuming). -* Addition of REST endpoints intended to replace client requests. -* Addition of new WebSocket dispatch [Ready OP](#ready-op) to get `sessionId` and `resume` status. -* Addition of new [Session](#update-session)/[Player](#get-player) REST API. -* Addition of `/v3/info`, replaces `/plugins`. -* Deprecation of `Track.track` in existing endpoints. Use `Track.encoded` instead. -* Deprecation of `TrackXEvent.track` in WebSocket dispatches. Use `TrackXEvent.encodedTrack` instead. -* Player now has a `state` field which contains the same structure as returned by the `playerUpdate` OP. - -
-v3.7.0 Migration Guide - -All websocket ops are deprecated as of `v3.7.0` and replaced with the following endpoints and json fields: - -* `play` -> [Update Player Endpoint](#update-player) `track` or `identifier` field -* `stop` -> [Update Player Endpoint](#update-player) `track` field with `null` -* `pause` -> [Update Player Endpoint](#update-player) `pause` field -* `seek` -> [Update Player Endpoint](#update-player) `position` field -* `volume` -> [Update Player Endpoint](#update-player) `volume` field -* `filters` -> [Update Player Endpoint](#update-player) `filters` field -* `destroy` -> [Destroy Player Endpoint](#destroy-player) -* `voiceUpdate` -> [Update Player Endpoint](#update-player) `voice` field -* `configureResuming` -> [Update Session Endpoint](#update-session) - -
- -### v3.3 -> v3.4 - -* Added filters -* The `error` string on the `TrackExceptionEvent` has been deprecated and replaced by - the [Exception](#exception-object) object following the same structure as the `LOAD_FAILED` error on [`/loadtracks`](#track-loading). -* Added the `connected` boolean to player updates. -* Added source name to REST api track objects -* Clients are now requested to make their name known during handshake - -### v2.0 -> v3.0 - -* The response of `/loadtracks` has been completely changed (again since the initial v3.0 pre-release). -* Lavalink v3.0 now reports its version as a handshake response header. - `Lavalink-Major-Version` has a value of `3` for v3.0 only. It's missing for any older version. - -### v1.3 -> v2.0 - -With the release of v2.0 many unnecessary ops were removed: - -* `connect` -* `disconnect` -* `validationRes` -* `isConnectedRes` -* `validationReq` -* `isConnectedReq` -* `sendWS` - -With Lavalink 1.x the server had the responsibility of handling Discord `VOICE_SERVER_UPDATE`s as well as its own internal ratelimiting. -This remote handling makes things unnecessarily complicated and adds a lot og points where things could go wrong. -One problem we noticed is that since JDA is unaware of ratelimits on the bot's gateway connection, it would keep adding -to the ratelimit queue to the gateway. With this update this is now the responsibility of the Lavalink client or the -Discord client. - -A voice connection is now initiated by forwarding a `voiceUpdate` (VOICE_SERVER_UPDATE) to the server. When you want to -disconnect or move to a different voice channel you must send Discord a new VOICE_STATE_UPDATE. If you want to move your -connection to a new Lavalink server you can simply send the VOICE_SERVER_UPDATE to the new node, and the other node -will be disconnected by Discord. - -Depending on your Discord library, it may be possible to take advantage of the library's OP 4 handling. For instance, -the JDA client takes advantage of JDA's websocket write thread to send OP 4s for connects, disconnects and reconnects. - -
- ## Protocol ### Reference diff --git a/docs/api/rest.md b/docs/api/rest.md index 65dd4d7de..e2c5ecb2d 100644 --- a/docs/api/rest.md +++ b/docs/api/rest.md @@ -13,7 +13,11 @@ Authorization: youshallnotpass Routes are prefixed with `/v3` as of `v3.7.0` and `/v4` as of `v4.0.0`. Routes without an API prefix were removed in v4 (except `/version`). -#### Error Responses +## Insomnia Collection + +You can find an [Insomnia](https://insomnia.rest/) collection in the [here](Insomnia.json) which contains all the endpoints and their respective payloads. + +## Error Responses When Lavalink encounters an error, it will respond with a JSON object containing more information about the error. Include the `trace=true` query param to also receive the full stack trace. @@ -42,27 +46,12 @@ When Lavalink encounters an error, it will respond with a JSON object containing -#### Get Players - -Returns a list of players in this specific session. - -``` -GET /v4/sessions/{sessionId}/players -``` -##### Player +## Track API -| Field | Type | Description | -|---------|--------------------------------------------------|-------------------------------------------------------| -| guildId | string | The guild id of the player | -| track | ?[Track](#track) object | The currently playing track | -| volume | int | The volume of the player, range 0-1000, in percentage | -| paused | bool | Whether the player is paused | -| state | [Player State](websocket.md#player-state) object | The state of the player | -| voice | [Voice State](#voice-state) object | The voice state of the player | -| filters | [Filters](#filters) object | The filters used by the player | +### Common Types ### {: #track-api-types } -##### Track +#### Track | Field | Type | Description | |------------|----------------------------------|-----------------------------------------| @@ -70,7 +59,7 @@ GET /v4/sessions/{sessionId}/players | info | [Track Info](#track-info) object | Info about the track | | pluginInfo | object | Addition track info provided by plugins | -##### Track Info +#### Track Info | Field | Type | Description | |------------|---------|---------------------------------------------------------------------------------------| @@ -86,186 +75,230 @@ GET /v4/sessions/{sessionId}/players | isrc | ?string | The track [ISRC](https://en.wikipedia.org/wiki/International_Standard_Recording_Code) | | sourceName | string | The track source name | -##### Voice State +#### Playlist Info -| Field | Type | Description | -|-----------|--------|---------------------------------------------------| -| token | string | The Discord voice token to authenticate with | -| endpoint | string | The Discord voice endpoint to connect to | -| sessionId | string | The Discord voice session id to authenticate with | +| Field | Type | Description | +|---------------|--------|-----------------------------------------------------------------| +| name | string | The name of the playlist | +| selectedTrack | int | The selected track of the playlist (-1 if no track is selected) | -`token`, `endpoint`, and `sessionId` are the 3 required values for connecting to one of Discord's voice servers. -`sessionId` is provided by the Voice State Update event sent by Discord, whereas the `endpoint` and `token` are provided -with the Voice Server Update. Please refer to https://discord.com/developers/docs/topics/gateway-events#voice +--- + +### Track Loading + +This endpoint is used to resolve audio tracks for use with the [Update Player](#update-player) endpoint. + + +!!! note + + Lavalink supports searching via YouTube, YouTube Music, and Soundcloud. To search, you must prefix your identifier with `ytsearch:`, `ytmsearch:` or `scsearch:` respectively. + + When a search prefix is used, the returned `loadType` will be `search`. Note that disabling the respective source managers renders these search prefixes useless. + + Plugins may also implement prefixes to allow for more search engines to be utilised. + + +``` +GET /v4/loadtracks?identifier=dQw4w9WgXcQ +``` + +Response: + +#### Track Loading Result + +| Field | Type | Description | +|----------|-------------------------------------|------------------------| +| loadType | [LoadResultType](#load-result-type) | The type of the result | +| data | [LoadResultData](#load-result-data) | The data of the result | + +#### Load Result Type + +| Load Result Type | Description | +|------------------|-----------------------------------------------| +| `track` | A track has been loaded | +| `playlist` | A playlist has been loaded | +| `search` | A search result has been loaded | +| `empty` | There has been no matches for your identifier | +| `error` | Loading has failed with an error | + +#### Load Result Data + +##### Track Result Data + +[Track](#track) object with the loaded track.
Example Payload ```yaml -[ - { - "guildId": "...", - "track": { - "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", - "info": { - "identifier": "dQw4w9WgXcQ", - "isSeekable": true, - "author": "RickAstleyVEVO", - "length": 212000, - "isStream": false, - "position": 60000, - "title": "Rick Astley - Never Gonna Give You Up", - "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", - "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", - "isrc": null, - "sourceName": "youtube" - }, - "pluginInfo": {} - }, - "volume": 100, - "paused": false, - "state": { - "time": 1500467109, - "position": 60000, - "connected": true, - "ping": 50 - }, - "voice": { - "token": "...", - "endpoint": "...", - "sessionId": "..." - }, - "filters": { ... } - }, - ... -] +{ + "loadType": "track", + "data": { + "encoded": "...", + "info": { ... }, + "pluginInfo": { ... } + } +} ```
---- +##### Playlist Result Data -#### Get Player +| Field | Type | Description | +|------------|---------------------------------------|--------------------------------------------| +| info | [PlaylistInfo](#playlist-info) object | The info of the playlist | +| pluginInfo | Object | Addition playlist info provided by plugins | +| tracks | array of [Track](#track) objects | The tracks of the playlist | -Returns the player for this guild in this session. +
+Example Payload -``` -GET /v4/sessions/{sessionId}/players/{guildId} +```yaml +{ + "loadType": "playlist", + "data": { + "info": { ... }, + "pluginInfo": { ... }, + "tracks": [ ... ] + } +} ``` -Response: +
-[Player](#Player) object +##### Search Result Data + +Array of [Track](#track) objects from the search result.
Example Payload ```yaml { - "guildId": "...", - "track": { - "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", - "info": { - "identifier": "dQw4w9WgXcQ", - "isSeekable": true, - "author": "RickAstleyVEVO", - "length": 212000, - "isStream": false, - "position": 60000, - "title": "Rick Astley - Never Gonna Give You Up", - "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", - "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", - "isrc": null, - "sourceName": "youtube" - } - }, - "volume": 100, - "paused": false, - "state": { - "time": 1500467109, - "position": 60000, - "connected": true, - "ping": 50 - }, - "voice": { - "token": "...", - "endpoint": "...", - "sessionId": "..." - }, - "filters": { ... } + "loadType": "search", + "data": [ + { + "encoded": "...", + "info": { ... }, + "pluginInfo": { ... } + }, + ... + ] } ```
---- +##### Empty Result Data -#### Update Player +Empty object. -Updates or creates the player for this guild if it doesn't already exist. +
+Example Payload +```yaml +{ + "loadType": "empty", + "data": {} +} ``` -PATCH /v4/sessions/{sessionId}/players/{guildId}?noReplace=true + +
+ +##### Error Result Data + +[Exception](websocket.md#exception-object) object with the error. + +
+Example Payload + +```yaml +{ + "loadType": "error", + "data": { + "message": "Something went wrong", + "severity": "fault", + "cause": "..." + } +} ``` -Query Params: +
-| Field | Type | Description | -|------------|------|------------------------------------------------------------------------------| -| noReplace? | bool | Whether to replace the current track with the new track. Defaults to `false` | +--- -Request: +### Track Decoding -| Field | Type | Description | -|-----------------|------------------------------------|-----------------------------------------------------------------------------------------------| -| encodedTrack? * | ?string | The base64 encoded track to play. `null` stops the current track | -| identifier? * | string | The identifier of the track to play | -| position? | int | The track position in milliseconds | -| endTime? | ?int | The track end time in milliseconds (must be > 0). `null` resets this if it was set previously | -| volume? | int | The player volume, in percentage, from 0 to 1000 | -| paused? | bool | Whether the player is paused | -| filters? | [Filters](#filters) object | The new filters to apply. This will override all previously applied filters | -| voice? | [Voice State](#voice-state) object | Information required for connecting to Discord | +Decode a single track into its info, where `BASE64` is the encoded base64 data. -> **Note** -> - \* `encodedTrack` and `identifier` are mutually exclusive. -> - `sessionId` in the path should be the value from the [ready op](websocket.md#ready-op). +``` +GET /v4/decodetrack?encodedTrack=BASE64 +``` -When `identifier` is used, Lavalink will try to resolve the identifier as a single track. An HTTP `400` error is returned when resolving a playlist, search result, or no tracks. +Response: + +[Track](#track) object
Example Payload ```yaml { - "encodedTrack": "...", - "identifier": "...", - "endTime": 0, - "volume": 100, - "position": 32400, - "paused": false, - "filters": { ... }, - "voice": { - "token": "...", - "endpoint": "...", - "sessionId": "..." - } + "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", + "info": { + "identifier": "dQw4w9WgXcQ", + "isSeekable": true, + "author": "RickAstleyVEVO", + "length": 212000, + "isStream": false, + "position": 0, + "title": "Rick Astley - Never Gonna Give You Up", + "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", + "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", + "isrc": null, + "sourceName": "youtube" + }, + "pluginInfo": {} } ```
+--- + +Decodes multiple tracks into their info + +``` +POST /v4/decodetracks +``` + +Request: + +Array of track data strings + +
+Example Payload + +```yaml +[ + "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", + ... +] +``` + +
+ Response: -[Player](#Player) object +Array of [Track](#track) objects
Example Payload ```yaml -{ - "guildId": "...", - "track": { +[ + { "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", "info": { "identifier": "dQw4w9WgXcQ", @@ -273,35 +306,52 @@ Response: "author": "RickAstleyVEVO", "length": 212000, "isStream": false, - "position": 60000, + "position": 0, "title": "Rick Astley - Never Gonna Give You Up", "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "isrc": null, "sourceName": "youtube" - } - }, - "volume": 100, - "paused": false, - "state": { - "time": 1500467109, - "position": 60000, - "connected": true, - "ping": 50 - }, - "voice": { - "token": "...", - "endpoint": "...", - "sessionId": "..." + }, + "pluginInfo": {} }, - "filters": { ... } -} + ... +] ```
--- +## Player API + +### Common Types ### {: #player-api-types } + +#### Player + +| Field | Type | Description | +|---------|--------------------------------------------------|-------------------------------------------------------| +| guildId | string | The guild id of the player | +| track | ?[Track](#track) object | The currently playing track | +| volume | int | The volume of the player, range 0-1000, in percentage | +| paused | bool | Whether the player is paused | +| state | [Player State](websocket.md#player-state) object | The state of the player | +| voice | [Voice State](#voice-state) object | The voice state of the player | +| filters | [Filters](#filters) object | The filters used by the player | + +#### Voice State + +| Field | Type | Description | +|-----------|--------|---------------------------------------------------| +| token | string | The Discord voice token to authenticate with | +| endpoint | string | The Discord voice endpoint to connect to | +| sessionId | string | The Discord voice session id to authenticate with | + +`token`, `endpoint`, and `sessionId` are the 3 required values for connecting to one of Discord's voice servers. +`sessionId` is provided by the Voice State Update event sent by Discord, whereas the `endpoint` and `token` are provided +with the Voice Server Update. Please refer to https://discord.com/developers/docs/topics/gateway-events#voice + + #### Filters Filters are used in above requests and look like this @@ -439,7 +489,7 @@ Any smoothing values equal to or less than 1.0 will disable the filter. |------------|-------|--------------------------------| | smoothing? | float | The smoothing factor (1.0 < x) | -##### Plugin Filter +##### Plugin Filters Plugins can add their own filters. The key is the name of the plugin, and the value is the configuration for that plugin. The configuration is plugin specific. See [Plugins](plugins.md) for more plugin information. @@ -508,202 +558,211 @@ Plugins can add their own filters. The key is the name of the plugin, and the va --- -#### Destroy Player +### Get Players -Destroys the player for this guild in this session. - -``` -DELETE /v4/sessions/{sessionId}/players/{guildId} -``` - -Response: - -204 - No Content - ---- - -#### Update Session - -Updates the session with the resuming state and timeout. +Returns a list of players in this specific session. ``` -PATCH /v4/sessions/{sessionId} -``` - -Request: - -| Field | Type | Description | -|-----------|------|-----------------------------------------------------| -| resuming? | bool | Whether resuming is enabled for this session or not | -| timeout? | int | The timeout in seconds (default is 60s) | - -
-Example Payload - -```json -{ - "resuming": false, - "timeout": 0 -} +GET /v4/sessions/{sessionId}/players ``` -
- -Response: - -| Field | Type | Description | -|----------|------|-----------------------------------------------------| -| resuming | bool | Whether resuming is enabled for this session or not | -| timeout | int | The timeout in seconds (default is 60s) | -
Example Payload -```json -{ - "resuming": true, - "timeout": 60 -} +```yaml +[ + { + "guildId": "...", + "track": { + "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", + "info": { + "identifier": "dQw4w9WgXcQ", + "isSeekable": true, + "author": "RickAstleyVEVO", + "length": 212000, + "isStream": false, + "position": 60000, + "title": "Rick Astley - Never Gonna Give You Up", + "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", + "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", + "isrc": null, + "sourceName": "youtube" + }, + "pluginInfo": {} + }, + "volume": 100, + "paused": false, + "state": { + "time": 1500467109, + "position": 60000, + "connected": true, + "ping": 50 + }, + "voice": { + "token": "...", + "endpoint": "...", + "sessionId": "..." + }, + "filters": { ... } + }, + ... +] ```
--- -#### Track Loading +### Get Player -This endpoint is used to resolve audio tracks for use with the [Update Player](#update-player) endpoint. +Returns the player for this guild in this session. ``` -GET /v4/loadtracks?identifier=dQw4w9WgXcQ +GET /v4/sessions/{sessionId}/players/{guildId} ``` Response: -##### Track Loading Result - -| Field | Type | Description | -|----------|-------------------------------------|------------------------| -| loadType | [LoadResultType](#load-result-type) | The type of the result | -| data | [LoadResultData](#load-result-data) | The data of the result | - -##### Load Result Type - -| Load Result Type | Description | -|------------------|-----------------------------------------------| -| `track` | A track has been loaded | -| `playlist` | A playlist has been loaded | -| `search` | A search result has been loaded | -| `empty` | There has been no matches for your identifier | -| `error` | Loading has failed with an error | - -##### Load Result Data - -###### Load Result Data - Track - -[Track](#track) object with the loaded track. - -
-Example Payload - -```yaml -{ - "loadType": "track", - "data": { - "encoded": "...", - "info": { ... }, - "pluginInfo": { ... } - } -} -``` - -
- -###### Load Result Data - Playlist - -| Field | Type | Description | -|------------|---------------------------------------|--------------------------------------------| -| info | [PlaylistInfo](#playlist-info) object | The info of the playlist | -| pluginInfo | Object | Addition playlist info provided by plugins | -| tracks | array of [Track](#track) objects | The tracks of the playlist | - -###### Playlist Info - -| Field | Type | Description | -|---------------|--------|-----------------------------------------------------------------| -| name | string | The name of the playlist | -| selectedTrack | int | The selected track of the playlist (-1 if no track is selected) | +[Player](#Player) object
Example Payload ```yaml { - "loadType": "playlist", - "data": { - "info": { ... }, - "pluginInfo": { ... }, - "tracks": [ ... ] - } + "guildId": "...", + "track": { + "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", + "info": { + "identifier": "dQw4w9WgXcQ", + "isSeekable": true, + "author": "RickAstleyVEVO", + "length": 212000, + "isStream": false, + "position": 60000, + "title": "Rick Astley - Never Gonna Give You Up", + "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", + "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", + "isrc": null, + "sourceName": "youtube" + } + }, + "volume": 100, + "paused": false, + "state": { + "time": 1500467109, + "position": 60000, + "connected": true, + "ping": 50 + }, + "voice": { + "token": "...", + "endpoint": "...", + "sessionId": "..." + }, + "filters": { ... } } ```
-###### Load Result Data - Search +--- -Array of [Track](#track) objects from the search result. +### Update Player -
-Example Payload +Updates or creates the player for this guild if it doesn't already exist. -```yaml -{ - "loadType": "search", - "data": [ - { - "encoded": "...", - "info": { ... }, - "pluginInfo": { ... } - }, - ... - ] -} +``` +PATCH /v4/sessions/{sessionId}/players/{guildId}?noReplace=true ``` -
+Query Params: -###### Load Result Data - Empty +| Field | Type | Description | +|------------|------|------------------------------------------------------------------------------| +| noReplace? | bool | Whether to replace the current track with the new track. Defaults to `false` | -Empty object. +Request: + +| Field | Type | Description | +|-----------------|------------------------------------|-----------------------------------------------------------------------------------------------| +| encodedTrack? * | ?string | The base64 encoded track to play. `null` stops the current track | +| identifier? * | string | The identifier of the track to play | +| position? | int | The track position in milliseconds | +| endTime? | ?int | The track end time in milliseconds (must be > 0). `null` resets this if it was set previously | +| volume? | int | The player volume, in percentage, from 0 to 1000 | +| paused? | bool | Whether the player is paused | +| filters? | [Filters](#filters) object | The new filters to apply. This will override all previously applied filters | +| voice? | [Voice State](#voice-state) object | Information required for connecting to Discord | + +> **Note** +> - \* `encodedTrack` and `identifier` are mutually exclusive. +> - `sessionId` in the path should be the value from the [ready op](websocket.md#ready-op). + +When `identifier` is used, Lavalink will try to resolve the identifier as a single track. An HTTP `400` error is returned when resolving a playlist, search result, or no tracks.
Example Payload ```yaml { - "loadType": "empty", - "data": {} + "encodedTrack": "...", + "identifier": "...", + "endTime": 0, + "volume": 100, + "position": 32400, + "paused": false, + "filters": { ... }, + "voice": { + "token": "...", + "endpoint": "...", + "sessionId": "..." + } } ```
-###### Load Result Data - Error +Response: -[Exception](websocket.md#exception-object) object with the error. +[Player](#Player) object
Example Payload ```yaml { - "loadType": "error", - "data": { - "message": "Something went wrong", - "severity": "fault", - "cause": "..." - } + "guildId": "...", + "track": { + "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", + "info": { + "identifier": "dQw4w9WgXcQ", + "isSeekable": true, + "author": "RickAstleyVEVO", + "length": 212000, + "isStream": false, + "position": 60000, + "title": "Rick Astley - Never Gonna Give You Up", + "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", + "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", + "isrc": null, + "sourceName": "youtube" + } + }, + "volume": 100, + "paused": false, + "state": { + "time": 1500467109, + "position": 60000, + "connected": true, + "ping": 50 + }, + "voice": { + "token": "...", + "endpoint": "...", + "sessionId": "..." + }, + "filters": { ... } } ``` @@ -711,110 +770,71 @@ Empty object. --- -#### Track Searching - -Lavalink supports searching via YouTube, YouTube Music, and Soundcloud. To search, you must prefix your identifier with `ytsearch:`, `ytmsearch:` or `scsearch:` respectively. - -When a search prefix is used, the returned `loadType` will be `search`. Note that disabling the respective source managers renders these search prefixes useless. Plugins may also implement prefixes to allow for more search engines to be utilised. - ---- - -#### Track Decoding +### Destroy Player -Decode a single track into its info, where `BASE64` is the encoded base64 data. +Destroys the player for this guild in this session. ``` -GET /v4/decodetrack?encodedTrack=BASE64 +DELETE /v4/sessions/{sessionId}/players/{guildId} ``` Response: -[Track](#track) object - -
-Example Payload +204 - No Content -```yaml -{ - "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", - "info": { - "identifier": "dQw4w9WgXcQ", - "isSeekable": true, - "author": "RickAstleyVEVO", - "length": 212000, - "isStream": false, - "position": 0, - "title": "Rick Astley - Never Gonna Give You Up", - "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", - "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", - "isrc": null, - "sourceName": "youtube" - }, - "pluginInfo": {} -} -``` +--- -
+## Session API ---- +### Update Session -Decodes multiple tracks into their info +Updates the session with the resuming state and timeout. ``` -POST /v4/decodetracks +PATCH /v4/sessions/{sessionId} ``` Request: -Array of track data strings +| Field | Type | Description | +|-----------|------|-----------------------------------------------------| +| resuming? | bool | Whether resuming is enabled for this session or not | +| timeout? | int | The timeout in seconds (default is 60s) |
Example Payload -```yaml -[ - "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", - ... -] +```json +{ + "resuming": false, + "timeout": 0 +} ```
Response: -Array of [Track](#track) objects +| Field | Type | Description | +|----------|------|-----------------------------------------------------| +| resuming | bool | Whether resuming is enabled for this session or not | +| timeout | int | The timeout in seconds (default is 60s) |
Example Payload -```yaml -[ - { - "encoded": "QAAAjQIAJVJpY2sgQXN0bGV5IC0gTmV2ZXIgR29ubmEgR2l2ZSBZb3UgVXAADlJpY2tBc3RsZXlWRVZPAAAAAAADPCAAC2RRdzR3OVdnWGNRAAEAK2h0dHBzOi8vd3d3LnlvdXR1YmUuY29tL3dhdGNoP3Y9ZFF3NHc5V2dYY1EAB3lvdXR1YmUAAAAAAAAAAA==", - "info": { - "identifier": "dQw4w9WgXcQ", - "isSeekable": true, - "author": "RickAstleyVEVO", - "length": 212000, - "isStream": false, - "position": 0, - "title": "Rick Astley - Never Gonna Give You Up", - "uri": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", - "artworkUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", - "isrc": null, - "sourceName": "youtube" - }, - "pluginInfo": {} - }, - ... -] +```json +{ + "resuming": true, + "timeout": 60 +} ```
--- -#### Get Lavalink info +## Get Lavalink info Request Lavalink information. @@ -824,7 +844,7 @@ GET /v4/info Response: -##### Info Response +### Info Response | Field | Type | Description | |----------------|-------------------------------------------|-----------------------------------------------------------------| @@ -837,7 +857,7 @@ Response: | filters | array of strings | The enabled filters for this server | | plugins | array of [Plugin](#plugin-object) objects | The enabled plugins for this server | -##### Version Object +#### Version Object Parsed [Semantic Versioning 2.0.0](https://semver.org/) @@ -850,7 +870,7 @@ Parsed [Semantic Versioning 2.0.0](https://semver.org/) | preRelease | ?string | The pre-release version according to semver as a `.` separated list of identifiers | | build | ?string | The build metadata according to semver as a `.` separated list of identifiers | -##### Git Object +#### Git Object | Field | Type | Description | |------------|--------|----------------------------------------------------------------| @@ -858,7 +878,7 @@ Parsed [Semantic Versioning 2.0.0](https://semver.org/) | commit | string | The commit this Lavalink server was built on | | commitTime | int | The millisecond unix timestamp for when the commit was created | -##### Plugin Object +#### Plugin Object | Field | Type | Description | |---------|--------|---------------------------| @@ -913,7 +933,23 @@ Parsed [Semantic Versioning 2.0.0](https://semver.org/) --- -#### Get Lavalink stats +## Get Lavalink version + +Request Lavalink version. + +``` +GET /version +``` + +Response: + +``` +4.0.0 +``` + +--- + +## Get Lavalink stats Request Lavalink statistics. @@ -952,40 +988,14 @@ Response: --- -#### Get Lavalink version - -Request Lavalink version. - -``` -GET /version -``` - -Response: - -``` -4.0.0 -``` - ---- - -### RoutePlanner API +## RoutePlanner API Additionally, there are a few REST endpoints for the ip rotation extension. -#### Get RoutePlanner status -``` -GET /v4/routeplanner/status -``` - -Response: - -| Field | Type | Description | -|---------|---------------------------------------------|-----------------------------------------------------------------------| -| class | ?[Route Planner Type](#route-planner-types) | The name of the RoutePlanner implementation being used by this server | -| details | ?[Details](#details-object) object | The status details of the RoutePlanner | +### Common Types ### {: #route-planner-api-types } -##### Route Planner Types +#### Route Planner Types | Route Planner Type | Description | |------------------------------|-----------------------------------------------------------------------------------------------------------------------------| @@ -994,7 +1004,7 @@ Response: | `RotatingNanoIpRoutePlanner` | IP address used is switched on clock update, rotates to a different /64 block on ban. Use with at least 2x /64 IPv6 blocks. | | `BalancingIpRoutePlanner` | IP address used is selected at random per request. Recommended for larger IP blocks. | -##### Details Object +#### Details Object | Field | Type | Description | Valid Types | |---------------------|-------------------------------------------------------|---------------------------------------------------------------------------------------|----------------------------------------------------| @@ -1006,21 +1016,21 @@ Response: | currentAddressIndex | string | The current offset in the ip block | `NanoIpRoutePlanner`, `RotatingNanoIpRoutePlanner` | | blockIndex | string | The information in which /64 block ips are chosen. This number increases on each ban. | `RotatingNanoIpRoutePlanner` | -##### IP Block Object +#### IP Block Object | Field | Type | Description | |-------|---------------------------------|--------------------------| | type | [IP Block Type](#ip-block-type) | The type of the ip block | | size | string | The size of the ip block | -##### IP Block Type +#### IP Block Type | IP Block Type | Description | |----------------|---------------------| | `Inet4Address` | The ipv4 block type | | `Inet6Address` | The ipv6 block type | -##### Failing Address Object +#### Failing Address Object | Field | Type | Description | |------------------|--------|----------------------------------------------------------| @@ -1028,6 +1038,21 @@ Response: | failingTimestamp | int | The timestamp when the address failed | | failingTime | string | The timestamp when the address failed as a pretty string | +--- + +### Get RoutePlanner status + +``` +GET /v4/routeplanner/status +``` + +Response: + +| Field | Type | Description | +|---------|---------------------------------------------|-----------------------------------------------------------------------| +| class | ?[Route Planner Type](#route-planner-types) | The name of the RoutePlanner implementation being used by this server | +| details | ?[Details](#details-object) object | The status details of the RoutePlanner | +
Example Payload @@ -1056,7 +1081,7 @@ Response: --- -#### Unmark a failed address +### Unmark a failed address ``` POST /v4/routeplanner/free/address @@ -1085,7 +1110,7 @@ Response: --- -#### Unmark all failed address +### Unmark all failed address ``` POST /v4/routeplanner/free/all diff --git a/docs/changelog/index.md b/docs/changelog/index.md new file mode 100644 index 000000000..e86584f59 --- /dev/null +++ b/docs/changelog/index.md @@ -0,0 +1,119 @@ +--- +description: Lavalink changelog. +--- + +# Changelog + +Each release usually includes various fixes and improvements. +The most noteworthy of these, as well as any features and breaking changes, are listed here. + +## Significant changes + +
+v3.7.0 -> v4.0.0 + +* removed all non version `/v3` or `/v4` endpoints (except `/version`). +* `/v4/websocket` does not accept any messages anymore. +* `v4` uses the `sessionId` instead of the `resumeKey` for resuming. +* `v4` now returns the tracks `artworkUrl` and `isrc` if the source supports it. +* removal of deprecated json fields like `track`. +* addition of `artworkUrl` and `isrc` fields to the [Track Info](#track-info) object. +* addition of the full [Track](#track) object in [TrackStartEvent](#trackstartevent), [TrackEndEvent](#trackendevent), [TrackExceptionEvent](#trackexceptionevent) and [TrackStuckEvent](#trackstuckevent). +* updated capitalization of [Track End Reason](#track-end-reason) and [Severity](#severity) +* reworked [Load Result](#track-loading-result) object + +All websocket ops are removed as of `v4.0.0` and replaced with the following endpoints and json fields: + +* `play` -> [Update Player Endpoint](#update-player) `encodedTrack` or `identifier` field +* `stop` -> [Update Player Endpoint](#update-player) `encodedTrack` field with `null` +* `pause` -> [Update Player Endpoint](#update-player) `pause` field +* `seek` -> [Update Player Endpoint](#update-player) `position` field +* `volume` -> [Update Player Endpoint](#update-player) `volume` field +* `filters` -> [Update Player Endpoint](#update-player) `filters` field +* `destroy` -> [Destroy Player Endpoint](#destroy-player) +* `voiceUpdate` -> [Update Player Endpoint](#update-player) `voice` field +* `configureResuming` -> [Update Session Endpoint](#update-session) + +
+ +
+v3.6.0 -> v3.7.0 + +* Moved HTTP endpoints under the new `/v3` path with `/version` as the only exception. +* Deprecation of the old HTTP paths. +* WebSocket handshakes should be done with `/v3/websocket`. Handshakes on `/` are now deprecated. +* Deprecation of all client-to-server messages (play, stop, pause, seek, volume, filters, destroy, voiceUpdate & configureResuming). +* Addition of REST endpoints intended to replace client requests. +* Addition of new WebSocket dispatch [Ready OP](#ready-op) to get `sessionId` and `resume` status. +* Addition of new [Session](#update-session)/[Player](#get-player) REST API. +* Addition of `/v3/info`, replaces `/plugins`. +* Deprecation of `Track.track` in existing endpoints. Use `Track.encoded` instead. +* Deprecation of `TrackXEvent.track` in WebSocket dispatches. Use `TrackXEvent.encodedTrack` instead. +* Player now has a `state` field which contains the same structure as returned by the `playerUpdate` OP. + +All websocket ops are deprecated as of `v3.7.0` and replaced with the following endpoints and json fields: + +* `play` -> [Update Player Endpoint](#update-player) `track` or `identifier` field +* `stop` -> [Update Player Endpoint](#update-player) `track` field with `null` +* `pause` -> [Update Player Endpoint](#update-player) `pause` field +* `seek` -> [Update Player Endpoint](#update-player) `position` field +* `volume` -> [Update Player Endpoint](#update-player) `volume` field +* `filters` -> [Update Player Endpoint](#update-player) `filters` field +* `destroy` -> [Destroy Player Endpoint](#destroy-player) +* `voiceUpdate` -> [Update Player Endpoint](#update-player) `voice` field +* `configureResuming` -> [Update Session Endpoint](#update-session) + +
+ +
+v3.3 -> v3.4 + +* Added filters +* The `error` string on the `TrackExceptionEvent` has been deprecated and replaced by + the [Exception](#exception-object) object following the same structure as the `LOAD_FAILED` error on [`/loadtracks`](#track-loading). +* Added the `connected` boolean to player updates. +* Added source name to REST api track objects +* Clients are now requested to make their name known during handshake + +
+ +
+v2.0 -> v3.0 + +* The response of `/loadtracks` has been completely changed (again since the initial v3.0 pre-release). +* Lavalink v3.0 now reports its version as a handshake response header. + `Lavalink-Major-Version` has a value of `3` for v3.0 only. It's missing for any older version. + +
+ + +
+v1.3 -> v2.0 + +With the release of v2.0 many unnecessary ops were removed: + +* `connect` +* `disconnect` +* `validationRes` +* `isConnectedRes` +* `validationReq` +* `isConnectedReq` +* `sendWS` + +With Lavalink 1.x the server had the responsibility of handling Discord `VOICE_SERVER_UPDATE`s as well as its own internal ratelimiting. +This remote handling makes things unnecessarily complicated and adds a lot og points where things could go wrong. +One problem we noticed is that since JDA is unaware of ratelimits on the bot's gateway connection, it would keep adding +to the ratelimit queue to the gateway. With this update this is now the responsibility of the Lavalink client or the +Discord client. + +A voice connection is now initiated by forwarding a `voiceUpdate` (VOICE_SERVER_UPDATE) to the server. When you want to +disconnect or move to a different voice channel you must send Discord a new VOICE_STATE_UPDATE. If you want to move your +connection to a new Lavalink server you can simply send the VOICE_SERVER_UPDATE to the new node, and the other node +will be disconnected by Discord. + +Depending on your Discord library, it may be possible to take advantage of the library's OP 4 handling. For instance, +the JDA client takes advantage of JDA's websocket write thread to send OP 4s for connects, disconnects and reconnects. + +
+ + diff --git a/docs/changelog/v2.md b/docs/changelog/v2.md new file mode 100644 index 000000000..7773703ac --- /dev/null +++ b/docs/changelog/v2.md @@ -0,0 +1,36 @@ +## v2.2 + +* Lavaplayer updated to 1.3.x [\#115](https://github.com/lavalink-devs/Lavalink/pull/115) +* Version command line flag [\#121](https://github.com/lavalink-devs/Lavalink/pull/121) +* Fix race condition in `/loadtracks` endpoint leading to some requests never completing [\#125](https://github.com/lavalink-devs/Lavalink/pull/125) + +Contributors: +[@Devoxin](https://github.com/Devoxin), +[@freyacodes](https://github.com/freyacodes/), +[@napstr](https://github.com/napstr) + +## v2.1 + +* Add prometheus metrics [\#105](https://github.com/lavalink-devs/Lavalink/pull/105), [\#106](https://github.com/lavalink-devs/Lavalink/pull/106) + +Contributors: +[@freyacodes](https://github.com/freyacodes/), +[@napstr](https://github.com/napstr), +[@Repulser](https://github.com/Repulser/) + +## v2.0.1 + +* Configurable playlist load limit [\#60](https://github.com/lavalink-devs/Lavalink/pull/60) +* [Docker Releases](https://hub.docker.com/r/fredboat/lavalink/), [\#74](https://github.com/lavalink-devs/Lavalink/pull/74) + +Contributors: +[@Devoxin](https://github.com/Devoxin), +[@freyacodes](https://github.com/freyacodes/), +[@itslukej](https://github.com/itslukej/), +[@napstr](https://github.com/napstr), +[@Repulser](https://github.com/Repulser/) + +## v2.0 + +Please see [here](https://github.com/lavalink-devs/Lavalink/commit/b8dd3c8a7e186755c1ab343d19a552baecf138e7) +and [here](https://github.com/lavalink-devs/Lavalink/commit/08a34c99a47a18ade7bd14e6c55ab92348caaa88) diff --git a/docs/changelog.md b/docs/changelog/v3.md similarity index 68% rename from docs/changelog.md rename to docs/changelog/v3.md index a49f888fc..1be1b2e34 100644 --- a/docs/changelog.md +++ b/docs/changelog/v3.md @@ -1,77 +1,24 @@ ---- -description: Lavalink changelog. ---- - -# Changelog - -Each release usually includes various fixes and improvements. -The most noteworthy of these, as well as any features and breaking changes, are listed here. - -## v4 - -### v4.0.0-beta.5 -* Update lavaplayer to [`2.0.3`](https://github.com/lavalink-devs/lavaplayer/releases/tag/2.0.2) - Fixed YouTube access token errors -* Added default plugin repository. Plugin devs can now request their plugin to be added to the default repository. For more info see [here](api/plugins.md#distributing-your-plugin) -* Fixed error when seeking and player is not playing anything in - -### v4.0.0-beta.4 - -* Update lavaplayer to [`2.0.2`](https://github.com/lavalink-devs/lavaplayer/releases/tag/2.0.2) - Support MPEG 2.5 and fixed some requests not timing out -* Add `Omissible#isPresent` & `Omissible#isOmitted` to the `protocol` module -* Fix null pointer when a playlist has no selected track - -### v4.0.0-beta.3 - -* Update lavaplayer to [`2.0.0`](https://github.com/lavalink-devs/lavaplayer/releases/tag/2.0.0) - Fixed YouTube 403 errors & YouTube access token errors - -### v4.0.0-beta.2 - -* Update lavaplayer to [`08cfbc0`](https://github.com/Walkyst/lavaplayer-fork/commit/08cfbc05953128f3cf727ea3bcbe41dabcd1c7db) - Fixed ogg streaming -* Add JDA-NAS support for musl (`x86-64`, `aarch64`) based systems (most notably `alpine`) -* New config option to specify the directory to load plugins from. `lavalink.pluginsDir` (defaults to `./plugins`) - -### v4.0.0-beta.1 - -* New Lavalink now requires Java 17 or higher to run -* **Removal of all websocket messages sent by the client. Everything is now done via [REST](api/rest.md)** -* Update to [Lavaplayer custom branch](https://github.com/Walkyst/lavaplayer-fork/tree/custom), which includes native support for artwork urls and ISRCs in the track info -* Addition of full `Track` objects in following events: `TrackStartEvent`, `TrackEndEvent`, `TrackExceptionEvent`, `TrackStuckEvent` -* Resuming a session now requires the `Session-Id` header instead of `Resume-Key` header -* Reworked track loading result. For more info see [here](api/rest.md#track-loading-result) -* Update to the [Protocol Module](https://github.com/lavalink-devs/Lavalink/tree/master/protocol) to support Kotlin/JS -* Removal of all `/v3` endpoints except `/version`. All other endpoints are now under `/v4` - -> **Warning** -> This is a beta release, and as such, may contain bugs. Please report any bugs you find to the [issue tracker](https://github.com/lavalink-devs/Lavalink/issues/new/choose). -> For more info on the changes in this release, see [here](api/index.md#v370---v400) -> If you have any question regarding the changes in this release, please ask in the [support server]({{ discord_help }}) or [GitHub discussions](https://github.com/lavalink-devs/Lavalink/discussions/categories/q-a) - -Contributors: -[@topi314](https://github.com/topi314), [@freyacodes](https://github.com/freyacodes), [@DRSchlaubi](https://github.com/DRSchlaubi) and [@melike2d](https://github.com/melike2d) - -## v3 - -### v3.7.9 +## v3.7.9 * Update lavaplayer to [`1.5.1`](https://github.com/lavalink-devs/lavaplayer/releases/tag/1.5.1) - Fixed YouTube access token errors * Fixed websocket crash when seeking and nothing is playing * Fixed error when seeking and player is not playing anything -### v3.7.8 +## v3.7.8 * Fix YouTube 403 errors * Fix YouTube access token errors -### v3.7.7 +## v3.7.7 * Add JDA-NAS support for musl (`x86-64`, `aarch64`) based systems (most notably `alpine`) -### v3.7.6 +## v3.7.6 * Update Lavaplayer to [`1.4.1`](https://github.com/Walkyst/lavaplayer-fork/releases/tag/1.4.1) & [`1.4.2`](https://github.com/Walkyst/lavaplayer-fork/releases/tag/1.4.2) * New support for `MUSL` based systems (most notably `alpine`) * New `alpine` docker image variant (use `-alpine` suffix) -### v3.7.5 +## v3.7.5 * Fix `endTime` in `Player Update` endpoint only applying when playing a new track * Fix errors when doing multiple session resumes @@ -80,23 +27,23 @@ Contributors: > **Note** > Lavalink Docker images are now found in the GitHub Container Registry instead of DockerHub -### v3.7.4 +## v3.7.4 * Fix an issue where Lavalink would not destroy a session when a client disconnects -### v3.7.3 +## v3.7.3 * Fix breaking change where `/decodetrack` would return a full track instead of the track info -### v3.7.2 +## v3.7.2 * Fix breaking change where frameStats would be null instead of omitted -### v3.7.1 +## v3.7.1 * Revert of application.yml autocreate as it can cause issues with differently named configs -### v3.7.0 +## v3.7.0 * New REST API for player control and deprecation of all websocket OPs. For more info see [here](https://github.com/lavalink-devs/Lavalink/blob/master/IMPLEMENTATION.md#significant-changes-v360---v370) * Autocreate default `application.yml` if none was found. https://github.com/lavalink-devs/Lavalink/pull/781 @@ -108,22 +55,22 @@ Contributors: Contributors: [@topi314](https://github.com/topi314), [@Devoxin](https://github.com/Devoxin), [@melike2d](https://github.com/melike2d), [@freyacodes](https://github.com/freyacodes), [@aikaterna](https://github.com/aikaterna), [@ooliver1](https://github.com/ooliver1) -### v3.6.2 +## v3.6.2 * Update lavaplayer to `1.3.99.1`. For more info see [here](https://github.com/lavalink-devs/Lavalink/pull/773) -### v3.6.1 +## v3.6.1 * Update lavaplayer to `1.3.99`. For more info see [here](https://github.com/lavalink-devs/Lavalink/pull/768) -### v3.6.0 +## v3.6.0 * New userId & clientName getters in the plugin-api. For more info see [here](https://github.com/lavalink-devs/Lavalink/pull/743). Contributors: [@melike2d](https://github.com/melike2d) -### v3.5.1 +## v3.5.1 * Update udpqueue.rs to `0.2.5` which fixes crashes when ipv6 is disabled * Fix null socketContext in `IPlayer` for plugins @@ -132,7 +79,7 @@ Contributors: Contributors: [@topi314](https://github.com/topi314), [@Devoxin](https://github.com/Devoxin), and [@freyacodes](https://github.com/freyacodes) -### v3.5 +## v3.5 * New plugin system. For more info see [here](https://github.com/lavalink-devs/Lavalink/blob/master/PLUGINS.md). * Add support for HTTP proxying via httpConfig. For more info see [here](https://github.com/lavalink-devs/Lavalink/pull/595). @@ -165,7 +112,7 @@ Contributors: [@TheEssemm](https://github.com/TheEssemm), and [@jack1142](https://github.com/jack1142) -### v3.4 +## v3.4 * New filters system * Deprecation of `TrackExceptionEvent.error`, replaced by `TrackExceptionEvent.exception` @@ -182,28 +129,28 @@ Contributors: [@Allvaa](https://github.com/@Allvaa), and [@topi314](https://github.com/topi314) -### v3.3.2.5 +## v3.3.2.5 * Update Lavaplayer to 1.3.76 -### v3.3.2.4 +## v3.3.2.4 * Update Lavaplayer to 1.3.74 -### v3.3.2.3 +## v3.3.2.3 * Update Lavaplayer to 1.3.65, fixes Soundcloud -### v3.3.2.2 +## v3.3.2.2 * Updated Lavaplayer to 1.3.61 * Fixed a ConcurrentModificationException ([Thewsomeguy](https://github.com/Thewsomeguy)) -### v3.3.2.1 +## v3.3.2.1 * Updated to Sedmelluq's Lavaplayer 1.3.53 -### v3.3.2 +## v3.3.2 * Replaced Magma with Koe. * Finally implemented `stopTime` for `play` op. @@ -222,25 +169,25 @@ Contributors: [@TheEssem](https://github.com/Essem), and [@Devoxin](https://github.com/Devoxin) -### v3.3.1.4 +## v3.3.1.4 * Update lavaplayer to `1.3.54.3` from devoxin's fork. -### v3.3.1.3 +## v3.3.1.3 * Update lavaplayer to `1.3.53` from devoxin's fork. -### v3.3.1.2 +## v3.3.1.2 * Update lavaplayer to [@Devoxin](https://github.com/Devoxin)'s' fork -### v3.3.1.1 +## v3.3.1.1 * Updated Lavaplayer to `1.3.50`. This notably fixes YouTube search. Search patch contributed by [@freyacodes](https://github.com/freyacodes) -### v3.3.1 +## v3.3.1 * Update Magma and Lavaplayer. * Added TrackStartEvent event. @@ -254,11 +201,11 @@ Contributors: [@ByteAlex](https://github.com/ByteAlex), and [@Xavinlol](https://github.com/Xavinlol) -### v3.3 +## v3.3 Officially limit Lavalink to JRE 11 and up. Magma has long been having issues with older versions. -### v3.2.2 +## v3.2.2 * IP rotation system for getting around certain ratelimits. * Update Lavaplayer to 1.3.32. @@ -270,7 +217,7 @@ Contributors: [@duncte123](https://github.com/duncte123), and [@james7132](https://github.com/james7132) -### v3.2.1.1 +## v3.2.1.1 * Updated Lavaplayer to 1.3.19. This release includes a patch which fixes loading youtube URLs. https://github.com/sedmelluq/lavaplayer/pull/199 @@ -280,7 +227,7 @@ Contributors: [@freyacodes](https://github.com/freyacodes) and [@Devoxin](https://github.com/Devoxin) -### v3.2.1 +## v3.2.1 * Update dependencies -- fixes frequent youtube HTTP errors * Return `FriendlyException` message on `LOAD_FAILED` #174 @@ -292,27 +239,27 @@ Contributors: [@freyacodes](https://github.com/freyacodes), and [@napstr](https://github.com/napstr) -### v3.2.0.3 +## v3.2.0.3 * Add compatibility for Java 8-10 Contributor: [@MinnDevelopment](https://github.com/MinnDevelopment/) -### v3.2.0.2 +## v3.2.0.2 * Patched magma Contributor: [@freyacodes](https://github.com/freyacodes/) -### v3.2.0.1 +## v3.2.0.1 * Bumped to Java 11. Treating this as a patch version, as v3.2 still requires Java 11 due to a Magma update. [@freyacodes](https://github.com/freyacodes) -### v3.2 +## v3.2 * Added support for resuming * Added noReplace option to the play op @@ -321,14 +268,14 @@ Contributor: Contributor: [@freyacodes](https://github.com/freyacodes) -### v3.1.2 +## v3.1.2 * Add API version header to all responses Contributor: [@Devoxin](https://github.com/Devoxin) -### v3.1.1 +## v3.1.1 * Add equalizer support * Update lavaplayer to 1.3.10 @@ -340,14 +287,14 @@ Contributors: [@freyacodes](https://github.com/freyacodes/), [@calebj](https://github.com/calebj) -### v3.1 +## v3.1 * Replaced JDAA with Magma * Added an event for when the Discord voice WebSocket is closed * Replaced Tomcat and Java_Websocket with Undertow. WS and REST is now handled by the same server and port. Port is specified by `server.port`. -### v3.0 +## v3.0 * **Breaking:** The minimum required Java version to run the server is now Java 10. **Please note**: Java 10 will be obsolete @@ -366,42 +313,3 @@ Contributors: [@freyacodes](https://github.com/freyacodes/), [@napstr](https://github.com/napstr), [@SamOphis](https://github.com/SamOphis) - -## v2 - -### v2.2 - -* Lavaplayer updated to 1.3.x [\#115](https://github.com/lavalink-devs/Lavalink/pull/115) -* Version command line flag [\#121](https://github.com/lavalink-devs/Lavalink/pull/121) -* Fix race condition in `/loadtracks` endpoint leading to some requests never completing [\#125](https://github.com/lavalink-devs/Lavalink/pull/125) - -Contributors: -[@Devoxin](https://github.com/Devoxin), -[@freyacodes](https://github.com/freyacodes/), -[@napstr](https://github.com/napstr) - -### v2.1 - -* Add prometheus metrics [\#105](https://github.com/lavalink-devs/Lavalink/pull/105), [\#106](https://github.com/lavalink-devs/Lavalink/pull/106) - -Contributors: -[@freyacodes](https://github.com/freyacodes/), -[@napstr](https://github.com/napstr), -[@Repulser](https://github.com/Repulser/) - -### v2.0.1 - -* Configurable playlist load limit [\#60](https://github.com/lavalink-devs/Lavalink/pull/60) -* [Docker Releases](https://hub.docker.com/r/fredboat/lavalink/), [\#74](https://github.com/lavalink-devs/Lavalink/pull/74) - -Contributors: -[@Devoxin](https://github.com/Devoxin), -[@freyacodes](https://github.com/freyacodes/), -[@itslukej](https://github.com/itslukej/), -[@napstr](https://github.com/napstr), -[@Repulser](https://github.com/Repulser/) - -### v2.0 - -Please see [here](https://github.com/lavalink-devs/Lavalink/commit/b8dd3c8a7e186755c1ab343d19a552baecf138e7) -and [here](https://github.com/lavalink-devs/Lavalink/commit/08a34c99a47a18ade7bd14e6c55ab92348caaa88) diff --git a/docs/changelog/v4.md b/docs/changelog/v4.md new file mode 100644 index 000000000..b877503d3 --- /dev/null +++ b/docs/changelog/v4.md @@ -0,0 +1,40 @@ +## v4.0.0-beta.5 +* Update lavaplayer to [`2.0.3`](https://github.com/lavalink-devs/lavaplayer/releases/tag/2.0.2) - Fixed YouTube access token errors +* Added default plugin repository. Plugin devs can now request their plugin to be added to the default repository. For more info see [here](../api/plugins.md#distributing-your-plugin) +* Fixed error when seeking and player is not playing anything in + +## v4.0.0-beta.4 + +* Update lavaplayer to [`2.0.2`](https://github.com/lavalink-devs/lavaplayer/releases/tag/2.0.2) - Support MPEG 2.5 and fixed some requests not timing out +* Add `Omissible#isPresent` & `Omissible#isOmitted` to the `protocol` module +* Fix null pointer when a playlist has no selected track + +## v4.0.0-beta.3 + +* Update lavaplayer to [`2.0.0`](https://github.com/lavalink-devs/lavaplayer/releases/tag/2.0.0) - Fixed YouTube 403 errors & YouTube access token errors + +## v4.0.0-beta.2 + +* Update lavaplayer to [`08cfbc0`](https://github.com/Walkyst/lavaplayer-fork/commit/08cfbc05953128f3cf727ea3bcbe41dabcd1c7db) - Fixed ogg streaming +* Add JDA-NAS support for musl (`x86-64`, `aarch64`) based systems (most notably `alpine`) +* New config option to specify the directory to load plugins from. `lavalink.pluginsDir` (defaults to `./plugins`) + +## v4.0.0-beta.1 + +* New Lavalink now requires Java 17 or higher to run +* **Removal of all websocket messages sent by the client. Everything is now done via [REST](../api/rest.md)** +* Update to [Lavaplayer custom branch](https://github.com/Walkyst/lavaplayer-fork/tree/custom), which includes native support for artwork urls and ISRCs in the track info +* Addition of full `Track` objects in following events: `TrackStartEvent`, `TrackEndEvent`, `TrackExceptionEvent`, `TrackStuckEvent` +* Resuming a session now requires the `Session-Id` header instead of `Resume-Key` header +* Reworked track loading result. For more info see [here](../api/rest.md#track-loading-result) +* Update to the [Protocol Module](https://github.com/lavalink-devs/Lavalink/tree/master/protocol) to support Kotlin/JS +* Removal of all `/v3` endpoints except `/version`. All other endpoints are now under `/v4` + +> **Warning** +> This is a beta release, and as such, may contain bugs. Please report any bugs you find to the [issue tracker](https://github.com/lavalink-devs/Lavalink/issues/new/choose). +> For more info on the changes in this release, see [here](../api/index.md#v370---v400) +> If you have any question regarding the changes in this release, please ask in the [support server]({{ discord_help }}) or [GitHub discussions](https://github.com/lavalink-devs/Lavalink/discussions/categories/q-a) + +Contributors: +[@topi314](https://github.com/topi314), [@freyacodes](https://github.com/freyacodes), [@DRSchlaubi](https://github.com/DRSchlaubi) and [@melike2d](https://github.com/melike2d) + diff --git a/docs/clients.md b/docs/clients.md index 4f4b0c9b6..075cbdb52 100644 --- a/docs/clients.md +++ b/docs/clients.md @@ -23,7 +23,7 @@ description: A list of Lavalink client libraries. | [Coglink](https://github.com/PerformanC/Coglink) | C | Concord | | | [lavalink-rs](https://gitlab.com/vicky5124/lavalink-rs) | Rust, Python | **Any** | `tokio`-based, `asyncio`-based | -
+
v3.7 supporting Client Libraries | Client | Platform | Compatible With | Additional Information | diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md index 651e53c42..d10319171 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -6,28 +6,28 @@ description: Lavalink getting started guide. Welcome to the Lavalink Getting Started guide. If you're new to Lavalink, follow these steps to get started: -1. Install Java 17 or higher. You can download it [here](https://www.azul.com/downloads/?package=jdk#zulu). -2. Download the latest `Lavalink.jar` from [GitHub](https://github.com/lavalink-devs/Lavalink/releases/latest). -3. Check out the [configuration](../configuration/index.md) page to learn how to configure Lavalink. -4. Run Lavalink with `java -jar Lavalink.jar`. +## Prerequisites -Now you can connect to Lavalink with your client. You can find a list of clients [here](../clients.md). +Install Java 17 or higher. You can download it [here](https://www.azul.com/downloads/?package=jdk#zulu). -If you want to run the Lavalink server without it closing when you close the terminal, you can see the [Docker](../configuration/docker.md) or [Systemd](../configuration/systemd.md) configuration pages. +## Installation -## Useful Links +Download the latest `Lavalink.jar` from [GitHub](https://github.com/lavalink-devs/Lavalink/releases/latest). -- [Features](https://github.com/lavalink-devs/Lavalink#features): Explore the rich feature set of Lavalink. -- [Clients](../clients.md): Explore Lavalink clients. -- [Plugins](../plugins.md): Explore Lavalink plugins. -- [Changelog](../changelog.md): Stay updated with the latest changes and improvements. -- [API Implementation Guidelines](../api/index.md): Learn about implementing the Lavalink API. -- [Server Configuration](../configuration/index.md): Learn about configuring your Lavalink server. +## Configuration -## Found a Bug? +Check out the [configuration](../configuration/index.md) page to learn how to configure Lavalink. -If you found a bug, please report it on the [issue tracker](https://github.com/lavalink-devs/Lavalink/issues/new?labels=bug&template=bug_report.md). +## Running Lavalink -## Need Help? +Run Lavalink with `java -jar Lavalink.jar`. -Join the [Lavalink support Discord]({{ discord_help }}) or open a [GitHub discussion](https://github.com/lavalink-devs/Lavalink/discussions/new?category=q-a) for help or questions. +If you want to keep Lavalink running in the background, you can check out the [Docker](../configuration/docker.md) or [Systemd](../configuration/systemd.md) configuration pages. + +## Connecting to Lavalink + +Pick a client from the [clients](../clients.md) page and follow their instructions on how to connect to Lavalink. + +## Getting stuck? + +If you're stuck, you can join the [Lavalink support Discord]({{ discord_help }}) or open a [GitHub discussion](https://github.com/lavalink-devs/Lavalink/discussions/new?category=q-a) for help or questions. diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md new file mode 100644 index 000000000..c92f29a57 --- /dev/null +++ b/docs/getting-started/troubleshooting.md @@ -0,0 +1,55 @@ +--- +description: Lavalink troubleshooting steps. +--- + +# Trouble Shooting + +## Lavalink won't start + +If Lavalink won't start, check the following: + +- Make sure you have Java 17 or higher installed. You can download it [here](https://www.azul.com/downloads/?package=jdk#zulu). + +- Make sure you have downloaded the latest `Lavalink.jar` from [GitHub](https://github.com/lavalink-devs/Lavalink/releases/latest). + +- Make sure you have configured Lavalink correctly. Check out the [configuration](../configuration/index.md) page for more information. + +- If you're using Docker, make sure you have configured Docker correctly. + Check out the [Docker](../configuration/docker.md) page for more information. + +- If you're using Systemd, make sure you have configured Systemd correctly. + Check out the [Systemd](../configuration/systemd.md) page for more information. + +- If you are using a firewall, make sure you have opened the port you configured Lavalink to use. + +- If you are using a reverse proxy, make sure you have configured it correctly. Nginx needs to be configured to pass the `Upgrade` header for WebSockets to work. + +## Configuring more detailed Logging + +If you are having issues with Lavalink, you can enable more detailed logging by adding the following to your `application.yml`: + +In general there are 6 log levels: `TRACE`, `DEBUG`, `INFO`, `WARN`, `ERROR` and `OFF`. + + +```yaml title="application.yml" +logging: + level: + # Set this to DEBUG to enable more detailed logging. Please note that this will log probably spam your console. + root: INFO + # Set this to DEBUG to enable more detailed logging from Lavalink + lavalink: DEBUG + # Set this to TRACE to see all WebSocket messages + lavalink.server.io.SocketContext: TRACE + + # This will log all requests to the REST API + request: + enabled: true + includeClientInfo: true + includeHeaders: false + includeQueryString: true + includePayload: true +``` + +## Lavalink won't connect to Discord / Play Audio + +If Lavalink doesn't connect to Discord, make sure you forward the `sessionId`, `token` and `enpoint` to Lavalink via the [player update endpoint](../api/rest.md#update-player). diff --git a/docs/index.md b/docs/index.md index c37f20ddf..44fb0916d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,6 +10,8 @@ hide: - path --- +## Features + ::cards:: - title: Powered by Lavaplayer @@ -33,12 +35,13 @@ hide: url: api/rest.md - title: Statistics icon: ':octicons-graph-16:' - url: api/websocket.md#stats-op + url: api/rest.html#get-lavalink-stats - title: Basic authentication icon: ':material-lock:' - url: api/websocket.md#opening-a-connection + url: api/rest.html - title: Prometheus metrics icon: ':simple-prometheus:' + url: https://prometheus.io/ - title: Docker images icon: ':simple-docker:' url: configuration/docker.md @@ -46,4 +49,12 @@ hide: icon: ':material-power-plug-outline:' url: plugins.md -::/cards:: \ No newline at end of file +::/cards:: + +## Found a Bug? + +If you found a bug, please report it on the [issue tracker](https://github.com/lavalink-devs/Lavalink/issues/new?labels=bug&template=bug_report.md). + +## Need Help? + +Join the [Lavalink support Discord]({{ discord_help }}) or open a [GitHub discussion](https://github.com/lavalink-devs/Lavalink/discussions/new?category=q-a) for help or questions. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index bc1bb62a0..17d70d029 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -17,6 +17,7 @@ nav: - Home: index.md - Getting Started: - getting-started/index.md + - Troubleshooting: getting-started/troubleshooting.md - FAQ: getting-started/faq.md - Configuration: - configuration/index.md @@ -30,7 +31,11 @@ nav: - Websocket: api/websocket.md - Rest: api/rest.md - Plugins: api/plugins.md - - Changelog: changelog.md + - Changelog: + - changelog/index.md + - v4: changelog/v4.md + - v3: changelog/v3.md + - v2: changelog/v2.md extra_css: - stylesheets/style.css diff --git a/docs/overrides/home.html b/docs/overrides/home.html index 594625dbb..db0525ebe 100644 --- a/docs/overrides/home.html +++ b/docs/overrides/home.html @@ -1,30 +1,32 @@ {% extends "main.html" %} {% block tabs %} {{ super() }} - -
-
-
+ {% endblock %} {% block content %} {% endblock %} {% block footer %} {{ super() }} -{% endblock %} \ No newline at end of file +{% endblock %} + diff --git a/docs/stylesheets/neoteroi-cards.css b/docs/stylesheets/neoteroi-cards.css index d1a70ab69..13cbf35ef 100644 --- a/docs/stylesheets/neoteroi-cards.css +++ b/docs/stylesheets/neoteroi-cards.css @@ -30,7 +30,7 @@ .nt-card { border-radius: 4px; box-shadow: 0 2px 2px 0 rgba(0, 0, 0, 0.14), 0 3px 1px -2px rgba(0, 0, 0, 0.2), 0 1px 5px 0 rgba(0, 0, 0, 0.12); - background-color: var(--md-primary-fg-color); + background-color: var(--md-typeset-kbd-color); } .nt-card:hover { @@ -42,26 +42,28 @@ display: flex; flex-direction: row; align-items: center; - justify-content: space-between; - padding: 0.8rem 0.8rem 0.8rem 0.8rem; + justify-content: flex-start; + padding: .625em; border-radius: 4px; } .nt-card > a > div:hover { - background-color: var(--md-accent-fg-color); + background-color: var(--md-typeset-kbd-color); +} + +.nt-card-content { + width: 100%; } .nt-card-title { - font-size: 1rem; font-weight: bold; margin: 4px 0 8px 0; - line-height: 22px; - text-align: right; - color: var(--md-primary-bg-color); + text-align: center; + color: var(--md-default-fg-color); } .nt-card-icon { - color: var(--md-primary-bg-color); + color: var(--md-default-fg-color); } .nt-card-icon svg,