Skip to main content

Overview

tip

For the difference between ENV and File examples in this document see Configuration Types.

Local Installation​

After installation see service.md to configure multi-scrobbler to run automatically in the background.

Nodejs​

Clone this repository somewhere and then install from the working directory

git clone https://github.com/FoxxMD/multi-scrobbler.git .
cd multi-scrobbler
nvm use # optional, to set correct Node version
npm install
npm run docs:install && npm run build
npm run start

Rollup build error​

During building if you encounter an error like: Your current platform "XXX" and architecture "XXX" combination is not yet supported by the native Rollup build.

Modify overrides in package.json to use @rollup/wasm-node as a drop-in replacement for rollup:

"overrides": {
  "spotify-web-api-node": {
    "superagent": "$superagent"
  }
  "vite": {
    "rollup": "npm:@rollup/wasm-node@^4.9.6"
  }
}

See this issue for more detail.

Usage Examples​

SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret MALOJA_URL="http://domain.tld" node src/index.js
tip

The web UI and API is served on port 9078. This can be modified using the PORT environmental variable.

Flatpak​

You must have Flatpak installed on your system.

flatpak install flathub io.github.foxxmd.multiscrobbler
warning

Flatpak users have experienced issues when using multi-scrobbler as a long-running process. Due to the relative difficulty in debugging issues with flatpak installations it is recommended:

  • to use a Docker installation if possible or
  • only if you need access to host-level resources like dbus for MPRIS and cannot run a nodejs installation

Usage Examples​

There are a few options for running flatpak applications with temporary or permanent environmental variables.

flatpak run --env=SPOTIFY_CLIENT_ID=yourId --envSPOTIFY_CLIENT_SECRET=yourSecret --env=MALOJA_URL="http://domain.tld" io.github.foxxmd.multiscrobbler

Docker​

Cross-platform images are built for x86 (Intel/AMD) and ARM64 (IE Raspberry Pi)

Available Images

Repository Page

docker.io/foxxmd/multi-scrobbler:latest

Or use the example docker-compose.yml, found in the repo, after modifying it to fit your configuration:

docker-compose.yml
version: '3.7'

services:
  multi-scrobbler:
    image: foxxmd/multi-scrobbler
    container_name: multi-scrobbler
    environment:
      - TZ=Etc/GMT # Specify timezone from TZ Database name found here https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
      #- SPOTIFY_CLIENT_ID=
      #- SPOTIFY_CLIENT_SECRET=
      #- SPOTIFY_REDIRECT_URI=http://multi-scrobbler-host-IP:9078/callback ## Need to be whitelisted in Spotify dashboard and is used for creating the connection first time
      #- MALOJA_URL=http://maloja:42010
      #- MALOJA_API_KEY=
      #- PUID=1000 # required if running docker on linux host, see main README Docker setup instructions
      #- PGID=1000 # required if running docker on linux host, see main README Docker setup instructions

      # set if using a source/client with redirect URI that you have not explicitly set and MS is NOT running on the same machine that you will view the dashboard from
      # EX: You will view MS dashboard at 'http://192.168.0.101:9078' -> set BASE_URL=http://192.168.0.101:9078
      #- BASE_URL=http://MyHostIP:9078
    volumes:
      - "./config:/config"
    #networks:
    #  - (optional to add container to the same bridge network that maloja is inside to be able to use docker internal networking & dns to resolve and connect to maloja URL via http://maloja:port)
    ports:
      - 9078:9078 # first port is the HOST port multi-scrobbler will serve UI and API on
    restart: unless-stopped

Recommended configuration steps for docker or docker-compose usage:

Storage​

You should bind a host directory into the container for storing configurations and credentials. Otherwise, these will be lost when the container is updated.

Example

Using -v method for docker:

docker run ... -v "$(pwd)/config:/config" foxxmd/multi-scrobbler

Networking​

If you are using a bridge network (default docker setup) you must map a port to the container in order to access the dashboard and use MS with some sources (Plex, Jellyfin). The default container port is 9078.

Example

Docker run publish options:

docker run ... -p 9078:9078 foxxmd/multi-scrobbler
Base URL​

Optionally, when

  • using a Source or Client that has a "Redirect URI" that you have not explicitly defined
  • and
    • using a bridge network or
    • installing MS on a different machine than the one used to view the dashboard

set the Base URL as the IP of the host machine. (This is the IP you would use to view the dashboard in a browser)

Example
docker run ... -e BASE_URL="http://hostMachineIP" foxxmd/multi-scrobbler

Other​

Linux Host​

info
note

If you are using rootless containers with Podman or are running docker on MacOS/Windows this DOES NOT apply to you.

If you are running Docker on a Linux Host you must specify user:group permissions of the user who owns the configuration directory on the host to avoid docker file permission problems. These can be specified using the environmental variables PUID and PGID.

To get the UID and GID for the current user run these commands from a terminal:

  • id -u -- prints UID
  • id -g -- prints GID

Docker Usage Example​

tip

See the Quick Start Guide for another guided docker-compose example

The example scenario:

  • Spotify Source
  • Maloja Client
  • Serving app on port 9078
  • Docker container located on a different IP (192.168.0.100) so use Base URL
  • Config/data directory on host machine in a directory next to docker-compose.yml
  • Linux uid/gid is 1000:1000
docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" -e "BASE_URL=192.168.0.100" -e "MALOJA_URL=http://domain.tld" -e "MALOJA_API_KEY=1234" -e "PUID=1000" -e "PGID=1000" -p 9078:9078 -v /home/myUser/ms:/config foxxmd/multi-scrobbler