mirror of
https://github.com/krateng/maloja.git
synced 2023-08-10 21:12:55 +03:00
Moved API information
This commit is contained in:
krateng
parent
56f7c18495
commit
528d3565b7
70
API.md
70
API.md
@ -1,9 +1,56 @@
|
||||
# Scrobbling
|
||||
|
||||
In order to scrobble from a wide selection of clients, you can use Maloja's standard-compliant APIs with the following settings:
|
||||
|
||||
GNU FM |
|
||||
------ | ---------
|
||||
Gnukebox URL | Your Maloja URL followed by `/apis/audioscrobbler`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
ListenBrainz |
|
||||
------ | ---------
|
||||
API URL | Your Maloja URL followed by `/apis/listenbrainz`
|
||||
Username | Doesn't matter
|
||||
Auth Token | Any of your API keys
|
||||
|
||||
Audioscrobbler v1.2 |
|
||||
------ | ---------
|
||||
Server URL | Your Maloja URL followed by `/apis/audioscrobbler_legacy`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
Note that this is the base URL - some scrobblers ask you for the full endpoint instead.
|
||||
|
||||
# API Documentation
|
||||
|
||||
The native Maloja API is reachable at `/apis/mlj_1`. Endpoints are listed on `/api_explorer`.
|
||||
|
||||
All endpoints return JSON data. POST request can be made with query string or form data arguments, but this is discouraged - JSON should be used whenever possible.
|
||||
|
||||
No application should ever rely on the non-existence of fields in the JSON data - i.e., additional fields can be added at any time without this being considered a breaking change. Existing fields should usually not be removed or changed, but it is always a good idea to add basic handling for missing fields.
|
||||
|
||||
## General Structure
|
||||
|
||||
Most endpoints follow this structure:
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `status` | String | Status of the request. Can be `success`, `ok`, `error`, `failure`, `no_operation` |
|
||||
| `error` | Mapping | Details about the error if one occured. |
|
||||
| `warnings` | List | Any warnings that did not result in failure, but should be noted. Field is omitted if there are no warnings! |
|
||||
| `desc` | String | Human-readable feedback. This can be shown directly to the user if desired. |
|
||||
|
||||
Both errors and warnings have the following structure:
|
||||
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `type` | String | Name of the error or warning type |
|
||||
| `value` | varies | Specific data for this error or warning instance |
|
||||
| `desc` | String | Human-readable error or warning description. This can be shown directly to the user if desired. |
|
||||
|
||||
|
||||
## Entity Structure
|
||||
|
||||
Whenever a list of entities is returned, they have the following fields:
|
||||
@ -59,26 +106,3 @@ Artists are just represented as raw Strings.
|
||||
```json
|
||||
"Red Velvet"
|
||||
```
|
||||
|
||||
## General Structure
|
||||
|
||||
Most endpoints follow this structure:
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `status` | String | Status of the request. Can be `success`, `ok`, `error`, `failure`, `no_operation` |
|
||||
| `error` | Mapping | Details about the error if one occured. |
|
||||
| `warnings` | List | Any warnings that did not result in failure, but should be noted. Field is omitted if there are no warnings! |
|
||||
| `desc` | String | Human-readable feedback. This can be shown directly to the user if desired. |
|
||||
|
||||
Both errors and warnings have the following structure:
|
||||
|
||||
|
||||
| Key | Type | Description |
|
||||
| --- | --- | --- |
|
||||
| `type` | String | Name of the error or warning type |
|
||||
| `value` | varies | Specific data for this error or warning instance |
|
||||
| `desc` | String | Human-readable error or warning description. This can be shown directly to the user if desired. |
|
||||
|
||||
|
||||
|
||||
|
||||
51
README.md
51
README.md
@ -156,56 +156,9 @@ To backup your data, run `maloja backup`, optional with `--include_images`.
|
||||
|
||||
You can set up any amount of API keys in the file `apikeys.yml` in your configuration folder (or via the web interface). It is recommended to define a different API key for every scrobbler you use.
|
||||
|
||||
### Native support
|
||||
Some scrobbler clients support Maloja's native API. You can also use any scrobbler that allows you to set a custom Listenbrainz or GNUFM server. See [API.md](API.md) for details.
|
||||
|
||||
These solutions allow you to directly setup scrobbling to your Maloja server:
|
||||
* [Tauon](https://tauonmusicbox.rocks) Desktop Player
|
||||
* [Web Scrobbler](https://github.com/web-scrobbler/web-scrobbler) Browser Extension
|
||||
* [Multi Scrobbler](https://github.com/FoxxMD/multi-scrobbler) Desktop Application
|
||||
* [Cmus-maloja-scrobbler](https://git.sr.ht/~xyank/cmus-maloja-scrobbler) Script
|
||||
* [OngakuKiroku](https://github.com/Atelier-Shiori/OngakuKiroku) Desktop Application (Mac)
|
||||
* [Maloja Scrobbler](https://chrome.google.com/webstore/detail/maloja-scrobbler/cfnbifdmgbnaalphodcbandoopgbfeeh) Chromium Extension (also included in the repository) for Plex Web, Spotify, Bandcamp, Soundcloud or Youtube Music
|
||||
|
||||
### Native API
|
||||
|
||||
If you want to implement your own method of scrobbling, it's very simple: You only need one POST request to `/apis/mlj_1/newscrobble` with the keys `artist`, `title` and `key` (and optionally `album`,`duration` (in seconds) and `time`(for cached scrobbles)) - either as form-data or json.
|
||||
|
||||
If you're the maintainer of a music player or server and would like to implement native Maloja scrobbling, feel free to reach out - I'll try my best to help. For Python applications, you can simply use the [`malojalib` package](https://pypi.org/project/maloja-lib/) for a consistent interface even with future updates.
|
||||
|
||||
### Standard-compliant API
|
||||
|
||||
You can use any third-party scrobbler that supports the audioscrobbler (GNUFM) or the ListenBrainz protocol. This is still somewhat experimental, but give it a try with these settings:
|
||||
|
||||
GNU FM |
|
||||
------ | ---------
|
||||
Gnukebox URL | Your Maloja URL followed by `/apis/audioscrobbler`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
ListenBrainz |
|
||||
------ | ---------
|
||||
API URL | Your Maloja URL followed by `/apis/listenbrainz`
|
||||
Username | Doesn't matter
|
||||
Auth Token | Any of your API keys
|
||||
|
||||
Audioscrobbler v1.2 |
|
||||
------ | ---------
|
||||
Server URL | Your Maloja URL followed by `/apis/audioscrobbler_legacy`
|
||||
Username | Doesn't matter
|
||||
Password | Any of your API keys
|
||||
|
||||
Known working scrobblers:
|
||||
* [Pano Scrobbler](https://github.com/kawaiiDango/pScrobbler) for Android
|
||||
* [Simple Scrobbler](https://simple-last-fm-scrobbler.github.io) for Android
|
||||
* [Airsonic Advanced](https://github.com/airsonic-advanced/airsonic-advanced) (requires you to supply the full endpoint (`yoururl.tld/apis/listenbrainz/1/submit-listens`))
|
||||
* [Funkwhale](https://dev.funkwhale.audio/funkwhale/funkwhale) (use the legacy API `yoururl.tld/apis/audioscrobbler_legacy`)
|
||||
* [mpdscribble](https://github.com/MusicPlayerDaemon/mpdscribble) (use the legacy API `yoururl.tld/apis/audioscrobbler_legacy`)
|
||||
|
||||
I'm thankful for any feedback whether other scrobblers work!
|
||||
|
||||
|
||||
|
||||
### Manual
|
||||
If you're the maintainer of a music player or server and would like to implement native Maloja scrobbling, feel free to reach out!
|
||||
|
||||
If you can't automatically scrobble your music, you can always do it manually on the `/admin_manual` page of your Maloja server.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user