Overview

A Source is a data source that contains information about tracks you are playing like a music player or platform. Examples are Spotify, Jellyfin, Plex, Youtube Music, Airsonic, etc...

Sources

Name	Networking	Scrobble SOT	Multi Device/User	Scrobble Destination	Thresholds	Should Scrobble
Azuracast	Active	Activity	❌	✅	✅	✅
Deezer	Active	History	✅	✅	❌	❌
Google Cast (Chromecast)	Active	Activity	✅	✅	✅	❌
Icecast	Active	Activity	❌	✅	✅	✅
Jellyfin	Active	Activity	✅	✅	✅	❌
JRiver	Active	Activity	❌	✅	✅	❌
Kodi	Active	Activity	❌	✅	✅	❌
Koito	Active	History	❌	✅	❌	❌
Last.fm	Active	History	❌	✅	❌	❌
Last.fm (Endpoint)	Ingress	History	❌	✅	❌	❌
ListenBrainz	Active	History	❌	✅	❌	❌
ListenBrainz (Endpoint)	Ingress	History	❌	✅	❌	❌
Maloja	Active	History	❌	✅	❌	❌
Mopidy	Active	Activity	❌	✅	✅	❌
MPD (Music Player Daemon)	Active	Activity	❌	✅	✅	❌
Musikcube	Active	Activity	❌	✅	✅	❌
Plex	Active	Activity	✅	✅	✅	❌
Spotify	Active	Activity	✅	✅	✅	❌
Subsonic-compatible APIs	Active	Activity	✅	✅	✅	❌
WebScrobbler	Ingress	History	❌	✅	❌	❌
VLC	Active	Activity	❌	✅	✅	❌
Yamaha MusicCast	Active	Activity	❌	✅	✅	❌
Youtube Music	Active	History	❌	✅	❌	❌

Features

Types of Sources

The Sources implemented in multi-scrobbler can be broken down into two categories.

By Communication Method

How does this Source get data from the service/application?

Active

The MS Source makes network requests to the service which returns a response with data MS can use to monitor listening activity or scrobbles.

Ingress

The MS Source waits for the service/application to send data to multi-scrobbler.

These types of Sources require that multi-scrobbler is accessible to the service, generally through an open port or reverse proxy.

By Data Source of Truth

How does MS determine if/when a song has been played and is scrobbable?

Listening Activity

These Sources expose some kind of real-time listening data for users, like:

• player state (paused, stopped, playing)
• player position (1:50/2:40)
• current listened duration (Track A playing for 1m:20s)

For theses Sources multi-scrobbler keeps track of the real-time state of your activity and scrobbles a track after it meets certain scrobble thresholds.

Listening History

Some Sources expose their own version of "this track has been scrobbled."

• Listenbrainz, Koito, and Last.fm are all scrobble services that have "definitive" histories of scrobbled tracks.

For these Sources multi-scrobbler monitors the listening history data and scrobbles when it sees a new entry in the list.

Multi-Device/User

Some Sources report which User is playing a track and/or on what device the track is being played. These Sources can be filtered with configuration to only monitor activity for specific devices or users.

Limiting Scrobble Destination

To limit which Clients a Source will scrobble to use the clients property in a Source's File/AIO configuration to specify the name property of the Clients that it should scrobble to:

jellyfin.json

{
    "name": "MyJellyfin",
    "clients": ["myMaloja","koitoA","listenbrainzFoo"]
    "data": {
        // ...
    },
}

note

If clients is empty ("clients": []) or is omitted then the default is for the Source to scrobble to all configured Clients.

note

If a Client is configured using ENV then it is given a generated name. Check the multi-scrobbler Dashboard to find their name in a subheader under the Client type. Example:

Otherwise, use the name property you gave the client in it's File/AIO config.

Scrobble Thresholds

A Source that monitors active listening uses one of two metrics to determine if a Song is scrobbable based on your listening:

• percent of track listened to (50% or more)
• or amount of time (duration) track was listened to (4 minutes or more)

These default values are based on last.fm's scrobble guidance.

These values can be customized in the options of Source's file or aio config:

spotify.json

{
  "data": {
      // ...
  },
  "options": {
      "scrobbleThresholds": {
          "duration": 40, // scrobbable if listened to for 40 seconds or more
          "percent": 20   // scrobbable if listened to for 20% or more of the track's length
      }
  }
}

These can also be configured globally for all Sources using ENVs:

SOURCE_SCROBBLE_DURATION=40
SOURCE_SCROBBLE_PERCENT=20

Should Scrobble Behavior

note

This feature is currently available only for some Sources. Check each Source's documentation to see if it supported.

For most Sources multi-scrobbler can determine if a user is listening and scrobble automatically. For Sources which multi-scrobbler cannot do this or require additional configuration, a user can indicate to MS that it should or should not scrobble. This action can be taken on the Web Dashboard by clicking the link next to Should Scrobble found in each Source's status card.

Additionally, for these Sources, the default behavior for Scrobbling can be explicitly set by adding the following value to a Source's options in file or aio config:

azuracast.json

{
    "data": {
        // ...
    },
    "options": {
        // set to true to always scrobble automatically
        // set to false to never scrobble automatically
        "systemScrobble": true
    }
}