kitty/spotube
1
0
Fork 0
mirror of https://github.com/KRTirtho/spotube.git synced 2025-09-12 23:45:18 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs: merge some endpoints together to reduce too much elements on the side bar

Browse Source
This commit is contained in:
Kingkor Roy Tirtho 2025-08-14 20:19:16 +06:00
parent 032309a2c6
commit 0e34057794
21 changed files with 684 additions and 801 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
website/src/components/navigation/DocSideBar.astro
View File

@ -58,7 +58,7 @@ const sections: [
][] = [ ][] = [
["Get Started", "get-started/", queryCollection], ["Get Started", "get-started/", queryCollection],
["Developing Plugins", "developing-plugins/", queryCollection], ["Developing Plugins", "developing-plugins/", queryCollection],
["Models", "models/", queryCollection], ["Reference", "reference/", queryCollection],
// ["Design System", "design/", queryCollection], // ["Design System", "design/", queryCollection],
// ["Tailwind Components", "tailwind/", queryCollection], // ["Tailwind Components", "tailwind/", queryCollection],
// ["Functional Components", "components/", queryMetaCollection], // ["Functional Components", "components/", queryMetaCollection],

48
website/src/content/docs/developing-plugins/album-endpoint.mdx
View File

@ -1,48 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The AlbumEndpoint
description: ""
order: 6
---
The AlbumEndpoint is used to fetch album information and do album-related actions. In the `src/segments/album.ht` file you can find all the
required method definitions.
```hetu_script
class AlbumEndpoint {
construct (this.client)
fun getAlbum(id: string) {
// TODO: Implement method
}
fun tracks(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun releases({offset: int, limit: int}) {
// TODO: Implement method
}
fun save(albumIds: List) { // List<String>
// TODO: Implement method
}
fun unsave(albumIds: List) { // List<String>
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `getAlbum()` | Fetches album information by ID. | [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `tracks()` | Fetches tracks of the specified album. Accepts an ID and optional pagination parameters. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `releases()` | Fetches new album releases user followed artists or globally | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `save()` | Saves the specified albums. Accepts a list of album IDs. | `void` |
| `unsave()` | Removes the specified albums from saved albums. Accepts a list of album IDs. | `void` |
{/* Urls */}
[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object
[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject
[SpotubeFullTrackObject]: /docs/models/spotube-track-object

56
website/src/content/docs/developing-plugins/artist-endpoint.mdx
View File

@ -1,56 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The ArtistEndpoint
description: ""
order: 7
---
The ArtistEndpoint is used to fetch artist information and do artist-related actions. In the `src/segments/artist.ht` file you can find all the
required method definitions.
```hetu_script
class ArtistEndpoint {
var client: HttpClient
construct (this.client)
fun getArtist(id: string) {
// TODO: Implement method
}
fun related(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun topTracks(id: string, {limit: int, offset: int}) {
// TODO: Implement method
}
fun albums(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun save(artistIds: List) {
// TODO: Implement method
}
fun unsave(artistIds: List) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `getArtist()` | Fetches artist information by ID. | [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `related()` | Fetches related artists based on the specified artist ID. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `topTracks()` | Fetches top tracks of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `albums()` | Fetches albums of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `save()` | Saves the specified artists. Accepts a list of artist IDs. | `void` |
| `unsave()` | Removes the specified artists from saved artists. Accepts a list of artist IDs. | `void` |
{/* Urls */}
[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object
[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject
[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject
[SpotubeFullTrackObject]: /docs/models/spotube-track-object

72
website/src/content/docs/developing-plugins/auth-endpoint.mdx
View File

@ -1,72 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The AuthEndpoint
description: ""
order: 3
---
> If your plugin doesn't need authentication support, you can skip this section.
In the `src/segments/auth.ht` file you can find all the required method definition. These are the necessary
methods Spotube calls in it's lifecycle.
```hetu_script
class AuthEndpoint {
var client: HttpClient
final controller: StreamController
get authStateStream -> Stream => controller.stream
construct (this.client){
controller = StreamController.broadcast()
}
fun isAuthenticated() -> bool {
// TODO: Implement method
return false
}
fun authenticate() -> Future {
// TODO: Implement method
}
fun logout() -> Future {
// TODO: Implement method
}
}
```
For this specific endpoint, you may need `WebView` or `Forms` to get user inputs. The [`hetu_spotube_plugin`][hetu_spotube_plugin] provides
such APIs.
> Learn more about it in the [Spotube Plugin API][spotube_plugin_api] section
### The `.authStateStream` property
The `AuthEndpoint.authStateStream` property is also necessary to notify Spotube about the authentication status. [`hetu_std`][hetu_std] is a built-in
module and it exports `StreamController` which basically 1:1 copy of the Dart's [StreamController][dart_stream_controller].
If the status of authentication changes you need to add a new event using the `controller.add`
Following events are respected by Spotube:
| Name | Description |
| ----------- | ------------------------------------------------------------ |
| `login` | When user successfully completes login |
| `logout` | When user logs out of the service |
| `recovered` | When user's cached/saved credentials are recovered from disk |
| `refreshed` | When user's session is refreshed |
Example of adding a new authentication event:
```hetu_script
controller.add({ type: "login" }.toJson())
```
By the way, the event type is a `Map<String, dynamic>` in the Dart side, so make sure to always convert hetu_script's [structs into Maps][hetu_struct_into_map]
{/* Urls */}
[hetu_script_import_export_docs]: https://hetu-script.github.io/docs/en-US/grammar/import/
[hetu_spotube_plugin]: https://github.com/KRTirtho/hetu_spotube_plugin
[spotube_plugin_api]: /
[hetu_std]: https://github.com/hetu-community/hetu_std
[dart_stream_controller]: https://api.flutter.dev/flutter/dart-async/StreamController-class.html
[hetu_struct_into_map]: https://hetu-script.github.io/docs/en-US/api_reference/hetu/#struct

48
website/src/content/docs/developing-plugins/browse-endpoint.mdx
View File

@ -1,48 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The BrowseEndpoint
description: ""
order: 10
---
The BrowseEndpoint is used to fetch recommendations and catalogs of playlists, albums and artists. In the `src/segments/browse.ht` file you can find all the
required method definitions.
```hetu_script
class BrowseEndpoint {
var client: HttpClient
construct (this.client)
fun sections({offset: int, limit: int}) {
// TODO: Implement method
}
fun sectionItems(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `sections()` | Returns the sections of the home page. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeBrowseSectionObject`][SpotubeBrowseSectionObject] of `Object` |
| `sectionItems()` | Returns the items of a specific section. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of `Object` |
> In `sectionItems()` The `id` it takes comes from `sections()`. It is basically used in an expanded screen to show the browse section items with pagination.
>
> For sections returned by `sections()` if `browseMore` is `true` that's when `sectionItems()` is used to fetch the items of that section.
By the way, the `Object` can be any of the following types:
- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject]
- [`SpotubeFullArtistObject`][SpotubeFullArtistObject]
- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject]
{/* Urls */}
[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object
[SpotubeBrowseSectionObject]: /docs/models/spotube-browse-section-object
[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject
[SpotubeFullTrackObject]: /docs/models/spotube-track-object
[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject
[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject

68
website/src/content/docs/developing-plugins/core-endpoint.mdx
View File

@ -1,68 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The CoreEndpoint
description: ""
order: 11
---
The CoreEndpoint is a special subclass which is used to check update and scrobbling and to get support text. In the `src/segments/core.ht` file you can find all the
required method definitions.
```hetu_script
class CorePlugin {
var client: HttpClient
construct (this.client)
/// Checks for updates to the plugin.
/// [currentConfig] is just plugin.json's file content.
///
/// If there's an update available, it will return a map of:
/// - [downloadUrl] -> direct download url to the new plugin.smplug file.
/// - [version] of the new plugin.
/// - [changelog] Optionally, a changelog for the update (markdown supported).
///
/// If no update is available, it will return null.
fun checkUpdate(currentConfig: Map) -> Future {
// TODO: Check for updates
}
/// Returns the support information for the plugin in Markdown or plain text.
/// Supports images and links.
get support -> string {
// TODO: Return support information
return ""
}
/// Scrobble the provided details to the scrobbling service supported by the plugin.
/// "scrobbling" must be set as an ability in the plugin.json
/// [details] is a map containing the scrobble information, such as:
/// - [id] -> The unique identifier of the track.
/// - [title] -> The title of the track.
/// - [artists] -> List of artists
/// - [id] -> The unique identifier of the artist.
/// - [name] -> The name of the artist.
/// - [album] -> The album of the track
/// - [id] -> The unique identifier of the album.
/// - [name] -> The name of the album.
/// - [timestamp] -> The timestamp of the scrobble (optional).
/// - [duration_ms] -> The duration of the track in milliseconds (optional).
/// - [isrc] -> The ISRC code of the track (optional).
fun scrobble(details: Map) {
// TODO: Implement scrobbling
}
}
```
| Method | Description | Returns |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `checkUpdate()` | Checks for updates to the plugin. | `Future` with a map containing `downloadUrl`, `version`, and optionally `changelog`. If no update is available, returns `null`. |
| `support` | Returns support information. | `string` containing the support information in Markdown or plain text. |
| `scrobble()` | [Scrobbles][scrobbling_wiki] the provided track details. This is only called if your plugin.json has scrobbling in the `abilities` field | `void` |
> In the `checkUpdate()` method the `plugin.json`'s content will be passed as map. You can use that to check updates using the `version` field.
>
> Also, the `downloadUrl` it provides should be a direct binary download link (redirect is supported) for the `.smplug` file
{/* Urls */}
[scrobbling_wiki]: https://en.wikipedia.org/wiki/Last.fm

493
website/src/content/docs/developing-plugins/implementing-endpoints.mdx Normal file
View File

@ -0,0 +1,493 @@
---
layout: "layouts/DocLayout.astro"
title: Implementing Endpoints
description: ""
order: 2
---
## AuthEndpoint
> If your plugin doesn't need authentication support, you can skip this section.
In the `src/segments/auth.ht` file you can find all the required method definition. These are the necessary
methods Spotube calls in it's lifecycle.
```hetu_script
class AuthEndpoint {
var client: HttpClient
final controller: StreamController
get authStateStream -> Stream => controller.stream
construct (this.client){
controller = StreamController.broadcast()
}
fun isAuthenticated() -> bool {
// TODO: Implement method
return false
}
fun authenticate() -> Future {
// TODO: Implement method
}
fun logout() -> Future {
// TODO: Implement method
}
}
```
For this specific endpoint, you may need `WebView` or `Forms` to get user inputs. The [`hetu_spotube_plugin`][hetu_spotube_plugin] provides
such APIs.
> Learn more about it in the [Spotube Plugin API][spotube_plugin_api] section
### The `.authStateStream` property
The `AuthEndpoint.authStateStream` property is also necessary to notify Spotube about the authentication status. [`hetu_std`][hetu_std] is a built-in
module and it exports `StreamController` which basically 1:1 copy of the Dart's [StreamController][dart_stream_controller].
If the status of authentication changes you need to add a new event using the `controller.add`
Following events are respected by Spotube:
| Name | Description |
| ----------- | ------------------------------------------------------------ |
| `login` | When user successfully completes login |
| `logout` | When user logs out of the service |
| `recovered` | When user's cached/saved credentials are recovered from disk |
| `refreshed` | When user's session is refreshed |
Example of adding a new authentication event:
```hetu_script
controller.add({ type: "login" }.toJson())
```
By the way, the event type is a `Map<String, dynamic>` in the Dart side, so make sure to always convert hetu_script's [structs into Maps][hetu_struct_into_map]
## UserEndpoint
The UserEndpoint is used to fetch user information and manage user-related actions.
In the `src/segments/user.ht` file you can find all the required method definitions. These are the necessary
methods Spotube calls in its lifecycle.
> Most of these methods should be just a mapping to an API call with minimum latency. Avoid calling plugin APIs like WebView or Forms
> in these methods. User interactions should be avoided here generally.
```hetu_script
class UserEndpoint {
var client: HttpClient
construct (this.client)
fun me() {
// TODO: Implement method
}
fun savedTracks({ offset: int, limit: int }) {
// TODO: Implement method
}
fun savedPlaylists({ offset: int, limit: int }) {
// TODO: Implement method
}
fun savedAlbums({ offset: int, limit: int }) {
// TODO: Implement method
}
fun savedArtists({ offset: int, limit: int }) {
// TODO: Implement method
}
fun isSavedPlaylist(playlistId: string) { // Future<bool>
// TODO: Implement method
}
fun isSavedTracks(trackIds: List) { // Future<List<bool>>
// TODO: Implement method
}
fun isSavedAlbums(albumIds: List) { // Future<List<bool>>
// TODO: Implement method
}
fun isSavedArtists(artistIds: List) { // Future<List<bool>>
// TODO: Implement method
}
}
```
These methods are pretty self-explanatory. You need to implement them to fetch user information from your service.
| Method | Description | Returns |
| ------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `me()` | Fetches the current user's information. | [`SpotubeUserObject`][SpotubeUserObject] |
| `savedTracks()` | Fetches the user's saved tracks with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `savedPlaylists()` | Fetches the user's saved playlists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
| `savedAlbums()` | Fetches the user's saved albums with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `savedArtists()` | Fetches the user's saved artists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `isSavedPlaylist()` | Checks if a playlist is saved by the user. Returns a `Future<bool>`. | `bool` |
| `isSavedTracks()` | Checks if tracks are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to a track ID) |
| `isSavedAlbums()` | Checks if albums are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to an album ID) |
| `isSavedArtists()` | Checks if artists are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to an artist ID) |
> Note: The `isSavedTracks`, `isSavedAlbums`, and `isSavedArtists` methods accept a list of IDs and return a list of booleans
> indicating whether each item is saved by the user. The order of the booleans in the list corresponds to the order of the IDs
> in the input list.
## TrackEndpoint
The TrackEndpoint is used to fetch track information and do track-related actions. In the `src/segments/track.ht` file you can find all the
required method definitions.
```hetu_script
class TrackEndpoint {
var client: HttpClient
construct (this.client)
fun getTrack(id: string) {
// TODO: Implement method
}
fun save(trackIds: List) { // List<String>
// TODO: Implement method
}
fun unsave(trackIds: List) { // List<String>
// TODO: Implement method
}
fun radio(id: string) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `getTrack()` | Fetches track information by ID. | [SpotubeFullTrackObject][SpotubeFullTrackObject] |
| `save()` | Saves the specified tracks. Accepts a list of track IDs. | void |
| `unsave()` | Removes the specified tracks from saved tracks. Accepts a list of track IDs. | void |
| `radio()` | Fetches related tracks based on specified tracks. Try to return a List of 50 tracks. | [List\<SpotubeFullTrackObject\>][SpotubeFullTrackObject] |
{/* Urls */}
## AlbumEndpoint
The AlbumEndpoint is used to fetch album information and do album-related actions. In the `src/segments/album.ht` file you can find all the
required method definitions.
```hetu_script
class AlbumEndpoint {
construct (this.client)
fun getAlbum(id: string) {
// TODO: Implement method
}
fun tracks(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun releases({offset: int, limit: int}) {
// TODO: Implement method
}
fun save(albumIds: List) { // List<String>
// TODO: Implement method
}
fun unsave(albumIds: List) { // List<String>
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------ | ---------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `getAlbum()` | Fetches album information by ID. | [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `tracks()` | Fetches tracks of the specified album. Accepts an ID and optional pagination parameters. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `releases()` | Fetches new album releases user followed artists or globally | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `save()` | Saves the specified albums. Accepts a list of album IDs. | `void` |
| `unsave()` | Removes the specified albums from saved albums. Accepts a list of album IDs. | `void` |
## ArtistEndpoint
The ArtistEndpoint is used to fetch artist information and do artist-related actions. In the `src/segments/artist.ht` file you can find all the
required method definitions.
```hetu_script
class ArtistEndpoint {
var client: HttpClient
construct (this.client)
fun getArtist(id: string) {
// TODO: Implement method
}
fun related(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun topTracks(id: string, {limit: int, offset: int}) {
// TODO: Implement method
}
fun albums(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun save(artistIds: List) {
// TODO: Implement method
}
fun unsave(artistIds: List) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `getArtist()` | Fetches artist information by ID. | [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `related()` | Fetches related artists based on the specified artist ID. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `topTracks()` | Fetches top tracks of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `albums()` | Fetches albums of the specified artist. Accepts optional pagination. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `save()` | Saves the specified artists. Accepts a list of artist IDs. | `void` |
| `unsave()` | Removes the specified artists from saved artists. Accepts a list of artist IDs. | `void` |
## PlaylistEndpoint
The PlaylistEndpoint is used to fetch playlist information and do track-related actions. In the `src/segments/playlist.ht` file you can find all the
required method definitions.
```hetu_script
class PlaylistEndpoint {
var client: HttpClient
construct (this.client)
fun getPlaylist(id: string) {
// TODO: Implement method
}
fun tracks(id: string, { offset: int, limit: int }) {
// TODO: Implement method
}
fun create(userId: string, {
name: string,
description: string,
public: bool,
collaborative: bool
}) {
// TODO: Implement method
}
fun update(playlistId: string, {
name: string,
description: string,
public: bool,
collaborative: bool
}) {
// TODO: Implement method
}
fun deletePlaylist(playlistId: string) {
// TODO: Implement method
}
fun addTracks(playlistId: string, { trackIds: List, position: int }) {
// TODO: Implement method
}
fun removeTracks(playlistId: string, { trackIds: List }) {
// TODO: Implement method
}
fun save(playlistId: string) {
// TODO: Implement method
}
fun unsave(playlistId: string) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `getPlaylist` | Fetches a playlist by its ID. | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
| `tracks` | Fetches tracks in a playlist. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `create` | Creates a new playlist and returns | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
| `update` | Updates an existing playlist. | `void` |
| `deletePlaylist` | Deletes a playlist. | `void` |
| `addTracks` | Adds tracks to a playlist. | `void` |
| `removeTracks` | Removes tracks from a playlist. | `void` |
| `save` | Saves a playlist to the user's library. | `void` |
| `unsave` | Removes a playlist from the user's library. | `void` |
## SearchEndpoint
The SearchEndpoint is used to fetch search playlist, tracks, album and artists. In the `src/segments/search.ht` file you can find all the
required method definitions.
```hetu_script
class SearchEndpoint {
var client: HttpClient
construct (this.client)
get chips -> List { // Set<string>
// can be tracks, playlists, artists, albums and all
return ["all", "tracks", "albums", "artists", "playlists"]
}
fun all(query: string) {
// TODO: Implement method
}
fun albums(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun artists(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun tracks(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun playlists(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `chips` | Returns the available search chips. | `List<string>` |
| `all()` | Searches for all types of content. | [`SpotubeSearchResponseObject`][SpotubeSearchResponseObject] |
| `albums()` | Searches only for albums. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `artists()` | Searches only for artists. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `tracks()` | Searches only for tracks. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `playlists()` | Searches only for playlists. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
## BrowseEndpoint
The BrowseEndpoint is used to fetch recommendations and catalogs of playlists, albums and artists. In the `src/segments/browse.ht` file you can find all the
required method definitions.
```hetu_script
class BrowseEndpoint {
var client: HttpClient
construct (this.client)
fun sections({offset: int, limit: int}) {
// TODO: Implement method
}
fun sectionItems(id: string, {offset: int, limit: int}) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ---------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `sections()` | Returns the sections of the home page. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeBrowseSectionObject`][SpotubeBrowseSectionObject] of `Object` |
| `sectionItems()` | Returns the items of a specific section. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of `Object` |
> In `sectionItems()` The `id` it takes comes from `sections()`. It is basically used in an expanded screen to show the browse section items with pagination.
>
> For sections returned by `sections()` if `browseMore` is `true` that's when `sectionItems()` is used to fetch the items of that section.
By the way, the `Object` can be any of the following types:
- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject]
- [`SpotubeFullArtistObject`][SpotubeFullArtistObject]
- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject]
## CoreEndpoint
The CoreEndpoint is a special subclass which is used to check update and scrobbling and to get support text. In the `src/segments/core.ht` file you can find all the
required method definitions.
```hetu_script
class CorePlugin {
var client: HttpClient
construct (this.client)
/// Checks for updates to the plugin.
/// [currentConfig] is just plugin.json's file content.
///
/// If there's an update available, it will return a map of:
/// - [downloadUrl] -> direct download url to the new plugin.smplug file.
/// - [version] of the new plugin.
/// - [changelog] Optionally, a changelog for the update (markdown supported).
///
/// If no update is available, it will return null.
fun checkUpdate(currentConfig: Map) -> Future {
// TODO: Check for updates
}
/// Returns the support information for the plugin in Markdown or plain text.
/// Supports images and links.
get support -> string {
// TODO: Return support information
return ""
}
/// Scrobble the provided details to the scrobbling service supported by the plugin.
/// "scrobbling" must be set as an ability in the plugin.json
/// [details] is a map containing the scrobble information, such as:
/// - [id] -> The unique identifier of the track.
/// - [title] -> The title of the track.
/// - [artists] -> List of artists
/// - [id] -> The unique identifier of the artist.
/// - [name] -> The name of the artist.
/// - [album] -> The album of the track
/// - [id] -> The unique identifier of the album.
/// - [name] -> The name of the album.
/// - [timestamp] -> The timestamp of the scrobble (optional).
/// - [duration_ms] -> The duration of the track in milliseconds (optional).
/// - [isrc] -> The ISRC code of the track (optional).
fun scrobble(details: Map) {
// TODO: Implement scrobbling
}
}
```
| Method | Description | Returns |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `checkUpdate()` | Checks for updates to the plugin. | `Future` with a map containing `downloadUrl`, `version`, and optionally `changelog`. If no update is available, returns `null`. |
| `support` | Returns support information. | `string` containing the support information in Markdown or plain text. |
| `scrobble()` | [Scrobbles][scrobbling_wiki] the provided track details. This is only called if your plugin.json has scrobbling in the `abilities` field | `void` |
> In the `checkUpdate()` method the `plugin.json`'s content will be passed as map. You can use that to check updates using the `version` field.
>
> Also, the `downloadUrl` it provides should be a direct binary download link (redirect is supported) for the `.smplug` file
{/* Urls */}
[scrobbling_wiki]: https://en.wikipedia.org/wiki/Last.fm
[hetu_script_import_export_docs]: https://hetu-script.github.io/docs/en-US/grammar/import/
[hetu_spotube_plugin]: https://github.com/KRTirtho/hetu_spotube_plugin
[spotube_plugin_api]: /
[hetu_std]: https://github.com/hetu-community/hetu_std
[dart_stream_controller]: https://api.flutter.dev/flutter/dart-async/StreamController-class.html
[hetu_struct_into_map]: https://hetu-script.github.io/docs/en-US/api_reference/hetu/#struct
[SpotubeUserObject]: /docs/reference/models#user
[SpotubePaginationResponseObject]: /docs/reference/models#pagination-response
[SpotubeFullAlbumObject]: /docs/reference/models#spotubefullalbumobject
[SpotubeFullArtistObject]: /docs/reference/models#spotubefullartistobject
[SpotubeFullTrackObject]: /docs/reference/models#track
[SpotubeFullPlaylistObject]: /docs/reference/models#spotubefullplaylistobject
[SpotubeSearchResponseObject]: /docs/reference/models#search-response
[SpotubeBrowseSectionObject]: /docs/reference/models#browse-section

81
website/src/content/docs/developing-plugins/playlist-endpoint.mdx
View File

@ -1,81 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The PlaylistEndpoint
description: ""
order: 8
---
The PlaylistEndpoint is used to fetch playlist information and do track-related actions. In the `src/segments/playlist.ht` file you can find all the
required method definitions.
```hetu_script
class PlaylistEndpoint {
var client: HttpClient
construct (this.client)
fun getPlaylist(id: string) {
// TODO: Implement method
}
fun tracks(id: string, { offset: int, limit: int }) {
// TODO: Implement method
}
fun create(userId: string, {
name: string,
description: string,
public: bool,
collaborative: bool
}) {
// TODO: Implement method
}
fun update(playlistId: string, {
name: string,
description: string,
public: bool,
collaborative: bool
}) {
// TODO: Implement method
}
fun deletePlaylist(playlistId: string) {
// TODO: Implement method
}
fun addTracks(playlistId: string, { trackIds: List, position: int }) {
// TODO: Implement method
}
fun removeTracks(playlistId: string, { trackIds: List }) {
// TODO: Implement method
}
fun save(playlistId: string) {
// TODO: Implement method
}
fun unsave(playlistId: string) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ---------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `getPlaylist` | Fetches a playlist by its ID. | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
| `tracks` | Fetches tracks in a playlist. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `create` | Creates a new playlist and returns | [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
| `update` | Updates an existing playlist. | `void` |
| `deletePlaylist` | Deletes a playlist. | `void` |
| `addTracks` | Adds tracks to a playlist. | `void` |
| `removeTracks` | Removes tracks from a playlist. | `void` |
| `save` | Saves a playlist to the user's library. | `void` |
| `unsave` | Removes a playlist from the user's library. | `void` |
{/* Urls */}
[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object
[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject
[SpotubeFullTrackObject]: /docs/models/spotube-track-object

59
website/src/content/docs/developing-plugins/search-endpoint.mdx
View File

@ -1,59 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The SearchEndpoint
description: ""
order: 9
---
The SearchEndpoint is used to fetch search playlist, tracks, album and artists. In the `src/segments/search.ht` file you can find all the
required method definitions.
```hetu_script
class SearchEndpoint {
var client: HttpClient
construct (this.client)
get chips -> List { // Set<string>
// can be tracks, playlists, artists, albums and all
return ["all", "tracks", "albums", "artists", "playlists"]
}
fun all(query: string) {
// TODO: Implement method
}
fun albums(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun artists(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun tracks(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
fun playlists(query: string, {offset: int, limit: int}) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------- | ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `chips` | Returns the available search chips. | `List<string>` |
| `all()` | Searches for all types of content. | [`SpotubeSearchResponseObject`][SpotubeSearchResponseObject] |
| `albums()` | Searches only for albums. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `artists()` | Searches only for artists. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `tracks()` | Searches only for tracks. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `playlists()` | Searches only for playlists. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
{/* Urls */}
[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object
[SpotubeSearchResponseObject]: /docs/models/spotube-search-response-object
[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject
[SpotubeFullTrackObject]: /docs/models/spotube-track-object
[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject
[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject

43
website/src/content/docs/developing-plugins/track-endpoint.mdx
View File

@ -1,43 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The TrackEndpoint
description: ""
order: 5
---
The TrackEndpoint is used to fetch track information and do track-related actions. In the `src/segments/track.ht` file you can find all the
required method definitions.
```hetu_script
class TrackEndpoint {
var client: HttpClient
construct (this.client)
fun getTrack(id: string) {
// TODO: Implement method
}
fun save(trackIds: List) { // List<String>
// TODO: Implement method
}
fun unsave(trackIds: List) { // List<String>
// TODO: Implement method
}
fun radio(id: string) {
// TODO: Implement method
}
}
```
| Method | Description | Returns |
| ------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------- |
| `getTrack()` | Fetches track information by ID. | [SpotubeFullTrackObject][SpotubeFullTrackObject] |
| `save()` | Saves the specified tracks. Accepts a list of track IDs. | void |
| `unsave()` | Removes the specified tracks from saved tracks. Accepts a list of track IDs. | void |
| `radio()` | Fetches related tracks based on specified tracks. Try to return a List of 50 tracks. | [List\<SpotubeFullTrackObject\>][SpotubeFullTrackObject] |
{/* Urls */}
[SpotubeFullTrackObject]: /docs/models/spotube-track-object

83
website/src/content/docs/developing-plugins/user-endpoint.mdx
View File

@ -1,83 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: The UserEndpoint
description: ""
order: 4
---
The UserEndpoint is used to fetch user information and manage user-related actions.
In the `src/segments/user.ht` file you can find all the required method definitions. These are the necessary
methods Spotube calls in its lifecycle.
> Most of these methods should be just a mapping to an API call with minimum latency. Avoid calling plugin APIs like WebView or Forms
> in these methods. User interactions should be avoided here generally.
```hetu_script
class UserEndpoint {
var client: HttpClient
construct (this.client)
fun me() {
// TODO: Implement method
}
fun savedTracks({ offset: int, limit: int }) {
// TODO: Implement method
}
fun savedPlaylists({ offset: int, limit: int }) {
// TODO: Implement method
}
fun savedAlbums({ offset: int, limit: int }) {
// TODO: Implement method
}
fun savedArtists({ offset: int, limit: int }) {
// TODO: Implement method
}
fun isSavedPlaylist(playlistId: string) { // Future<bool>
// TODO: Implement method
}
fun isSavedTracks(trackIds: List) { // Future<List<bool>>
// TODO: Implement method
}
fun isSavedAlbums(albumIds: List) { // Future<List<bool>>
// TODO: Implement method
}
fun isSavedArtists(artistIds: List) { // Future<List<bool>>
// TODO: Implement method
}
}
```
These methods are pretty self-explanatory. You need to implement them to fetch user information from your service.
| Method | Description | Returns |
| ------------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `me()` | Fetches the current user's information. | [`SpotubeUserObject`][SpotubeUserObject] |
| `savedTracks()` | Fetches the user's saved tracks with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
| `savedPlaylists()` | Fetches the user's saved playlists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject] |
| `savedAlbums()` | Fetches the user's saved albums with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject] |
| `savedArtists()` | Fetches the user's saved artists with pagination support. | [`SpotubePaginationResponseObject`][SpotubePaginationResponseObject] of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| `isSavedPlaylist()` | Checks if a playlist is saved by the user. Returns a `Future<bool>`. | `bool` |
| `isSavedTracks()` | Checks if tracks are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to a track ID) |
| `isSavedAlbums()` | Checks if albums are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to an album ID) |
| `isSavedArtists()` | Checks if artists are saved by the user. Returns a `Future<List<bool>>`. | `List<bool>` (each boolean corresponds to an artist ID) |
> Note: The `isSavedTracks`, `isSavedAlbums`, and `isSavedArtists` methods accept a list of IDs and return a list of booleans
> indicating whether each item is saved by the user. The order of the booleans in the list corresponds to the order of the IDs
> in the input list.
{/* Links */}
[SpotubeUserObject]: /docs/models/spotube-user-object
[SpotubePaginationResponseObject]: /docs/models/spotube-pagination-response-object
[SpotubeFullTrackObject]: /docs/models/spotube-track-object
[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject
[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject
[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject

42
website/src/content/docs/models/spotube-album-object.mdx
View File

@ -1,42 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Album
description: Different types of album objects used in Spotube.
order: 3
---
### SpotubeSimpleAlbumObject
Following is the structure of the `SpotubeAlbumObject`:
| Property | Type |
| ----------- | ---------------------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] |
| albumType | `album`, `single` or `compilation` |
| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] |
| releaseDate | `string` (YYYY-MM-DD format) or `null` |
{/* Urls */}
### SpotubeFullAlbumObject
Following is the structure of the `SpotubeFullAlbumObject`:
| Property | Type |
| ----------- | ---------------------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] |
| albumType | `album`, `single` or `compilation` |
| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] |
| releaseDate | `string` (YYYY-MM-DD format) |
| totalTracks | `number` |
| recordLabel | `string` or `null` |
{/* Urls */}
[SpotubeImageObject]: /docs/models/spotube-image-object
[SpotubeSimpleArtistObject]: /docs/models/spotube-artist-objects#spotubesimpleartistobject

33
website/src/content/docs/models/spotube-artist-object.mdx
View File

@ -1,33 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Artist
description: Different types of artist objects used in Spotube.
order: 2
---
### SpotubeSimpleArtistObject
Following is the structure of the `SpotubeArtistObject`:
| Property | Type |
| ----------- | ------------------------------------------------------------ |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` |
### SpotubeFullArtistObject
Following is the structure of the `SpotubeFullArtistObject`:
| Property | Type |
| ----------- | ----------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or |
| followers | `number` |
| genres | List of `string` or `null` |
{/* Urls */}
[SpotubeImageObject]: /docs/models/spotube-image-object

27
website/src/content/docs/models/spotube-browse-section-object.mdx
View File

@ -1,27 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Browse Section
description: ""
order: 7
---
Following is the structure of `SpotubeBrowseSectionObject`:
| Property | Type |
| ----------- | ---------------- |
| id | `string` |
| title | `string` |
| externalUri | `string` |
| browseMore | `boolean` |
| items | List of `Object` |
The `items` property array can contain multiple type of `Object` in it but it will always be
- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject]
- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject]
- [`SpotubeFullArtistObject`][SpotubeFullArtistObject]
{/* Urls */}
[SpotubeFullPlaylistObject]: /docs/models/spotube-playlist-object#spotubefullplaylistobject
[SpotubeFullAlbumObject]: /docs/models/spotube-album-object#spotubefullalbumobject
[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject

14
website/src/content/docs/models/spotube-image-object.mdx
View File

@ -1,14 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Image
description: How images are represented in Spotube.
order: 0
---
Following is the structure of the `SpotubeImageObject`:
| Property | Type |
| -------- | --------------- |
| width | `int` or `null` |
| height | `int` or `null` |
| url | `string` |

18
website/src/content/docs/models/spotube-pagination-response-object.mdx
View File

@ -1,18 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Pagination Response
description: ""
order: 8
---
`SpotubePaginationResponseObject` is generic model. The `items` property can contain any type of `Object` in it.
This is the structure of `SpotubePaginationResponseObject`:
| Property | Type |
| ---------- | ----------------------------------------------- |
| limit | `number` |
| nextOffset | `number` or `null` |
| total | `number` |
| hasMore | `boolean` |
| items | List of generic type `T` which extends `Object` |

40
website/src/content/docs/models/spotube-playlist-object.mdx
View File

@ -1,40 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Playlist
description: Different types of playlist objects used in Spotube.
order: 5
---
### SpotubeSimplePlaylistObject
Following is the structure of the `SpotubeSimplePlaylistObject`:
| Property | Type |
| ----------- | ------------------------------------------------------------ |
| id | `string` |
| name | `string` |
| description | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` |
| owner | [`SpotubeUserObject`][SpotubeUserObject] |
### SpotubeFullPlaylistObject
Following is the structure of the `SpotubeFullPlaylistObject`:
| Property | Type |
| ------------- | ------------------------------------------------------------ |
| id | `string` |
| name | `string` |
| description | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` |
| owner | [`SpotubeUserObject`][SpotubeUserObject] |
| collaborators | List of [`SpotubeUserObject`][SpotubeUserObject] or `null` |
| collaborative | `boolean` |
| public | `boolean` |
{/* Urls */}
[SpotubeImageObject]: /docs/models/spotube-image-object
[SpotubeUserObject]: /docs/models/spotube-simple-user-object

21
website/src/content/docs/models/spotube-search-response-object.mdx
View File

@ -1,21 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Search Response
description: ""
order: 6
---
Following is the structure of the `SpotubeSearchResponseObject`:
| Property | Type |
| --------- | -------------------------------------------------------------------- |
| albums | List of [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] |
| artists | List of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| playlists | List of [`SpotubeSimplePlaylistObject`][SpotubeSimplePlaylistObject] |
| tracks | List of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
{/* Urls */}
[SpotubeSimpleAlbumObject]: /docs/models/spotube-album-object#spotubesimplealbumobject
[SpotubeFullArtistObject]: /docs/models/spotube-artist-object#spotubefullartistobject
[SpotubeSimplePlaylistObject]: /docs/models/spotube-playlist-object#spotubesimpleplaylistobject
[SpotubeFullTrackObject]: /docs/models/spotube-track-object

27
website/src/content/docs/models/spotube-track-object.mdx
View File

@ -1,27 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: Track
description: ""
order: 4
---
Following is the structure of the `SpotubeFullTrackObject`:
| Property | Type |
| ---------------------------- | ---------------------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] |
| album | [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] |
| durationMs (in milliseconds) | `number` |
| explicit | `boolean` |
| [isrc][isrc_wiki] | `string` |
> `isrc` stands for International Standard Recording Code, which is a unique identifier for tracks.
> It is used to identify recordings and is often used in music distribution and royalty collection. The format is typically a 12-character alphanumeric code.
{/* Urls */}
[SpotubeSimpleArtistObject]: /docs/models/spotube-artist-objects#spotubesimpleartistobject
[SpotubeSimpleAlbumObject]: /docs/models/spotube-album-object#spotubesimplealbumobject
[isrc_wiki]: https://en.wikipedia.org/wiki/International_Standard_Recording_Code

20
website/src/content/docs/models/spotube-user-object.mdx
View File

@ -1,20 +0,0 @@
---
layout: "layouts/DocLayout.astro"
title: User
description: ""
order: 1
---
Structure of the SpotubeUserObject, which is used to represent a user in Spotube returned by Spotube Plugins.
| Property | Type |
| ----------- | -------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] |
> `externalUri` is a URL that points to the user's profile on the external service (e.g. Listenbrainz)
{/* Urls */}
[SpotubeImageObject]: /docs/models/spotube-image-object

190
website/src/content/docs/reference/models.mdx Normal file
View File

@ -0,0 +1,190 @@
---
layout: "layouts/DocLayout.astro"
title: Plugin Models
description: "Different types of objects used in Spotube."
order: 0
---
## Image
Following is the structure of the `SpotubeImageObject`:
| Property | Type |
| -------- | --------------- |
| width | `int` or `null` |
| height | `int` or `null` |
| url | `string` |
## User
Structure of the `SpotubeUserObject`, which is used to represent a user in Spotube returned by Spotube Plugins.
| Property | Type |
| ----------- | -------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] |
> `externalUri` is a URL that points to the user's profile on the external service (e.g. Listenbrainz)
## Artist
### SpotubeSimpleArtistObject
Following is the structure of the `SpotubeArtistObject`:
| Property | Type |
| ----------- | ------------------------------------------------------------ |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` |
### SpotubeFullArtistObject
Following is the structure of the `SpotubeFullArtistObject`:
| Property | Type |
| ----------- | ----------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or |
| followers | `number` |
| genres | List of `string` or `null` |
## Album
### SpotubeSimpleAlbumObject
Following is the structure of the `SpotubeAlbumObject`:
| Property | Type |
| ----------- | ---------------------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] |
| albumType | `album`, `single` or `compilation` |
| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] |
| releaseDate | `string` (YYYY-MM-DD format) or `null` |
### SpotubeFullAlbumObject
Following is the structure of the `SpotubeFullAlbumObject`:
| Property | Type |
| ----------- | ---------------------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] |
| albumType | `album`, `single` or `compilation` |
| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] |
| releaseDate | `string` (YYYY-MM-DD format) |
| totalTracks | `number` |
| recordLabel | `string` or `null` |
## Track
Following is the structure of the `SpotubeFullTrackObject`:
| Property | Type |
| ---------------------------- | ---------------------------------------------------------------- |
| id | `string` |
| name | `string` |
| externalUri | `string` |
| artists | List of [`SpotubeSimpleArtistObject`][SpotubeSimpleArtistObject] |
| album | [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] |
| durationMs (in milliseconds) | `number` |
| explicit | `boolean` |
| [isrc][isrc_wiki] | `string` |
> `isrc` stands for International Standard Recording Code, which is a unique identifier for tracks.
> It is used to identify recordings and is often used in music distribution and royalty collection. The format is typically a 12-character alphanumeric code.
## Playlist
### SpotubeSimplePlaylistObject
Following is the structure of the `SpotubeSimplePlaylistObject`:
| Property | Type |
| ----------- | ------------------------------------------------------------ |
| id | `string` |
| name | `string` |
| description | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` |
| owner | [`SpotubeUserObject`][SpotubeUserObject] |
### SpotubeFullPlaylistObject
Following is the structure of the `SpotubeFullPlaylistObject`:
| Property | Type |
| ------------- | ------------------------------------------------------------ |
| id | `string` |
| name | `string` |
| description | `string` |
| externalUri | `string` |
| images | List of [`SpotubeImageObject`][SpotubeImageObject] or `null` |
| owner | [`SpotubeUserObject`][SpotubeUserObject] |
| collaborators | List of [`SpotubeUserObject`][SpotubeUserObject] or `null` |
| collaborative | `boolean` |
| public | `boolean` |
## Search Response
Following is the structure of the `SpotubeSearchResponseObject`:
| Property | Type |
| --------- | -------------------------------------------------------------------- |
| albums | List of [`SpotubeSimpleAlbumObject`][SpotubeSimpleAlbumObject] |
| artists | List of [`SpotubeFullArtistObject`][SpotubeFullArtistObject] |
| playlists | List of [`SpotubeSimplePlaylistObject`][SpotubeSimplePlaylistObject] |
| tracks | List of [`SpotubeFullTrackObject`][SpotubeFullTrackObject] |
## Browse Section
Following is the structure of `SpotubeBrowseSectionObject`:
| Property | Type |
| ----------- | ---------------- |
| id | `string` |
| title | `string` |
| externalUri | `string` |
| browseMore | `boolean` |
| items | List of `Object` |
The `items` property array can contain multiple type of `Object` in it but it will always be
- [`SpotubeFullPlaylistObject`][SpotubeFullPlaylistObject]
- [`SpotubeFullAlbumObject`][SpotubeFullAlbumObject]
- [`SpotubeFullArtistObject`][SpotubeFullArtistObject]
## Pagination Response
`SpotubePaginationResponseObject` is generic model. The `items` property can contain any type of `Object` in it.
This is the structure of `SpotubePaginationResponseObject`:
| Property | Type |
| ---------- | ----------------------------------------------- |
| limit | `number` |
| nextOffset | `number` or `null` |
| total | `number` |
| hasMore | `boolean` |
| items | List of generic type `T` which extends `Object` |
[isrc_wiki]: https://en.wikipedia.org/wiki/International_Standard_Recording_Code
[SpotubeImageObject]: /docs/reference/models#image
[SpotubeSimpleArtistObject]: /docs/reference/models#spotubesimpleartistobject
[SpotubeSimpleAlbumObject]: /docs/reference/models#spotubesimplealbumobject
[SpotubeUserObject]: /docs/reference/models#user
[SpotubeFullArtistObject]: /docs/reference/models#spotubefullartistobject
[SpotubeSimplePlaylistObject]: /docs/reference/models#spotubesimpleplaylistobject
[SpotubeFullTrackObject]: /docs/reference/models#track
[SpotubeFullPlaylistObject]: /docs/reference/models#spotubefullplaylistobject
[SpotubeFullAlbumObject]: /docs/reference/models#spotubefullalbumobject