mirror of
https://github.com/KRTirtho/spotube.git
synced 2025-09-13 07:55:18 +00:00
docs: add detailed documentation for BrowseEndpoint, CoreEndpoint, and SearchEndpoint
This commit is contained in:
Kingkor Roy Tirtho
parent
8bdbe7dfba
commit
fbd7b771ef
@ -0,0 +1,48 @@
|
|||||||
|
---
|
||||||
|
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]: /models/spotube-pagination-response-object
|
||||||
|
[SpotubeBrowseSectionObject]: /models/spotube-browse-section-object
|
||||||
|
[SpotubeFullPlaylistObject]: /models/spotube-full-playlist-object
|
||||||
|
[SpotubeFullTrackObject]: /models/spotube-full-track-object
|
||||||
|
[SpotubeFullArtistObject]: /models/spotube-full-artist-object
|
||||||
|
[SpotubeFullAlbumObject]: /models/spotube-full-album-object
|
||||||
@ -0,0 +1,74 @@
|
|||||||
|
---
|
||||||
|
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 */}
|
||||||
|
[SpotubePaginationResponseObject]: /models/spotube-pagination-response-object
|
||||||
|
[SpotubeBrowseSectionObject]: /models/spotube-browse-section-object
|
||||||
|
[SpotubeFullPlaylistObject]: /models/spotube-full-playlist-object
|
||||||
|
[SpotubeFullTrackObject]: /models/spotube-full-track-object
|
||||||
|
[SpotubeFullArtistObject]: /models/spotube-full-artist-object
|
||||||
|
[SpotubeFullAlbumObject]: /models/spotube-full-album-object
|
||||||
|
[scrobbling_wiki]: https://en.wikipedia.org/wiki/Last.fm
|
||||||
@ -0,0 +1,59 @@
|
|||||||
|
---
|
||||||
|
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]: /models/spotube-pagination-response-object
|
||||||
|
[SpotubeSearchResponseObject]: /models/spotube-search-response-object
|
||||||
|
[SpotubeFullPlaylistObject]: /models/spotube-full-playlist-object
|
||||||
|
[SpotubeFullTrackObject]: /models/spotube-full-track-object
|
||||||
|
[SpotubeFullArtistObject]: /models/spotube-full-artist-object
|
||||||
|
[SpotubeFullAlbumObject]: /models/spotube-full-album-object
|
||||||
Loading…
Reference in New Issue
Block a user