Skip to content

Commit 0eb9fa0

Browse files
topi314duncte123freyacodes
authored and
DRSchlaubi
committed
add docs for track user data (lavalink-devs#984)
* document track user data * Apply suggestions from code review Co-authored-by: Duncan Sterken <contact@duncte123.me> Co-authored-by: Freya Arbjerg <freya@arbjerg.dev> * readded depreacted fields --------- Co-authored-by: Duncan Sterken <contact@duncte123.me> Co-authored-by: Freya Arbjerg <freya@arbjerg.dev>
1 parent 0093ce4 commit 0eb9fa0

File tree

5 files changed

+67
-35
lines changed

5 files changed

+67
-35
lines changed

‎docs/api/plugins.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,9 @@ description: Make your own plugin for Lavalink.
44

55
# Make your own plugin
66

7-
> **Note:**
8-
> If your plugin is developed in Kotlin make sure you are using **Kotlin v1.8.22**
7+
!!! info
8+
9+
If your plugin is developed in Kotlin make sure you are using **Kotlin v1.8.22**
910

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

‎docs/api/rest.md

Lines changed: 53 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -53,11 +53,12 @@ When Lavalink encounters an error, it will respond with a JSON object containing
5353

5454
#### Track
5555

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

6263
#### Track Info
6364

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

9192

92-
!!! note
93+
!!! tip
9394

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

@@ -136,7 +137,8 @@ Response:
136137
"data": {
137138
"encoded": "...",
138139
"info": { ... },
139-
"pluginInfo": { ... }
140+
"pluginInfo": { ... },
141+
"userData": { ... }
140142
}
141143
}
142144
```
@@ -181,7 +183,8 @@ Array of [Track](#track) objects from the search result.
181183
{
182184
"encoded": "...",
183185
"info": { ... },
184-
"pluginInfo": { ... }
186+
"pluginInfo": { ... },
187+
"userData": { ... }
185188
},
186189
...
187190
]
@@ -259,7 +262,8 @@ Response:
259262
"isrc": null,
260263
"sourceName": "youtube"
261264
},
262-
"pluginInfo": {}
265+
"pluginInfo": { ... },
266+
"userData": { ... }
263267
}
264268
```
265269

