Skip to main content

# 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 | Auto Monitoring
--- | --- | --- | --- | --- | --- | ---
Apple Music | Active | History | ❌ | ✅ | ❌ | ✅
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 | ❌ | ✅ | ❌ | ✅
Libre.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 | ✅ | ✅ | ✅ | ✅
Rocksky | Active | History | ❌ | ✅ | ❌ | ✅
Sonos | Active | Activity | ✅ | ✅ | ✅ | ✅
Spotify | Active | Activity | ✅ | ✅ | ✅ | ✅
Subsonic-compatible APIs | Active | Activity | ✅ | ✅ | ✅ | ✅
teal.fm | Active | History | ❌ | ✅ | ❌ | ✅
WebScrobbler | Ingress | History | ❌ | ✅ | ❌ | ✅
VLC | Active | Activity | ❌ | ✅ | ✅ | ✅
Yamaha MusicCast | Active | Activity | ❌ | ✅ | ✅ | ✅
Yandex Music | 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
- Ingress

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

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
- Listening History

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.

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.

### When Is Activity Scrobbled?​

##### From Listening History​

For Listening History Source-Of-Truth based Sources, like Listenbrainz and Last.fm, newely discovered history is immediately forwarded to relevant Clients.

##### From Ingress​

For Ingress communication based Sources, like Listenbrainz (Endpoint) and Webscrobbler, the client sending data to Multi-Scrobbler is what determines when activity is scrobbled. This means that it up to the behavior and implementation of whatever application you point at these Source endpoints: when the client sends "this is scrobbled", MS immediately forwards it to relevant Clients.

##### From Listening Activity​

For Sources that use Active communication with Listening Activity as the Source-Of-Truth -- like Jellyfin, Plex, Spotify, Subsonic, etc... -- Multi-Scrobbler waits until the track changes or the active player becomes stale/disappears before determining if the activity should be scrobbled.

This allows MS to record how long you listened to the track for as well as more accurately determine if Scrobble Thresholds have been met.

#### Scrobble Thresholds​

A Source that monitors Listening Activity 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

### Monitoring​

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 monitor activity 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 monitor activity. This action can be taken on the Web Dashboard by clicking the link next to Monitoring 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
            "autoMonitor": true
        }
    }