DOCSEARCHbyAlgolia
Submit Docs

multi-scrobbler

repository·master·Indexed 22 days ago

https://github.com/foxxmd/multi-scrobbler

A dockerized application that monitors music listening activity from various sources, such as Spotify, Plex, or YouTube Music, and scrobbles that data to multiple clients, including Last.fm and ListenBrainz. It supports multiple configuration methods via environment variables, individual JSON files, or a centralized All-In-One (AIO) JSON configuration.

Tokens
91.7K
Snippets
243
Records
364
Agent score
77%

What's inside multi-scrobbler

  1. How Duplicate Detection works

    master

    To prevent duplicate entries, Multi-scrobbler checks the Client's API for existing scrobbles before submitting a new Play.

    For each Play, MS fetches (cached) scrobbles from the Client within a time range around the Play's timestamp and scores them based on:

    • Similarity of Title, Artists, and Album.
    • Temporal closeness of the Play's timestamp to the existing scrobble's timestamp.
    • Whether MS detected the Play as a repeat (for Sources reporting real-time Player data).

    Detailed scoring breakdowns are available at the TRACE logging level or via the debug data for a scrobble.

  2. Correct scrobbles using MusicBrainz

    master

    MusicBrainz can be used to match activity, fill in missing data, or normalize existing data before it is sent to clients. This is an optional step.

    1. Global MusicBrainz Configuration

    Provide contact info and search presets in your docker-compose.yml environment section. This is a one-time setup.

    2. Enable MusicBrainz for specific Sources

    For Jellyfin, Spotify, Navidrome, or Plex: Add the corresponding _TRANSFORMS=musicbrainz environment variable to your docker-compose.yml:

    • JELLYFIN_TRANSFORMS=musicbrainz
    • SPOTIFY_TRANSFORMS=musicbrainz
    • LZE_TRANSFORMS=musicbrainz
    • PLEX_TRANSFORMS=musicbrainz

    For Last.fm (Source): Modify the lastfm.json configuration file to include a playTransform with a preCompare type of musicbrainz.

    // lastfm.json example
