multi-scrobbler/docsite/docs/quickstart.mdx

---
title: 'Quickstart'
sidebar_position: 2
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

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 an IP of `192.168.0.100`
* 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 `192.168.0.100` with `localhost`.

:::

## Create Docker Compose File

Create a new folder for multi-scrobbler related data and then create `docker-compose.yml` with this content:

```yaml title="~/msData/docker-compose.yml"
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
      - BASE_URL=http://192.168.0.100:9078
      # all Environmental Variables in below examples go here!

    volumes:
      - "./config:/config"
    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 # URL to Jellyfin UI
        - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56b # Api Key created in previous step
        - JELLYFIN_USER=MyUser # Your username in Jellyfin
        ```
    </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"
        - SPOTIFY_CLIENT_ID=yourClientId
        - SPOTIFY_CLIENT_SECRET=yourClientSecret
        - SPOTIFY_REDIRECT_URI=https://multi-scrobbler.mydomain.com/callback
        ```

        Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100: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
        ```

        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 `http://myMultiScrobblerIP:9078/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"
        - ND_LISTENBRAINZ_BASEURL=http://192.168.0.100: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
        # 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">
        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**:

        ```
        http://192.168.0.100: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"
        - SOURCE_LASTFM_API_KEY=MY_API_KEY_PLACEDHOLDER
        - SOURCE_LASTFM_SECRET=MY_SECRET_PLACEHOLDER
        - SOURCE_LASTFM_REDIRECT_URI=http://192.168.0.100:9078/lastfm/callback
        ```

        Later, after [starting multi-scrobbler](#start-multi-scrobbler), visit the dashboard at `http://192.168.0.100: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>

## (Optional) Correct Scrobbles with Musicbrainz

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.

:::

You must provide a way for Musicbrainz to [contact you.](https://wiki.musicbrainz.org/MusicBrainz_API/Rate_Limiting#How_can_I_be_a_good_citizen_and_be_smart_about_using_the_Web_Service?)

Add these value to the `environment` section in the [`docker-compose.yml` you created.](#create-docker-compose-file)

```yaml title="~/msData/docker-compose.yml"
# an email or personal website musicbrainz can use to contact you
- MB_CONTACT=myCoolName@emailProvider.com 
# 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"
[
  {
    "name": "myLastFmSource",
    "configureAs": "source",
    "data": {
      "apiKey": "MY_API_KEY_PLACEDHOLDER",
      "secret": "MY_SECRET_PLACEHOLDER",
      "redirectUri": "http://192.168.0.100:9078/lastfm/callback"
    // highlight-start
    },
    "options": {
      "playTransform": {
        "preCompare": {
          "type": "musicbrainz"
        }
      }
    }
    // highlight-end
  }
]
```
</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 `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 `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 title="~/msData/docker-compose.yml"
        - KOITO_TOKEN=myToken
        - KOITO_USER=myUser
        - KOITO_URL=myURL
        ```

        :::tip

        Ensure that Koito is configured to allow requests from multi-scrobbler! In Koito config set [`KOITO_ALLOWED_HOSTS`](https://koito.io/reference/configuration/#koito_allowed_hosts) to the IP the multi-scrobbler dashboard is accessible from.

        :::

    </TabItem>
    <TabItem value="lastfm" label="Last.fm">
        [Register for an API account at Last.fm.](https://www.last.fm/api/account/create)

        Use the following for **Callback URL**:

        ```
        http://192.168.0.100: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
        ```
    </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`:

            ```yaml reference title="~/malojaData/docker-compose.yml"
            https://github.com/krateng/maloja/blob/master/example-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
        ```
    </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#linux-host)

:::

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 `http://192.168.0.100:9078` 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

* See more advanced docker options as well as other install methods in the [**Installation**](/installation#docker) docs
* 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