diff --git a/README.md b/README.md index 612d132..3ed9d78 100644 --- a/README.md +++ b/README.md @@ -116,13 +116,20 @@ to run the server in the foreground. ## How to scrobble -You can set up any amount of API keys in the file `authenticated_machines.tsv` in the `~/.local/share/maloja/clients` folder. +You can set up any amount of API keys in the file `authenticated_machines.tsv` in the `~/.local/share/maloja/clients` folder. It is recommended to define a different API key for every scrobbler you use. + +### Native support + +These solutions allow you to directly setup scrobbling to your Maloja server: +* [Tauon](https://tauonmusicbox.rocks) Desktop Player +* [Albula](https://github.com/krateng/albula) Music Server +* [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 use Plex Web, Spotify, Bandcamp, Soundcloud or Youtube Music on Chromium, you can use the included extension (also available on the [Chrome Web Store](https://chrome.google.com/webstore/detail/maloja-scrobbler/cfnbifdmgbnaalphodcbandoopgbfeeh)). Make sure to enter the random key Maloja generates on first startup in the extension settings. +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 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` - 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. ### Standard-compliant API @@ -140,11 +147,13 @@ API URL | Your Maloja URL followed by `/apis/listenbrainz` Username | Any name, doesn't matter (don't leave empty) Auth Token | Any of your API keys -My recommendations are to use [Pano Scrobbler](https://github.com/kawaiiDango/pScrobbler) for Android and [Web Scrobbler](https://github.com/web-scrobbler/web-scrobbler) for desktop browsers. Note that Web Scrobbler requires you to supply the full endpoint (`yoururl.tld/apis/listenbrainz/1/submit-listens`). +Known working scrobblers: +* [Pano Scrobbler](https://github.com/kawaiiDango/pScrobbler) for Android +* [Web Scrobbler](https://github.com/web-scrobbler/web-scrobbler) for desktop browsers (requires you to supply the full endpoint (`yoururl.tld/apis/listenbrainz/1/submit-listens`)) I'm thankful for any feedback whether other scrobblers work! -It is recommended to define a different API key for every scrobbler you use in `clients/authenticated_machines.tsv` in your Maloja folder. + ### Manual diff --git a/maloja/apis/native_v1.py b/maloja/apis/native_v1.py index d20f2cc..5e18da6 100644 --- a/maloja/apis/native_v1.py +++ b/maloja/apis/native_v1.py @@ -17,6 +17,12 @@ api.__apipath__ = "mlj_1" @api.get("test") def test_server(key=None): + """Pings the server. If an API key is supplied, the server will respond with 200 + if the key is correct and 403 if it isn't. If no key is supplied, the server will + always respond with 200. + + :param string key: An API key to be tested. Optional. + """ response.set_header("Access-Control-Allow-Origin","*") if key is not None and not (checkAPIkey(key)): response.status = 403 @@ -26,8 +32,6 @@ def test_server(key=None): response.status = 200 return {"status":"ok"} - # 200 Database server is up and operational - # 403 Database server is up, but provided API key is not valid @api.get("serverinfo") def server_info(): @@ -213,7 +217,7 @@ def post_scrobble(artist:Multi,**keys): :param string artist: Artists. Can be multiple. :param string title: Title of the track. - :param string album: Name of the album. + :param string album: Name of the album. Optional. :param int duration: Actual listened duration of the scrobble in seconds. Optional. :param int time: UNIX timestamp of the scrobble. Optional, not needed if scrobble is at time of request. """