Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add docs for track user data #984

Merged
merged 3 commits into from
Dec 2, 2023
Merged

add docs for track user data #984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c3e1f6e
document track user data
topi314 Dec 2, 2023
f8a5261
Apply suggestions from code review
topi314 Dec 2, 2023
cceae99
readded depreacted fields
topi314 Dec 2, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions docs/api/plugins.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ description: Make your own plugin for Lavalink.

# Make your own plugin

> **Note:**
> If your plugin is developed in Kotlin make sure you are using **Kotlin v1.8.22**
!!! info

If your plugin is developed in Kotlin make sure you are using **Kotlin v1.8.22**

Follow [these steps](https://github.com/lavalink-devs/lavalink-plugin-template#how-to-use-this-template) to set up a new Lavalink plugin

Expand Down
80 changes: 53 additions & 27 deletions docs/api/rest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,11 +53,12 @@ When Lavalink encounters an error, it will respond with a JSON object containing

#### Track

| Field | Type | Description |
|------------|----------------------------------|-----------------------------------------|
| encoded | string | The base64 encoded track data |
| info | [Track Info](#track-info) object | Info about the track |
| pluginInfo | object | Addition track info provided by plugins |
| Field | Type | Description |
|------------|----------------------------------|-------------------------------------------------------------------------------|
| encoded | string | The base64 encoded track data |
| info | [Track Info](#track-info) object | Info about the track |
| pluginInfo | object | Additional track info provided by plugins |
| userData | object | Additional track data provided via the [Update Player](#update-player) endpoint |

#### Track Info

Expand Down Expand Up @@ -89,7 +90,7 @@ When Lavalink encounters an error, it will respond with a JSON object containing
This endpoint is used to resolve audio tracks for use with the [Update Player](#update-player) endpoint.


!!! note
!!! tip

Lavalink supports searching via YouTube, YouTube Music, and Soundcloud. To search, you must prefix your identifier with `ytsearch:`, `ytmsearch:` or `scsearch:` respectively.

Expand Down Expand Up @@ -136,7 +137,8 @@ Response:
"data": {
"encoded": "...",
"info": { ... },
"pluginInfo": { ... }
"pluginInfo": { ... },
"userData": { ... }
}
}
```
Expand Down Expand Up @@ -181,7 +183,8 @@ Array of [Track](#track) objects from the search result.
{
"encoded": "...",
"info": { ... },
"pluginInfo": { ... }
"pluginInfo": { ... },
"userData": { ... }
},
...
]
Expand Down Expand Up @@ -259,7 +262,8 @@ Response:
"isrc": null,
"sourceName": "youtube"
},
"pluginInfo": {}
"pluginInfo": { ... },
"userData": { ... }
}
```

Expand Down Expand Up @@ -313,7 +317,8 @@ Array of [Track](#track) objects
"isrc": null,
"sourceName": "youtube"
},
"pluginInfo": {}
"pluginInfo": { ... },
"userData": { ... }
},
...
]
Expand Down Expand Up @@ -588,7 +593,8 @@ GET /v4/sessions/{sessionId}/players
"isrc": null,
"sourceName": "youtube"
},
"pluginInfo": {}
"pluginInfo": { ... },
"userData": { ... }
},
"volume": 100,
"paused": false,
Expand Down Expand Up @@ -676,6 +682,10 @@ Updates or creates the player for this guild if it doesn't already exist.
PATCH /v4/sessions/{sessionId}/players/{guildId}?noReplace=true
```

!!! info

`sessionId` in the path should be the value from the [ready op](websocket.md#ready-op).

Query Params:

| Field | Type | Description |
Expand All @@ -684,20 +694,33 @@ Query Params:

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 |
topi314 marked this conversation as resolved.
Show resolved Hide resolved
| 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).
| Field | Type | Description |
|--------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------|
| track? | [Update Player Track](#update-player-track) | Specification for a new track to load, as well as user data to set |
| ~~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 |

!!! info

\* `encoded` and `identifier` are mutually exclusive and `DEPRECATED`. Use `track` instead.

#### Update Player Track

| Field | Type | Description |
|--------------|---------|---------------------------------------------------------------------|
| encoded?* | ?string | The base64 encoded track to play. `null` stops the current track |
| identifier?* | string | The identifier of the track to play |
| userData? | object | Additional track data to be sent back in the [Track Object](#track) |

!!! info

\* `encoded` and `identifier` are mutually exclusive.

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.

Expand All @@ -706,8 +729,11 @@ When `identifier` is used, Lavalink will try to resolve the identifier as a sing

```yaml
{
"encodedTrack": "...",
"identifier": "...",
"track": {
"encoded": "...",
"identifier": "...",
"userData": { ... }
},
"endTime": 0,
"volume": 100,
"position": 32400,
Expand Down
5 changes: 3 additions & 2 deletions docs/changelog/v3.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,8 +24,9 @@
* Fix errors when doing multiple session resumes
* Update lavaplayer to `1.4.0` see [here](https://github.com/Walkyst/lavaplayer-fork/releases/tag/1.4.0) for more info

> **Note**
> Lavalink Docker images are now found in the GitHub Container Registry instead of DockerHub
!!! info

Lavalink Docker images are now found in the GitHub Container Registry instead of DockerHub

## v3.7.4

Expand Down
9 changes: 5 additions & 4 deletions docs/changelog/v4.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,10 +30,11 @@
* 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)
!!! 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)
Expand Down
3 changes: 3 additions & 0 deletions docs/mkdocs.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,6 +96,9 @@ markdown_extensions:
- pymdownx.details
- pymdownx.superfences
- pymdownx.highlight
- pymdownx.caret
- pymdownx.mark
- pymdownx.tilde
- footnotes
- def_list
- attr_list
Expand Down