Deploying multi-scrobbler

Introduction

multi-scrobbler is a self-hosted service that aggregates music listening data from multiple sources and scrobbles to multiple destinations. If you listen to music across various platforms and want a unified scrobbling solution, multi-scrobbler bridges the gap between your music sources and your tracking services.

Whether you’re playing music through Spotify, Plex, Jellyfin, Subsonic, or other platforms, multi-scrobbler captures your listening activity and forwards it to services like Last.fm, Listenbrainz, and Maloja. This ensures consistent tracking regardless of where you’re listening.

Key highlights of multi-scrobbler:

Multi-Source Support: Scrobble from Spotify, Plex, Jellyfin, Tautulli, Subsonic, MPD, MPRIS, and more
Multi-Destination: Send scrobbles to Last.fm, Listenbrainz, Maloja, and other services simultaneously
Duplicate Detection: Prevents double-scrobbling when the same track is detected from multiple sources
Web Dashboard: Real-time view of current activity and scrobble history
Flexible Configuration: YAML/JSON configuration with environment variable support
Authentication Handling: Manages OAuth flows and API authentication for connected services
Retry Logic: Automatically retries failed scrobbles with exponential backoff
Dead Letter Queue: Stores failed scrobbles for later retry
Docker-Ready: Official Docker image with minimal configuration needed
Open Source: Licensed under MIT

This guide walks through deploying multi-scrobbler on Klutch.sh using Docker, configuring your music sources, and connecting to scrobbling services.

Why Deploy multi-scrobbler on Klutch.sh

Deploying multi-scrobbler on Klutch.sh provides several advantages:

Always-On Scrobbling: Your scrobbler runs 24/7, capturing plays even when your devices sleep.

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds multi-scrobbler without complex configuration.

Persistent Storage: Attach persistent volumes for configuration, authentication tokens, and the dead letter queue.

HTTPS by Default: Klutch.sh provides automatic SSL certificates, required for OAuth callbacks from services like Spotify.

GitHub Integration: Connect your configuration repository for automatic redeployments.

Centralized Scrobbling: One instance handles all your sources instead of configuring scrobbling on each device.

Custom Domains: Assign a custom domain for OAuth callback URLs.

Prerequisites

Before deploying multi-scrobbler on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization concepts
Accounts on the music sources you want to scrobble from (Spotify, Plex, etc.)
Accounts on destination services (Last.fm, Listenbrainz, etc.)
API credentials from your scrobbling services
(Optional) A custom domain for OAuth callbacks

Understanding multi-scrobbler Architecture

multi-scrobbler operates with a source-client model:

Sources: Services you listen to music on (Spotify, Plex, Jellyfin, etc.)

Clients: Services where scrobbles are sent (Last.fm, Listenbrainz, Maloja)

Web Dashboard: A monitoring interface showing current activity and history

Configuration: YAML or JSON files defining sources, clients, and their connections

Preparing Your Repository

Create a GitHub repository with your multi-scrobbler configuration.

Repository Structure

multi-scrobbler-deploy/
├── Dockerfile
├── config.yaml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile in your repository root:

FROM foxxmd/multi-scrobbler:latest

# Set environment variables
ENV CONFIG_DIR=/config
ENV LOG_LEVEL=info
ENV BASE_URL=${BASE_URL}

# Create config directory
RUN mkdir -p /config

# Copy configuration
COPY config.yaml /config/config.yaml

# Expose web interface
EXPOSE 9078

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:9078/ || exit 1

Creating the Configuration File

Create config.yaml with your sources and clients:

# multi-scrobbler Configuration

# Sources - where you listen to music
sources:
  # Spotify source
  - name: spotify
    type: spotify
    data:
      clientId: ${SPOTIFY_CLIENT_ID}
      clientSecret: ${SPOTIFY_CLIENT_SECRET}
      redirectUri: ${SPOTIFY_REDIRECT_URI}

  # Plex source (via webhook)
  - name: plex
    type: plex
    data:
      user:
        - your_plex_username

  # Jellyfin source
  - name: jellyfin
    type: jellyfin
    data:
      url: https://your-jellyfin-server.com
      apiKey: ${JELLYFIN_API_KEY}
      user:
        - your_jellyfin_username

# Clients - where scrobbles are sent
clients:
  # Last.fm client
  - name: lastfm
    type: lastfm
    data:
      apiKey: ${LASTFM_API_KEY}
      secret: ${LASTFM_SECRET}
      redirectUri: ${LASTFM_REDIRECT_URI}

  # Listenbrainz client
  - name: listenbrainz
    type: listenbrainz
    data:
      token: ${LISTENBRAINZ_TOKEN}

  # Maloja client (if self-hosted)
  - name: maloja
    type: maloja
    data:
      url: https://your-maloja-server.com
      apiKey: ${MALOJA_API_KEY}

Creating the .dockerignore File

.git
.github
*.md
LICENSE
.gitignore
*.log
.DS_Store
.env

Environment Variables Reference