[
  {
    "name": "myLastFmSource",
    "configureAs": "source",
    "data": {
      "apiKey": "MY_API_KEY_PLACEDHOLDER",
      "secret": "MY_SECRET_PLACEHOLDER",
      "redirectUri": "http://192.168.0.100:9078/lastfm/callback"
    },
    "options": {
      "playTransform": {
        "preCompare": {
          "type": "musicbrainz"
        }
      }
    }
  }
]

  3. How the Ingress component receives data

    master

    The Ingress component functions as a passive receiver. Instead of actively polling or contacting external services for data, it waits to receive data sent to it by outside services.

    To ensure successful data transmission, the multi-scrobbler instance must be network-accessible to the sending service. This can be achieved by:

    • Running multi-scrobbler on an open port.
    • Exposing multi-scrobbler through a reverse proxy.

  4. Whitelist or Blacklist Webscrobbler connectors

    master

    You can control which WebScrobbler connectors trigger a scrobble in Multi-scrobbler using whitelists or blacklists.

    Use the website name from the supported websites list or the Connectors tab in the WebScrobbler extension.

    Note: This configuration only affects Multi-scrobbler's behavior; it does not change how the WebScrobbler extension itself functions.

  5. How multi-scrobbler works

    master

    multi-scrobbler (MS) operates by monitoring one or more Sources and forwarding playback data to one or more Clients.

    Core Abstractions

    • Source: A data provider containing information about music being played (e.g., Spotify, Jellyfin, Plex, YouTube Music).

      • A Source configuration includes a friendly name, authentication data, and an optional list of specific Client names.
      • If no specific clients are listed for a Source, MS will scrobble that Source's data to all configured Clients.

    • Client: An application that stores historical playback data (scrobbles) (e.g., Last.fm, ListenBrainz, Koito).

      • A Client configuration includes a friendly name and authentication data.

    Data Flow

    MS continuously monitors all configured Sources. When a new track is detected, MS captures the track information and sends (scrobbles) it to the designated Clients.

  6. How Multi-Scrobbler interacts with the AT Protocol (Bluesky/Atmosphere)

    master

    When using the AT Protocol (used by Bluesky and Atmosphere accounts), Multi-Scrobbler functions by writing (scrobbling) your music play data directly to your personal repository on a PDS (Personal Data Server).

    Key behaviors:

    • Data Structure: Plays are written as a JSON data structure following the specific Lexicon definitions for the service.
    • Storage Location: Data is appended to a list at a specific collection location defined by the service's lexicon (e.g., <CodeInline>{props.lexicon}</CodeInline>).
    • Data Consumption: Because the data is stored in your personal repository, any other AT Protocol-compliant application can read and render your scrobble history.

  7. Understand the different configuration types in multi-scrobbler

    master

    multi-scrobbler supports three primary ways to provide configuration data:

    1. ENV (Environment Variables): Configuration provided via system environment variables.
    2. File: A standalone JSON configuration file specifically for a single Source or Client type.
    3. AIO (All-In-One): A single config.json file that contains the entire configuration, including multiple sources and clients within a unified structure.

    When writing a configuration, you should choose the method that best fits your deployment environment (e.g., ENV for containerized environments like Docker, or AIO for local file-based setups).

  8. Understand Caching in Multi-scrobbler

    master

    Multi-scrobbler uses caching to persist data across restarts, reduce external API calls, and improve performance. By default, an in-memory cache is used. You can optionally configure a secondary store for better persistence and capacity.

    What is cached?

    • Auth Data: Authentication sessions, tokens, and credentials.
    • Scrobble Transforms: Results of transform rules, allowing identical scrobbles with the same rules to reuse cached results.
    • Transform API Calls: Metadata service calls (e.g., Musicbrainz) used during scrobble enhancement.

  9. Use Enhanced Playback Reporting with Subsonic

    master

    Multi-Scrobbler supports the Open Subsonic extension, Playback Report, which provides millisecond-accurate player position and state reporting.

    To use this feature:

    1. Your Subsonic server must support the extension.
    2. Your active playback Client must report it.

    Multi-Scrobbler will automatically fall back to the classic, less accurate Subsonic getNowPlaying endpoint if the extension is unavailable. The UI will display contextual icons to indicate support for both the Source and the Player.

  10. Important Limitations of Rocksky Scrobbling

    master

    When using Rocksky as a client, be aware of the following:

    • Public Data: The default Bluesky PDS is public. Your scrobbles are public (read-only), similar to Last.fm or Listenbrainz.
    • No Scrobbling Guarantee: Rocksky does not guarantee that every scrobble will be persisted. It asynchronously matches scrobble data against Musicbrainz or Spotify catalogs after submission. If a match is not found, the scrobble is not persisted.
    • Recommendation: If you require 100% scrobble capture, you should also scrobble to an additional Scrobble Client.

  11. Understand Scrobble Clients

    master

    A Client is an application that stores historical information about played songs (scrobbles). Multi-scrobbler supports various clients such as Last.fm, Listenbrainz, Discord, and Maloja.

    Some clients support Now Playing functionality (reporting the currently active track), while others only support historical scrobbling.

    Supported Clients and Now Playing status:

    • Supports Now Playing: Discord, Last.fm, Libre.fm, Listenbrainz.
    • Does NOT support Now Playing: Koito, Maloja, Rocksky, Teal.fm.

  12. Understand the difference between Polling and Ingress Sources

    master

    When developing a new Source for multi-scrobbler, you must first determine how the service communicates playback data:

    1. Polling Source: Used when the service provides an API that multi-scrobbler can actively query. Multi-scrobbler sends periodic requests to the service's endpoints to fetch playback information (e.g., /api/now-playing or /api/recent).
    2. Ingress Source: Used when the service proactively pushes data to multi-scrobbler via webhooks (e.g., Jellyfin or Plex). In this model, the service initiates the communication.

    Choosing the correct model depends on whether the target service's API supports being queried or if it supports sending outbound webhooks.