Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/FoxxMD/multi-scrobbler. Scrobble plays from multiple sources to multiple clients docs.multi-scrobbler.app
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400---title: Quickstartsidebar: order: 2---
import {LocalStorageText} from '@site/src/components/Storage/Text';import { Badge } from '@astrojs/starlight/components';import Handle from "@site/src/components/snippets/_atmosphere_id.mdx";
This guide will get you up and running with multi-scrobbler using [Docker](https://www.docker.com/) and [`docker compose`](https://docs.docker.com/compose/). At the end of the guide you will have:
* the dashboard served on port `9078` of a host machine which has a URL of <LocalStorageText client:load initialValue="http://YOUR_MS_DOMAIN:9078" stylePreset="placeholder" storageKey="http://YOUR_MS_DOMAIN:9078"/>* data saved to the same directory as the `docker-compose.yml` file* multi-scrobbler monitoring [Spotify](/configuration/sources/spotify), [Jellyfin](/configuration/sources/jellyfin), Navidrome, [Plex](/configuration/sources/plex), and/or [Last.fm](/configuration/sources/lastfm-source) for listening activity* multi-scrobbler scrobbling to [Lastfm](/configuration/clients/lastfm), [Maloja](/configuration/clients/maloja), and/or [Koito](/configuration/clients/koito)
:::note
If the multi-scrobbler container is on the same machine you will be viewing the dashboard from (IE `localhost`) you can remove and ignore `BASE_URL` usage below. Additionally, replace usage of <LocalStorageText client:load initialValue="http://YOUR_MS_DOMAIN:9078" stylePreset="placeholder" storageKey="http://YOUR_MS_DOMAIN:9078"/> with `http://localhost:9078`.
:::
## Create Folders and Get User ID
Create a new folder for your multi-scrobbler installation and inside it create a folder for config/data files.
```shell title="/home/yourUser" placeholder="~/msData"$ mkdir ~/msData #[!ref] project folder$ mkdir ~/msData/config #[!ref] folder used for config/data```
If you are running docker on a Linux host, determine your UID/GID using these commands:
```shell placeholder="1000,1001"$ id -u1000 #[!ref] UID$ id -g1001 #[!ref] GID```
## Create Docker Compose File
Create a `docker-compose.yml` in <LocalStorageText client:load initialValue="~/msData" stylePreset="placeholder" storageKey="~/msData"/> with this content:
```yaml title="~/msData/docker-compose.yml" placeholder="http://YOUR_MS_DOMAIN:9078,1000,1001"services: multi-scrobbler: image: foxxmd/multi-scrobbler container_name: multi-scrobbler user: 1000:1001 # [!ref] UID:GID retrieved in the first section, used for [file/folder ownership](/installation#user-and-permission) on Linux hosts environment: - TZ=Etc/GMT # [!ref] Specify timezone from [TZ Database **TZ identifier**](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) - BASE_URL=http://YOUR_MS_DOMAIN:9078 # [!ref] [**Base URL**](/configuration#base-url) is the URL that Multi-Scrobbler will be accessed from in a browser # all Environmental Variables in below examples go here!
volumes: - "./config:/config" # [!ref] `./config` is the directory created in the first section, needed for storing db and auth data ports: - "9078:9078" restart: unless-stopped```
## Setup Sources
[**Sources**](/configuration/sources) are the services/music players multi-scrobbler monitors to look for listening activity.
<Tabs groupId="qsSource"> <TabItem value="jellyfin" label="Jellyfin"> Follow the Jellyfin configuration [instructions for setting up an **API Key**.](/configuration/sources/jellyfin)
Then, add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" - JELLYFIN_URL=192.168.0.110:8096 # [!ref] URL to Jellyfin UI - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56b # [!ref] Api Key created in previous step - JELLYFIN_USER=MyUser # [!ref] Your username in Jellyfin - JELLYFIN_ID=myJellyin ``` </TabItem> <TabItem value="spotify" label="Spotify"> To access your Spotify activity you must [create a Spotify App](https://developer.spotify.com/dashboard) to get a **Client ID/Secret** and set a valid **Redirect URI**. Refer to the [Spotify Authentication instructions in the docs.](/configuration/sources/spotify#authenticate-spotify-with-multi-scrobbler)
Assuming you used the **HTTPS** method for your **Redirect URI** from the instructions above...after the application is created add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" placeholder="http://YOUR_MS_DOMAIN:9078" - SPOTIFY_CLIENT_ID=yourClientId - SPOTIFY_CLIENT_SECRET=yourClientSecret - SPOTIFY_REDIRECT_URI=http://YOUR_MS_DOMAIN:9078/callback - SPOTIFY_ID=mySpotify ```
Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at <LocalStorageText client:load readOnly initialValue="http://YOUR_MS_DOMAIN:9078" stylePreset="inline" storageKey="http://YOUR_MS_DOMAIN:9078"/> and click **(Re)authenticate** on the Spotify card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete. </TabItem> <TabItem value="navidrome" label="Navidrome"> Navidrome supports [scrobbling using Listenbrainz](https://www.navidrome.org/docs/usage/scrobbling/#listenbrainz). You should use this, rather than a [Subsonic Source](/configuration/sources/subsonic) because Navidrome's internal scrobbling functionality supports providing multiple artists and offline scrobbling while the Subsonic Source does not.
To setup Navidrome to scrobble to multi-scrobbler via the Listenbrainz option:
#### Create Listenbrainz Endpoint Source
Create a new [Listenbrainz Endpoint](/configuration/sources/listenbrainz-endpoint) [Source](/configuration/sources) in multi-scrobbler by creating a token to use with the endpoint via [ENV Config](/configuration?configType=env#configuration-types) in `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" - LZE_TOKEN=myCoolToken - LZE_ID=navidromeLZ ```
The token can be anything. [(Re)start multi-scrobbler](#start-multi-scrobbler) after making this change.
#### Configure Navidrome
Set the [**ListenBrainz.BaseURL**](https://www.navidrome.org/docs/usage/configuration-options/#advanced-configuration) (env `ND_LISTENBRAINZ_BASEURL`) to <LocalStorageText client:load initialValue="http://YOUR_MS_DOMAIN:9078" stylePreset="inline" storageKey="http://YOUR_MS_DOMAIN:9078" suffix="/1/"/> in your Navidrome installation. Assuming you are using the [docker installation](https://www.navidrome.org/docs/installation/docker/), modify `environment` to add:
```yaml title="docker-compose.yml" placeholder="http://YOUR_MS_DOMAIN:9078" - ND_LISTENBRAINZ_BASEURL=http://YOUR_MS_DOMAIN:9078/1/ ```
Restart Navidrome after making this change. Then, [follow the directions for enabling Listenbrainz scrobbling in Navidrome](https://www.navidrome.org/docs/usage/scrobbling/#listenbrainz). The **Listenbrainz user token** is the token you created for `LZE_TOKEN` earlier. </TabItem> <TabItem value="plex" label="Plex"> Find your [**Plex Token**](https://support.plex.tv/articles/204059436-finding-an-authentication-token-x-plex-token/) and make note of the **URL** and **Port** used to connect to your Plex instance.
Add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" - PLEX_URL=http://192.168.0.101:32400 - PLEX_TOKEN=6c0ihz8j7__f5r18oa0zm8 - PLEX_ID=myPlex # [!ref] optional, restrict scrobbling to a list of comma-delimited users #- PLEX_USERS_ALLOW=myPlexUsername ```
[Restart multi-scrobbler](#start-multi-scrobbler) to create the new Source. You may wish to refer to the [User and Library defaults/filtering](/configuration/sources/plex) in the Plex Source docs for a more granular setup. </TabItem> <TabItem value="lastfm" label="Last.fm">
<Badge text="Warning!" size="small" variant="caution" /> [**Last.fm is ending free API Keys!**](/configuration/clients/lastfm)
If you are already scrobbling to Last.fm and wish to mirror your scrobbling activity to one or more other [Clients](#setup-clients), use this Source. If, instead, you want to scrobble **from** multi-scrobbler **to** Last.fm then see the Last.fm tab in the [Setup Clients](#setup-clients) section below.
[Register for an API account at Last.fm.](https://www.last.fm/api/account/create)
Use the following for **Callback URL**:
```text placeholder="http://YOUR_MS_DOMAIN:9078" http://YOUR_MS_DOMAIN:9078/lastfm/callback ```
After account creation make note of the **Api Key** and **Secret** that are displayed.
Add these values to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" placeholder="http://YOUR_MS_DOMAIN:9078" - SOURCE_LASTFM_API_KEY=MY_API_KEY_PLACEDHOLDER - SOURCE_LASTFM_SECRET=MY_SECRET_PLACEHOLDER - SOURCE_LASTFM_REDIRECT_URI=http://YOUR_MS_DOMAIN:9078/lastfm/callback - SOURCE_LASTFM_ID=myLFMSource ```
Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at <LocalStorageText client:load initialValue="http://YOUR_MS_DOMAIN:9078" stylePreset="inline" storageKey="http://YOUR_MS_DOMAIN:9078"/> and click **(Re)authenticate** on the **Last.fm (Source)** card to authorize multi-scrobbler to use your account. Monitoring will begin automatically after authorization is complete. </TabItem></Tabs>
## Correct Scrobbles with Musicbrainz :badge[Optional]{variant="note"}
Multi-scrobbler can use [Musicbrainz](https://musicbrainz.org/) to match activity from your Sources in order to [fill in missing data](/configuration/transforms/musicbrainz), or correct/normalize existing data, before it is scrobbled to the [Clients](#setup-clients) below. This step is optional.
<details>
<summary>Musicbrainz Setup Instructions</summary>
<h3>Configure Musicbrainz API</h3>
:::note
**This step only needs to be performed once** regardless of how many Sources you want to use Musicbrainz for.
:::
Add these value to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml"# [!ref] how musicbrainz searches and selects matches: isrc => then tries basic text fields => then tries extracted artists- MB_PRESETS=default,sensible,native```
**Presets** are found [here](/configuration/transforms/musicbrainz/#env-configuration).
<h3>Enable Musicbrainz For A Source</h3>
Musicbrainz can be enabled for multiple Sources. Follow the directions in each tab to enable it for that Source.
<Tabs groupId="qsSource"><TabItem value="jellyfin" label="Jellyfin">Add this value to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)```yaml title="~/msData/docker-compose.yml"- JELLYFIN_TRANSFORMS=musicbrainz```</TabItem><TabItem value="spotify" label="Spotify">Add this value to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)```yaml title="~/msData/docker-compose.yml"- SPOTIFY_TRANSFORMS=musicbrainz```</TabItem><TabItem value="navidrome" label="Navidrome">Add this value to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)```yaml title="~/msData/docker-compose.yml"- LZE_TRANSFORMS=musicbrainz```</TabItem><TabItem value="plex" label="Plex">Add this value to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)```yaml title="~/msData/docker-compose.yml"- PLEX_TRANSFORMS=musicbrainz```</TabItem><TabItem value="lastfm" label="Last.fm">Modify the `lastfm.json` file you created in the [Setup Sources](#setup-sources) step to add the highlighted section in the example below. The comma at the top highlighted section is important!
```json title="~/msData/config/lastfm.json" placeholder="http://YOUR_MS_DOMAIN:9078"[ { "name": "myLastFmSource", "configureAs": "source", "data": { "apiKey": "MY_API_KEY_PLACEDHOLDER", "secret": "MY_SECRET_PLACEHOLDER", "redirectUri": "http://YOUR_MS_DOMAIN:9078/lastfm/callback" // [!code highlight:8] }, "options": { "playTransform": { "preCompare": { "type": "musicbrainz" } } } }]```</TabItem></Tabs>
</details>
## Setup Clients
[**Clients**](/configuration/clients) are services that store scrobbles. Multi-scrobbler will scrobble all listening activity from the **Sources** you configured to all **Clients** you configure here.
<Tabs groupId="qsClient"> <TabItem value="koito" label="Koito"> Setup a [Koito server](https://koito.io/guides/installation/) if you have not already done this.
* [Create (or get) an API Key](https://koito.io/guides/scrobbler/) * From your Koito server dashboard navigate to **Settings** (bottom-left icon) => **API Keys** * Create a new Key (or use an existing) and Copy the key using the copy icon to the right of the key * EX `pM195xPV98CDpk0QW47FIIOR8AKATAX5DblBF-Jq0t1MbbKL` * Take note of your Koito username (used below as <LocalStorageText client:load initialValue="myUser" stylePreset="placeholder" storageKey="myUser"/>) * Determine your Koito URL * This is the URL you use to access your Koito dashboard OR whatever URL is accessible from your multi-scrobbler instance. * EX dashboard at `http://192.168.0.100:4110` => replace <LocalStorageText client:load initialValue="myURL" stylePreset="placeholder" storageKey="myURL"/> below with `http://192.168.0.100:4110` * [More info on the URL to use is the full docs](/configuration/clients/koito)
Add/Substitute values above into these examples values and add them to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file)
```yaml placeholder="myToken,myUser,myURL" title="~/msData/docker-compose.yml" - KOITO_TOKEN=myToken - KOITO_USER=myUser - KOITO_URL=myURL - KOITO_ID=myKoito ```
:::tip For Koito versions `<=0.1.7`, you must have the environment variable `KOITO_ALLOWED_HOSTS` set correctly in your Koito environment/container. Ensure it is set to the IP address or domain name that you use to access Koito with e.g. `koito.mydomain.com`. :::
</TabItem> <TabItem value="teal" label="Teal.fm"> [**teal.fm**](https://teal.fm/) is a social discovery and browsing app for scrobbles stored in your [**Atmosphere Account**](https://atmosphereaccount.com/).
Navigate to the Account settings for your Atmosphere account on your respective PDS and create a new **App Password**.
<DetailsAdmo type="tip" summary="Determining Your Atmosphere Handle/Identifier"> <Handle/> </DetailsAdmo>
If you don't know what a PDS is or how to find this, just use Bluesky:
* Sign in to [Bluesky](https://bsky.app) with your Atmosphere Account * Navigate to https://bsky.app/settings/app-passwords * Settings -> Privacy and Security -> App passwords * Create a new **App Password** and save it somewhere, it will not be shown again
Add/Substitute values above into these examples values and add them to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file)
```yaml placeholder="myToken,alice.bsky.social,xxxx-xxxx-xxxx-xxxx" title="~/msData/docker-compose.yml" - TEALFM_ID=myTeal - TEALFM_IDENTIFIER=alice.bsky.social - TEALFM_APP_PW=xxxx-xxxx-xxxx-xxxx ``` </TabItem> <TabItem value="maloja" label="Maloja"> Setup a [Maloja server](https://github.com/krateng/maloja?tab=readme-ov-file#how-to-install) if you have not already done this.
<details>
<summary>Maloja Setup Intructions</summary>
Using Maloja's example `docker-compose.yml`:
<RemoteCode url="https://github.com/krateng/maloja/blob/master/example-compose.yml" lang="yaml" title="~/malojaData/docker-compose.yml" />
Uncomment `environment` and add `MALOJA_FORCE_PASSWORD=CHANGE_ME` to set an admin password
Start the container:
```shell title="~/malojaData" docker compose up -d ``` </details>
* Navigate to the Admin Panel (Cog in upper-right corner) -> API Keys (or at http://192.168.0.100:42010/admin_apikeys) * Create a **New Key** and then copy the generated key value
Finally, add these values to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" - MALOJA_URL=http://192.168.0.100:42010 - MALOJA_API_KEY=myApiKey - MALOJA_ID=myMaloja ``` </TabItem> <TabItem value="lastfm" label="Last.fm"> <Badge text="Warning!" size="small" variant="caution" /> [**Last.fm is ending free API Keys!**](/configuration/clients/lastfm) [Register for an API account at Last.fm.](https://www.last.fm/api/account/create)
Use the following for **Callback URL**:
```text placeholder="http://YOUR_MS_DOMAIN:9078" http://YOUR_MS_DOMAIN:9078/lastfm/callback ```
After account creation use the displayed information and add these values to the `environment` section in the [`docker-compose.yml` you created for multi-scrobbler earlier.](#create-docker-compose-file)
```yaml title="~/msData/docker-compose.yml" - LASTFM_API_KEY=myApiKey - LASTFM_SECRET=myApiSecret - LASTFM_ID=myLfmClient ``` </TabItem></Tabs>
## Start Multi-Scrobbler
:::tip
If you are running your multi-scrobbler container on a Linux host see [these instructions for setting proper file permissions.](/installation?dockerSetting=linuxHost#recommended-settings)
:::
From the same directory as the [`docker-compose.yml` you created earlier](#create-docker-compose-file) start the container:
```shell title="~/msData"docker compose up -d```
You're done! Multi-scrobbler is now running. It will monitor the sources you configured and scrobble to clients you set up.
Visit <code><LocalStorageText client:load initialValue="http://YOUR_MS_DOMAIN:9078" stylePreset="placeholder" storageKey="http://YOUR_MS_DOMAIN:9078"/></code> to see the dashboard where
* configured Sources/Clients * show current status and authentication options * display statistics about discovered/scrobbled tracks and Now Playing status* a real-time log shows multi-scrobbler's activity
## Next Steps
* **[Secure your Multi-Scrobbler instance](/security/overview)** <Badge text="Imporant" size="small" variant="tip" />* See more advanced docker options as well as other install methods in the [**Installation**](/installation#docker) docs * Setup [secondary caching](/configuration#secondary-caching) with [valkey](/installation?dockerSetting=caching#recommended-settings) for increased performance and reduced memory usage* Review the [**Configuration**](/configuration) docs * Learn about how to configure multi-scrobbler using files for more complicated Source/Client scenarios * See all available [**Sources**](/configuration/sources) and [**Clients**](/configuration/clients) alongside configuration examples * Learn how to set up [notification webhooks](/configuration#webhook-configurations) * Check out the [kitchensink example](/configuration/kitchensink)* Setup [Scrobble Enhancements](/configuration/transforms) with [Musicbrainz](/configuration/transforms/musicbrainz) to automatically correct and fill in missing track information for your scrobbles* Consult the [**FAQ**](/FAQ) for solutions to common problems