Variable	Required	Description
`BASE_URL`	Yes	Public URL of your multi-scrobbler instance
`SPOTIFY_CLIENT_ID`	If using Spotify	Spotify API client ID
`SPOTIFY_CLIENT_SECRET`	If using Spotify	Spotify API client secret
`SPOTIFY_REDIRECT_URI`	If using Spotify	OAuth redirect URI
`JELLYFIN_API_KEY`	If using Jellyfin	Jellyfin API key
`LASTFM_API_KEY`	If using Last.fm	Last.fm API key
`LASTFM_SECRET`	If using Last.fm	Last.fm API secret
`LISTENBRAINZ_TOKEN`	If using Listenbrainz	Listenbrainz user token
`MALOJA_API_KEY`	If using Maloja	Maloja API key

Deploying multi-scrobbler on Klutch.sh

Gather API Credentials

Before deployment, collect the required API credentials:

Spotify: Create an app at Spotify Developer Dashboard
Last.fm: Create an API account at Last.fm API
Listenbrainz: Get your token from Listenbrainz Profile

Push Your Repository to GitHub

Initialize and push your repository with the Dockerfile and configuration.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project called “multi-scrobbler”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 9078

Set Environment Variables

Configure your API credentials as environment variables:

Variable	Value
`BASE_URL`	`https://your-app-name.klutch.sh`
`SPOTIFY_CLIENT_ID`	Your Spotify client ID
`SPOTIFY_CLIENT_SECRET`	Your Spotify client secret
`SPOTIFY_REDIRECT_URI`	`https://your-app-name.klutch.sh/callback`
`LASTFM_API_KEY`	Your Last.fm API key
`LASTFM_SECRET`	Your Last.fm secret
`LISTENBRAINZ_TOKEN`	Your Listenbrainz token

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/config`	1 GB	Configuration and state files

Deploy Your Application

Click Deploy to start the build process.

Complete OAuth Authentication

After deployment, access your multi-scrobbler dashboard and complete OAuth authentication for sources like Spotify that require it.

Access the Dashboard

View your scrobbling activity at https://your-app-name.klutch.sh.

Configuring Music Sources

Spotify

Spotify requires OAuth authentication:

Create an app at the Spotify Developer Dashboard
Add your redirect URI (e.g., https://your-app.klutch.sh/callback)
Access multi-scrobbler and click to authenticate
multi-scrobbler will poll your Spotify activity

Plex

Plex uses webhooks to notify multi-scrobbler:

In Plex settings, go to Webhooks
Add your multi-scrobbler webhook URL: https://your-app.klutch.sh/plex
Plays will be scrobbled automatically

Jellyfin

Jellyfin integration requires an API key:

In Jellyfin admin, go to API Keys
Create a new key for multi-scrobbler
Configure the URL and API key in your config
Webhook plugin recommended for real-time scrobbling

Subsonic/Airsonic

For Subsonic-compatible servers:

sources:
  - name: subsonic
    type: subsonic
    data:
      url: https://your-subsonic-server.com
      user: username
      password: password

MPD

Connect to a Music Player Daemon:

sources:
  - name: mpd
    type: mpd
    data:
      url: localhost
      port: 6600

Configuring Scrobble Destinations

Last.fm

The most popular scrobbling destination:

Create an API account at Last.fm
Configure with API key and secret
Complete OAuth when prompted in the dashboard

Listenbrainz

Open-source alternative to Last.fm:

Get your user token from your Listenbrainz profile
Configure with the token
Scrobbles appear immediately

Maloja

Self-hosted scrobbling server:

clients:
  - name: maloja
    type: maloja
    data:
      url: https://your-maloja-instance.com
      apiKey: your_api_key

Dashboard Features

Real-Time Monitoring

The web dashboard shows:

Currently playing tracks from all sources
Recent scrobble history
Source connection status
Client authentication status

Scrobble History

View your scrobbling history with:

Track details
Source information
Destination status
Timestamp

Dead Letter Queue

Failed scrobbles are stored for retry:

View failed scrobbles
Retry individual or all failed items
Clear the queue

Troubleshooting

OAuth Authentication Failing

Verify redirect URIs match exactly
Ensure BASE_URL is set correctly
Check that HTTPS is working

No Scrobbles Appearing

Verify source is connected (green status in dashboard)
Check client authentication is complete
Review logs for errors

Duplicate Scrobbles

Enable duplicate detection in config
Ensure same track isn’t playing on multiple sources
Check time thresholds for duplicate detection

Webhook Not Receiving

Verify webhook URL is correct
Check that source server can reach your multi-scrobbler instance
Review firewall and network settings

Additional Resources

Conclusion

Deploying multi-scrobbler on Klutch.sh gives you a centralized scrobbling solution that captures listening activity from all your music sources. With support for multiple sources and destinations, you can maintain consistent listening history regardless of where you play music.

The combination of real-time monitoring, duplicate detection, and retry logic ensures your scrobbles are captured reliably. Whether you’re tracking for personal statistics or sharing your listening habits, multi-scrobbler on Klutch.sh provides a robust, always-available scrobbling service.