From 17ab07bf050a33004c7efcbb9f0422026e1d792b Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Tue, 29 Sep 2026 15:35:47 +0000 Subject: [PATCH] docs(spotify): More succint language around backlog scrobbling --- .../sources/_env_configs/_spotify.md | 18 +++++++++--------- docsite/docs/configuration/sources/spotify.mdx | 8 +++++--- .../infrastructure/config/source/index.ts | 2 +- .../infrastructure/config/source/spotify.ts | 2 +- 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/docsite/docs/configuration/sources/_env_configs/_spotify.md b/docsite/docs/configuration/sources/_env_configs/_spotify.md index 41e966a4..e05f5e5a 100644 --- a/docsite/docs/configuration/sources/_env_configs/_spotify.md +++ b/docsite/docs/configuration/sources/_env_configs/_spotify.md @@ -1,9 +1,9 @@ -| Environmental Variable | Type | Default | Description | -| ----------------------------- | ------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| _**`SPOTIFY_ID`**_ | string | | A globally unique ID EX `myComponentId` | -| `SPOTIFY_NAME` | string | Value of `SPOTIFY_ID` | A vanity name EX `My Cool Component` | -| `SPOTIFY_ENABLE` | boolean | true | Should this component be used? | -| _**`SPOTIFY_CLIENT_ID`**_ | string | | spotify client id | -| _**`SPOTIFY_CLIENT_SECRET`**_ | string | | spotify client secret | -| `SPOTIFY_REDIRECT_URI` | string | http://localhost:9078/callback | spotify redirect URI -- required only if not the default shown here. | -| `SPOTIFY_SCROBBLE_BACKLOG` | boolean | true | Fetch recent listening history on startup and periodically refetch from Spotify's API to reconcile plays missed during live tracking. Note: Backfilled tracks scrobble under Spotify's ~30s history rule rather than normal listen thresholds (see [Scrobble Threshold Trade-off](#scrobbling-backlog-and-reconciling-history)). | \ No newline at end of file +| Environmental Variable | Type | Default | Description | +| ----------------------------- | ------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _**`SPOTIFY_ID`**_ | string | | A globally unique ID EX `myComponentId` | +| `SPOTIFY_NAME` | string | Value of `SPOTIFY_ID` | A vanity name EX `My Cool Component` | +| `SPOTIFY_ENABLE` | boolean | true | Should this component be used? | +| _**`SPOTIFY_CLIENT_ID`**_ | string | | spotify client id | +| _**`SPOTIFY_CLIENT_SECRET`**_ | string | | spotify client secret | +| `SPOTIFY_REDIRECT_URI` | string | http://localhost:9078/callback | spotify redirect URI -- required only if not the default shown here. | +| `SPOTIFY_SCROBBLE_BACKLOG` | boolean | true | Should backlogging and history reconciliation be enabled? (see [Scrobbling Backlog and Reconciling History](#scrobbling-backlog-and-reconciling-history)). | \ No newline at end of file diff --git a/docsite/docs/configuration/sources/spotify.mdx b/docsite/docs/configuration/sources/spotify.mdx index f7b1b0a5..0b0148ac 100644 --- a/docsite/docs/configuration/sources/spotify.mdx +++ b/docsite/docs/configuration/sources/spotify.mdx @@ -123,13 +123,15 @@ When `scrobbleBacklog` is enabled (default `true`), multi-scrobbler will: * On startup, check Spotify's recent listening history to scrobble any backlogged tracks played while MS was not running. * Periodically (every 15 minutes), check Spotify's recent listening history to reconcile and backfill any plays that may have been missed by real-time tracking (for example, during Spotify Connect device switches or transient API dropouts). Any tracks already tracked or scrobbled in real-time are automatically deduplicated. -:::caution Scrobble Threshold Trade-off + + Under normal live playback tracking, multi-scrobbler enforces your configured [scrobble thresholds](/configuration/sources#scrobble-thresholds) (by default, listening to at least **50% of the track** or 4 minutes) before submitting a scrobble. -Due to Spotify API limitations, the recent history endpoint does not report playback duration or whether a track was skipped. Spotify automatically records any listen lasting at least ~30 seconds into your recent history. Consequently, **any track queued from backlog (at startup or via periodic reconcile) will be scrobbled if Spotify logged it (~30+ seconds)**, bypassing the standard 50% or 4-minute listen threshold. +Spotify's recent history endpoint, which is used for backlogging, considers any listen lasting at least ~30 seconds as valid history and this data also does not include playback duration so MS cannot analyze it like it does live plays. Consequently, **any track queued from backlog (at startup or via periodic reconcile) will be scrobbled if Spotify logged it (~30+ seconds)**, bypassing the standard 50% or 4-minute listen threshold. If you prefer to strictly enforce duration thresholds and avoid scrobbling short/skipped listens that Spotify logged to history, set `scrobbleBacklog` to `false` in your Spotify source options (or via ENV `SPOTIFY_SCROBBLE_BACKLOG=false`). -::: + + ## Configuration diff --git a/src/backend/common/infrastructure/config/source/index.ts b/src/backend/common/infrastructure/config/source/index.ts index 6b47ae24..a34991b3 100644 --- a/src/backend/common/infrastructure/config/source/index.ts +++ b/src/backend/common/infrastructure/config/source/index.ts @@ -138,7 +138,7 @@ export const commonSourceOptionsSchema = z.object({ * @examples [true, false] * */ scrobbleBacklog: z.boolean().optional().meta({ - description: "If this source", + description: "If this source supports fetching listen history and this option is enabled then on startup MS will attempt to scrobble the recent listens from that history", default: true, examples: [true, false] }), diff --git a/src/backend/common/infrastructure/config/source/spotify.ts b/src/backend/common/infrastructure/config/source/spotify.ts index b5ab01a4..621d6ac9 100644 --- a/src/backend/common/infrastructure/config/source/spotify.ts +++ b/src/backend/common/infrastructure/config/source/spotify.ts @@ -83,7 +83,7 @@ const envDataSchema = z.object({ SPOTIFY_CLIENT_SECRET: spotifySourceDataSchema.shape.clientSecret, SPOTIFY_REDIRECT_URI: spotifySourceDataSchema.shape.redirectUri, SPOTIFY_SCROBBLE_BACKLOG: z.stringbool().optional().meta({ - description: "Fetch recent listening history on startup and periodically refetch from Spotify's API to reconcile plays missed during live tracking. Note: Backfilled tracks scrobble under Spotify's ~30s history rule rather than normal listen thresholds (see [Scrobble Threshold Trade-off](#scrobbling-backlog-and-reconciling-history)).", + description: "Should backlogging and history reconciliation be enabled? (see [Scrobbling Backlog and Reconciling History](#scrobbling-backlog-and-reconciling-history)).", default: true }), }); -- 2.51.2