From abdd7f0b555ee995d9ac8c63bae07de17763e01b Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Tue, 4 Nov 2025 18:48:04 +0000 Subject: [PATCH] docs: Improved linking on config/landing and configuration type refinement --- README.md | 8 +-- docsite/docs/configuration/configuration.mdx | 74 +++++++++++++++----- docsite/docs/index.mdx | 8 +-- docsite/docs/quickstart.mdx | 4 +- 4 files changed, 68 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 6fb1acd0..3ced3bb0 100644 --- a/README.md +++ b/README.md @@ -48,7 +48,7 @@ A javascript app to scrobble music you listen to, to [Maloja](https://github.com * Web server interface for stats, basic control, and detailed logs * Graceful network and client failure handling (queued scrobbles that auto-retry) * Smart handling of credentials (persistent, authorization through app) -* Easy configuration through ENVs or JSON +* Easy configuration through [ENVs or JSON](ttps://foxxmd.github.io/multi-scrobbler/configuration#configuration-types) * Modify data before scrobbling with [regular expression or search patterns](https://foxxmd.github.io/multi-scrobbler/configuration/transforms) * Install using [Docker images for x86/ARM](https://foxxmd.github.io/multi-scrobbler/installation#docker) or [locally with NodeJS](https://foxxmd.github.io/multi-scrobbler/installation#nodejs) @@ -69,11 +69,11 @@ Yes! You can use [Last.fm as a **Source**](https://foxxmd.github.io/multi-scrobb ## How Does multi-scrobbler (MS) Work? -You set up configurations for one or more **Sources** and one or more **Clients**. MS monitors all of your configured **Sources**. When new tracks are played by a Source it grabs that information and then sends it (scrobbles it) to all **Clients** that Source is configured to scrobble to. +You set up [configurations](https://foxxmd.github.io/multi-scrobbler/configuration) for one or more [**Sources**](https://foxxmd.github.io/multi-scrobbler/configuration/sources) and one or more [**Clients**](https://foxxmd.github.io/multi-scrobbler/configuration/clients). MS monitors all of your configured **Sources**. When new tracks are played by a Source MS grabs that information and then sends it (scrobbles it) to all **Clients** that Source is configured to forward to. ### Source -A **Source** is a data source that contains information about tracks you are playing like a music player or platform. Examples are **Spotify, Jellyfin, Plex, Youtube Music, Airsonic**, etc... +A [**Source**](https://foxxmd.github.io/multi-scrobbler/configuration/sources) is a data source that contains information about music you are playing or have listened to, like a desktop player, web music player, or cloud music service. Examples are **Spotify, Jellyfin, Plex, Youtube Music, Navidrome**, etc... Source configurations consist of: @@ -83,7 +83,7 @@ Source configurations consist of: ### Client -A **Client** is an application that stores the historical information about what songs you have played (scrobbles). Examples are **Maloja, Last.fm, Listenbrainz**... +A [**Client**](https://foxxmd.github.io/multi-scrobbler/configuration/clients) is an application that stores the historical information about what music you have played (scrobbles). Examples are **Maloja, Last.fm, Listenbrainz**... Client configurations consist of: diff --git a/docsite/docs/configuration/configuration.mdx b/docsite/docs/configuration/configuration.mdx index a67f61f1..02a42db0 100644 --- a/docsite/docs/configuration/configuration.mdx +++ b/docsite/docs/configuration/configuration.mdx @@ -22,7 +22,7 @@ Check the [**FAQ**](../FAQ.md) if you have any issues after configuration! ## Configuration Types -[**Sources** and **Clients**](/#how-does-multi-scrobbler-ms-work) are configured using: +[**Sources**](/configuration/sources) and [**Clients**](/configuration/clients) are configured using: * environmental (ENV) variables * client/source specific json config files @@ -32,15 +32,46 @@ Check the [**FAQ**](../FAQ.md) if you have any issues after configuration! - This is done by passing environmental variables and so does not require any files to run MS. + MS will parse environmental variables present in the OS/container when it is run. **This method means MS does not require files to run.** - * Using a docker container EX `docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" ...` - * Using a local installations by exporting variables before running MS EX `SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret node index.js` +
+ Use ENV-based configuration if... + + * You are the only person for whom MS is scrobbling for + * You have a very simple setup for MS such as one scrobble [Client](/configuration/clients) and one [Source](/configuration/sources) IE Plex -> Maloja - Use ENV-based configuration if: +
- * You are the only person for whom MS is scrobbling for - * You have a very simple setup for MS such as one scrobble [Client](/#client) and one [Source](/#source) IE Plex -> Maloja +
+ Config Example + + For Docker container... + + ```shell + docker run -e "SPOTIFY_CLIENT_ID=yourId" -e "SPOTIFY_CLIENT_SECRET=yourSecret" ... + ``` + + For Docker Compose + + ```yaml title="docker-compose.yml" + services: + multi-scrobbler: + image: foxxmd/multi-scrobbler + environment: + - SPOTIFY_CLIENT_ID=yourId + - SPOTIFY_CLIENT_SECRET=yourSecret + - MALOJA_URL=http://domain.tld:42010 + - MALOJA_API_KEY=1234 + # ... + # ... + ``` + + For a local/node installation export variables before running... + + ```shell + SPOTIFY_CLIENT_ID=yourId SPOTIFY_CLIENT_SECRET=yourSecret npm run start + ``` +
MS will parse configuration files located in the directory specified by the `CONFIG_DIR` environmental variable. This variable defaults to: @@ -52,18 +83,19 @@ Check the [**FAQ**](../FAQ.md) if you have any issues after configuration! Use File-based configuration if... - * You have many [Sources](/#source) + * You have many [Sources](/configuration/sources) * You have many of each type of **Source** you want to scrobble from IE 2x Plex accounts, 3x Spotify accounts, 1x Funkwhale... * You have more than one scrobble **Client** you want to scrobble to IE multiple Maloja servers - * You want only some **Sources** to scrobble to some **Clients** IE Fred's Spotify account scrobbles to Fred's Maloja - server, but not Mary's Maloja server + * You want only to scrobble to specific **Clients** + * You need to setup more advanced configuration for a Source/Client + * Most Source/Clients only support basic configuration through ENV, all configuration is possible using File/AIO :::tip * There are **example configurations** for all Source/Client types and AIO config located in the [`/config`](https://github.com/FoxxMD/multi-scrobbler/tree/master/config) directory of this project. These can be used as-is by renaming them to `.json`. - * For docker/flatpak installations these examples are copied to your configuration directory on first-time use. + * For docker installations these examples are copied to your configuration directory on first-time use. * There is also a [**kitchensink example**](kitchensink.md) that provides examples of using all sources/clients in a complex configuration. ::: @@ -95,12 +127,13 @@ Check the [**FAQ**](../FAQ.md) if you have any issues after configuration! Use AIO-based configuration if... - * You have many [Sources](/#source) + * You have many [Sources](/configuration/sources) * You have many of each type of **Source** you want to scrobble from IE 2x Plex accounts, 3x Spotify accounts, 1x Funkwhale... * You have more than one scrobble **Client** you want to scrobble to IE multiple Maloja servers - * You want only some **Sources** to scrobble to some **Clients** IE Fred's Spotify account scrobbles to Fred's Maloja - server, but not Mary's Maloja server + * You want only to scrobble to specific **Clients** + * You need to setup [monitoring/webhooks](#monitoring) + * You want to setup defaults for all Sources/Clients @@ -108,7 +141,7 @@ Check the [**FAQ**](../FAQ.md) if you have any issues after configuration! :::tip * An example AIO config files can be found in the project directory at [`/config/config.json.example`](https://github.com/FoxxMD/multi-scrobbler/tree/master/config/config.json.example) - * For docker/flatpak installations this example is copied to your configuration directory on first-time use. + * For docker installations this example is copied to your configuration directory on first-time use. * There is also a [**kitchensink example**](kitchensink.md) that provides examples of using all sources/clients in a complex configuration. ::: @@ -124,6 +157,15 @@ Check the [**FAQ**](../FAQ.md) if you have any issues after configuration! +## Setup Sources and Clients + +See the [Configuration Types](#configuration-types) above for your options for creating Source and Client configurations. + +* Reference [**Scrobble Sources**](/configuration/sources) for what Sources are available +* Reference [**Scrobble Clients**](/configuration/clients) for what Clients are available + +Each entry for a Source/Client includes a **Configuration** section that describes how to configure it using a [configuration type](#configuration-types). + ## Application Options These options affect multi-scrobbler's behavior and are not specific to any source/client. @@ -265,7 +307,7 @@ To set debug mode either add it to [AIO `config.json`](./?configType=aio#configu } ``` -or set the ENV `DEBUG_MODE=true` +or set the [ENV](./?configType=env#configuration-types) `DEBUG_MODE=true` ### Disable Web diff --git a/docsite/docs/index.mdx b/docsite/docs/index.mdx index 2d4c1dc7..4579741d 100644 --- a/docsite/docs/index.mdx +++ b/docsite/docs/index.mdx @@ -49,7 +49,7 @@ A javascript app to scrobble music you listened to, to [Maloja](https://github.c * Web server interface for stats, basic control, and detailed logs * Graceful network and client failure handling (queued scrobbles that auto-retry) * Smart handling of credentials (persistent, authorization through app) -* Easy configuration through ENVs or JSON +* Easy configuration through [ENVs or JSON](/configuration#configuration-types) * Modify data before scrobbling with [regular expression or search patterns](/configuration/transforms) * Install using [Docker images for x86/ARM](/installation#docker) or [locally with NodeJS](/installation#nodejs) @@ -70,11 +70,11 @@ Yes! You can use [Last.fm as a **Source**](/configuration/sources/lastfm-source) ## How Does multi-scrobbler (MS) Work? -You set up configurations for one or more **Sources** and one or more **Clients**. MS monitors all of your configured **Sources**. When new tracks are played by a Source it grabs that information and then sends it (scrobbles it) to all **Clients** that Source is configured to scrobble to. +You set up [configurations](/configuration) for one or more [**Sources**](/configuration/sources) and one or more [**Clients**](/configuration/clients). MS monitors all of your configured **Sources**. When new tracks are played by a Source MS grabs that information and then sends it (scrobbles it) to all **Clients** that Source is configured to forward to. ### Source -A **Source** is a data source that contains information about tracks you are playing like a music player or platform. Examples are **Spotify, Jellyfin, Plex, Youtube Music, Airsonic**, etc... +A [**Source**](/configuration/sources) is a data source that contains information about music you are playing or have listened to, like a desktop player, web music player, or cloud music service. Examples are **Spotify, Jellyfin, Plex, Youtube Music, Navidrome**, etc... Source configurations consist of: @@ -84,7 +84,7 @@ Source configurations consist of: ### Client -A **Client** is an application that stores the historical information about what songs you have played (scrobbles). Examples are **Maloja, Last.fm, Listenbrainz**... +A [**Client**](/configuration/clients) is an application that stores the historical information about what music you have played (scrobbles). Examples are **Maloja, Last.fm, Listenbrainz**... Client configurations consist of: diff --git a/docsite/docs/quickstart.mdx b/docsite/docs/quickstart.mdx index 5fd13e5a..0cfdb632 100644 --- a/docsite/docs/quickstart.mdx +++ b/docsite/docs/quickstart.mdx @@ -42,7 +42,7 @@ services: ## Setup Sources -**Sources** are the services multi-scrobbler monitors to look for listening activity. +[**Sources**](/configuration/sources) are the services/music players multi-scrobbler monitors to look for listening activity. @@ -76,7 +76,7 @@ services: ## Setup Clients -**Clients** are services that store scrobbles. Multi-scrobbler will scrobble all listening activity from the **Sources** you configured to all **Clients** you configure here. +[**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. -- 2.51.2