Scrobbling

Scrobbling can be done with the native API, see below. In order to scrobble from a wide selection of clients, you can also 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 these are the base URLs - some scrobblers ask you for the full endpoint instead.

Scrobbling Guideline

Maloja makes no assumptions about scrobbling behaviour. The clients should decide when and whether a play is scrobbled - the server will accept it as long as it contains all necessary data. However, a general guideline is:

As soon as a track has been played for 50% of its length or 4 minutes, it should be counted as a scrobble
That scrobble should be submitted when the play has ended in order to know its duration
If the total play duration is enough to count as a scrobble, but not longer than the total track length + enough for a second scrobble, it should be submitted as a scrobble with the according duration
If the duration exceeds this value, the first scrobble should be submitted as a scrobble with the duration of the full track length, while the second scrobble is queued up following the above suggestions in regards to remaining time

📝 Example

The user starts playing '(Fine Layers of) Slaysenflite', which is exactly 3:00 minutes long.

If the user ends the play after 1:22, no scrobble is submitted
If the user ends the play after 2:06, a scrobble with "duration":126 is submitted
If the user jumps back several times and ends the play after 3:57, a scrobble with "duration":237 is submitted
If the user jumps back several times and ends the play after 4:49, two scrobbles with "duration":180 and "duration":109 are submitted

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.

Submitting a Scrobble

The POST endpoint /newscrobble is used to submit new scrobbles. These use a flat JSON structure with the following fields:

Key	Type	Description
`artists`	List(String)	Track artists
`title`	String	Track title
`album`	String	Name of the album (Optional)
`albumartists`	List(String)	Album artists (Optional)
`duration`	Integer	How long the song was listened to in seconds (Optional)
`length`	Integer	Actual length of the full song in seconds (Optional)
`time`	Integer	Timestamp of the listen if it was not at the time of submitting (Optional)
`nofix`	Boolean	Skip server-side metadata fixing (Optional)

General Structure

The API is not fully consistent in order to ensure backwards-compatibility. Refer to the individual endpoints.
Generally, 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.
`list`	List	List of returned entities

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:

Scrobble

Key	Type	Description
`time`	Integer	Timestamp of the Scrobble in UTC
`track`	Mapping	The track being scrobbled
`duration`	Integer	How long the track was played for in seconds
`origin`	String	Client that submitted the scrobble, or import source

📝 Example

{
  "time": 1650684324,
  "track": {
    "artists": ["Jennie Kim","HyunA","LE","SunMi"],
    "title": "Wow Thing",
    "length":200
  },
  "duration": 196,
  "origin": "client:navidrome_desktop"
}

Track

Key	Type	Description
`artists`	List	The artists credited with the track
`title`	String	The title of the track
`length`	Integer	The full length of the track in seconds

📝 Example

{
  "artists": ["Blackpink","Chou Tzuyu"],
  "title": "MORE",
  "length": 171
}

Artist

Artists are just represented as raw Strings.

Example

📝 Example

"Red Velvet"

5.9 KiB Raw Blame History

Scrobbling

Scrobbling Guideline

API Documentation

Submitting a Scrobble

General Structure

Entity Structure

Scrobble

Track

Artist

5.9 KiB

Raw Blame History