Skip to content

configuration.md

Latest commit

 

History

History
137 lines (105 loc) · 6.2 KB

configuration.md

File metadata and controls

137 lines (105 loc) · 6.2 KB
Raw

Configuration Guide

This guide covers all available Scrobblet configuration options, which are set through environment variables.

Table of Contents

General Configuration

Variable Required Default Description
SCROBBLET_PORT No 7276 Port the API server listens on
SCROBBLET_DATA_PATH No /etc/scrobblet Path where application data is stored
SCROBBLET_LOG_LEVEL No INFO The log level. Options: DEBUG, INFO, WARN, ERROR
SCROBBLET_RATE_LIMIT_RATE No 10 Maximum requests per second
SCROBBLET_RATE_LIMIT_BURST No 100 Maximum burst size
SCROBBLET_SOURCE Yes - Source to track. Options: Spotify
SCROBBLET_TARGETS Yes - Comma-separated list of targets to scrobble to. Options: LastFm, ListenBrainz, Maloja, Koito, CSV

Client Configuration

Spotify

ℹ️ Spotify Premium account required: Scrobblet uses Spotify's Web API to fetch your currently playing track. Since February 11, 2026, all newly created Development Mode apps require a Spotify Premium account. As of March 9, 2026, this requirement also applies to all existing apps. See the Spotify Developer Blog for full details.

Variable Required Default Description
SPOTIFY_CLIENT_ID Yes* - Your Spotify app Client ID
SPOTIFY_CLIENT_SECRET Yes* - Your Spotify app Client secret
SPOTIFY_REDIRECT_URL Yes* - OAuth 2.0 redirect URL (must match your Spotify app Redirect URI)

*Required only when SCROBBLET_SOURCE=Spotify

To set up Spotify:

  1. Go to Spotify Developer Dashboard
  2. Create a new app
  3. Add http://127.0.0.1:7276/api/spotify/callback (or your custom URL) to Redirect URIs
  4. Copy the client ID and client secret
  5. Start Scrobblet with the client ID, client secret, and redirect URL configured
  6. Visit http://localhost:7276/api/spotify/login to authenticate

⚠️ Spotify Redirect URI: Spotify only allows HTTPS Redirect URIs unless you use an explicit IPv4 or IPv6 loopback address (e.g. http://127.0.0.1:7276 or http://[::1]:7276).

If you cannot provide a valid redirect URI, you can intercept the callback and rewrite the address to your Scrobblet instance:

  1. Run docker run --rm -p 8080:8080 mendhak/http-https-echo:39 on the machine where your browser runs
  2. Set the Spotify Redirect URI and SPOTIFY_REDIRECT_URL to http://127.0.0.1:8080/api/spotify/callback
  3. Visit http://localhost:7276/api/spotify/login to authenticate
  4. Replace 127.0.0.1:8080 with the address of your Scrobblet instance and open the updated URL

Last.fm

Variable Required Default Description
LASTFM_API_KEY Yes* - Your Last.fm API key
LASTFM_SHARED_SECRET Yes* - Your Last.fm shared secret
LASTFM_REDIRECT_URL Yes* - Redirect URL (must match your Last.fm API account callback URL)

*Required only when SCROBBLET_TARGETS=LastFm

To set up Last.fm:

  1. Go to Last.fm API Account Creation
  2. Create an API account
  3. Set callback URL to http://127.0.0.1:7276/api/lastfm/callback (or your custom URL)
  4. Copy the API key and shared secret
  5. Start Scrobblet with the API key and shared secret configured
  6. Visit http://localhost:7276/api/lastfm/login to authenticate

ListenBrainz

Variable Required Default Description
LISTENBRAINZ_URL No https://api.listenbrainz.org URL of a ListenBrainz-compatible service
LISTENBRAINZ_TOKEN Yes* - Your ListenBrainz user token

*Required only when SCROBBLET_TARGETS=ListenBrainz

To set up ListenBrainz:

  1. Go to ListenBrainz User Settings
  2. Copy your user token
  3. Start Scrobblet with the user token configured

✅ ListenBrainz-compatible API support: Scrobblet can scrobble to any service that implements the ListenBrainz API specification. This includes the official ListenBrainz service, self-hosted ListenBrainz instances, or any other compatible implementation. Simply set LISTENBRAINZ_URL to point to your preferred service.

Maloja

Variable Required Default Description
MALOJA_URL Yes* - URL of your Maloja instance (e.g., http://localhost:42010)
MALOJA_TOKEN Yes* - Your Maloja API key

*Required only when SCROBBLET_TARGETS=Maloja

To set up Maloja:

  1. Access your Maloja instance
  2. Go to Settings → API Keys
  3. Generate a new API key
  4. Start Scrobblet with the API key configured

Koito

Variable Required Default Description
KOITO_URL Yes* - URL of your Koito instance (e.g., http://localhost:4110)
KOITO_TOKEN Yes* - Your Koito API key

*Required only when SCROBBLET_TARGETS=Koito

To set up Koito:

  1. Access your Koito instance
  2. Log in
  3. Go to Settings → API Keys
  4. Generate a new API key
  5. Start Scrobblet with the API key configured

CSV

Variable Required Default Description
CSV_FILE_PATH No ${SCROBBLET_DATA_PATH}/scrobbles.csv Path to the CSV file where scrobbles will be written

The CSV target writes completed scrobbles to a CSV file with the following format:

  • Artists: Multiple artists joined with ", "
  • Title: Track title
  • Album: Album name
  • Track Number: Track number on the album
  • Duration: Track duration in seconds
  • Started At: ISO 8601 timestamp when tracking started
  • Ended At: ISO 8601 timestamp when tracking ended

The CSV file is created automatically with headers on the first scrobble. Subsequent scrobbles are appended to the file.