@@ -313,7 +317,8 @@ Array of [Track](#track) objects
313317
"isrc": null,
314318
"sourceName": "youtube"
315319
},
316-
"pluginInfo": {}
320+
"pluginInfo": { ... },
321+
"userData": { ... }
317322
},
318323
...
319324
]
@@ -588,7 +593,8 @@ GET /v4/sessions/{sessionId}/players
588593
"isrc": null,
589594
"sourceName": "youtube"
590595
},
591-
"pluginInfo": {}
596+
"pluginInfo": { ... },
597+
"userData": { ... }
592598
},
593599
"volume": 100,
594600
"paused": false,
@@ -676,6 +682,10 @@ Updates or creates the player for this guild if it doesn't already exist.
676682
PATCH /v4/sessions/{sessionId}/players/{guildId}?noReplace=true
677683
```
678684

685+
!!! info
686+
687+
`sessionId` in the path should be the value from the [ready op](websocket.md#ready-op).
688+
679689
Query Params:
680690

681691
| Field | Type | Description |
@@ -684,20 +694,33 @@ Query Params:
684694

685695
Request:
686696

687-
| Field | Type | Description |
688-
|-----------------|------------------------------------|-----------------------------------------------------------------------------------------------|
689-
| encodedTrack? * | ?string | The base64 encoded track to play. `null` stops the current track |
690-
| identifier? * | string | The identifier of the track to play |
691-
| position? | int | The track position in milliseconds |
692-
| endTime? | ?int | The track end time in milliseconds (must be > 0). `null` resets this if it was set previously |
693-
| volume? | int | The player volume, in percentage, from 0 to 1000 |
694-
| paused? | bool | Whether the player is paused |
695-
| filters? | [Filters](#filters) object | The new filters to apply. This will override all previously applied filters |
696-
| voice? | [Voice State](#voice-state) object | Information required for connecting to Discord |
697-
698-
> **Note**
699-
> - \* `encodedTrack` and `identifier` are mutually exclusive.
700-
> - `sessionId` in the path should be the value from the [ready op](websocket.md#ready-op).
697+
| Field | Type | Description |
698+
|--------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------|
699+
| track? | [Update Player Track](#update-player-track) | Specification for a new track to load, as well as user data to set |
700+
| ~~encodedTrack?~~* | ?string | The base64 encoded track to play. `null` stops the current track |
701+
| ~~identifier?~~* | string | The identifier of the track to play |
702+
| *position*? | int | The track position in milliseconds |
703+
| endTime? | ?int | The track end time in milliseconds (must be > 0). `null` resets this if it was set previously |
704+
| volume? | int | The player volume, in percentage, from 0 to 1000 |
705+
| paused? | bool | Whether the player is paused |
706+
| filters? | [Filters](#filters) object | The new filters to apply. This will override all previously applied filters |
707+
| voice? | [Voice State](#voice-state) object | Information required for connecting to Discord |
708+
709+
!!! info
710+
711+
\* `encoded` and `identifier` are mutually exclusive and `DEPRECATED`. Use `track` instead.
712+
713+
#### Update Player Track
714+
715+
| Field | Type | Description |
716+
|--------------|---------|---------------------------------------------------------------------|
717+
| encoded?* | ?string | The base64 encoded track to play. `null` stops the current track |
718+
| identifier?* | string | The identifier of the track to play |
719+
| userData? | object | Additional track data to be sent back in the [Track Object](#track) |
720+
721+
!!! info
722+
723+
\* `encoded` and `identifier` are mutually exclusive.
701724

702725
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.
703726

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

707730
```yaml
708731
{
709-
"encodedTrack": "...",
710-
"identifier": "...",
732+
"track": {
733+
"encoded": "...",
734+
"identifier": "...",
735+
"userData": { ... }
736+
},
711737
"endTime": 0,
712738
"volume": 100,
713739
"position": 32400,

‎docs/changelog/v3.md

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -24,8 +24,9 @@
2424
* Fix errors when doing multiple session resumes
2525
* Update lavaplayer to `1.4.0` see [here](https://github.com/Walkyst/lavaplayer-fork/releases/tag/1.4.0) for more info
2626

27-
> **Note**
28-
> Lavalink Docker images are now found in the GitHub Container Registry instead of DockerHub
27+
!!! info
28+
29+
Lavalink Docker images are now found in the GitHub Container Registry instead of DockerHub
2930

3031
## v3.7.4
3132

‎docs/changelog/v4.md

Lines changed: 5 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -30,10 +30,11 @@
3030
* Update to the [Protocol Module](https://github.com/lavalink-devs/Lavalink/tree/master/protocol) to support Kotlin/JS
3131
* Removal of all `/v3` endpoints except `/version`. All other endpoints are now under `/v4`
3232

33-
> **Warning**
34-
> 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).
35-
> For more info on the changes in this release, see [here](../api/index.md#v370---v400)
36-
> 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)
33+
!!! warning
34+
35+
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).
36+
For more info on the changes in this release, see [here](../api/index.md#v370---v400)
37+
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)
3738

3839
Contributors:
3940
[@topi314](https://github.com/topi314), [@freyacodes](https://github.com/freyacodes), [@DRSchlaubi](https://github.com/DRSchlaubi) and [@melike2d](https://github.com/melike2d)

‎docs/mkdocs.yml

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,9 @@ markdown_extensions:
9696
- pymdownx.details
9797
- pymdownx.superfences
9898
- pymdownx.highlight
99+
- pymdownx.caret
100+
- pymdownx.mark
101+
- pymdownx.tilde
99102
- footnotes
100103
- def_list
101104
- attr_list

0 commit comments

Comments
 (0)