From 528d3565b76ab5d389d551130197829aac807e29 Mon Sep 17 00:00:00 2001 From: krateng Date: Sat, 23 Apr 2022 14:38:18 +0200 Subject: [PATCH] Moved API information --- API.md | 70 +++++++++++++++++++++++++++++++++++++------------------ README.md | 51 ++-------------------------------------- 2 files changed, 49 insertions(+), 72 deletions(-) diff --git a/API.md b/API.md index d2717c3..5ef412a 100644 --- a/API.md +++ b/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. | - - - diff --git a/README.md b/README.md index 1ba0d76..5be8caf 100644 --- a/README.md +++ b/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.