From 6d187893dadfd5fb9eb4bef0cc7aa334159e55ef Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Sun, 27 Sep 2026 17:54:38 +0000 Subject: [PATCH] docs: Add stage name and ENV stage name guidance --- .../transforms/coverartarchive.mdx | 2 + .../configuration/transforms/musicbrainz.mdx | 2 + .../docs/configuration/transforms/native.mdx | 2 + .../docs/configuration/transforms/rocksky.mdx | 4 +- .../docs/configuration/transforms/spotify.mdx | 2 + .../configuration/transforms/transforms.mdx | 41 ++++++++++++++++++- .../docs/configuration/transforms/user.mdx | 2 - 7 files changed, 51 insertions(+), 4 deletions(-) diff --git a/docsite/docs/configuration/transforms/coverartarchive.mdx b/docsite/docs/configuration/transforms/coverartarchive.mdx index 49dfad4a..732a902a 100644 --- a/docsite/docs/configuration/transforms/coverartarchive.mdx +++ b/docsite/docs/configuration/transforms/coverartarchive.mdx @@ -275,6 +275,8 @@ services: +To use the configured ENV stage in [Rules and Hooks](#rules-and-hooks) with File/AIO config either [omit `name` or specify it as `"name": "MSEnv"`.](/configuration/transforms#stage-names-and-default-stages) + ## Finding Art :::note diff --git a/docsite/docs/configuration/transforms/musicbrainz.mdx b/docsite/docs/configuration/transforms/musicbrainz.mdx index f4fd0814..57fb3319 100644 --- a/docsite/docs/configuration/transforms/musicbrainz.mdx +++ b/docsite/docs/configuration/transforms/musicbrainz.mdx @@ -368,6 +368,8 @@ services: +To use the configured ENV stage in [Rules and Hooks](#rules-and-hooks) with File/AIO config either [omit `name` or specify it as `"name": "MSEnv"`.](/configuration/transforms#stage-names-and-default-stages) + ## Matching with Musicbrainz :::note diff --git a/docsite/docs/configuration/transforms/native.mdx b/docsite/docs/configuration/transforms/native.mdx index a8f632ee..380d0607 100644 --- a/docsite/docs/configuration/transforms/native.mdx +++ b/docsite/docs/configuration/transforms/native.mdx @@ -39,6 +39,8 @@ Will be transformed into this } ``` +To use the default Stage in [Rules and Hooks](#rules-and-hooks) either omit `name` or specify it as `"name": "MSDefault"`. + ## Configuration Available properties for [Stage Configuration](/configuration/transforms#configuring-stages): diff --git a/docsite/docs/configuration/transforms/rocksky.mdx b/docsite/docs/configuration/transforms/rocksky.mdx index 17858eee..e98cc7d2 100644 --- a/docsite/docs/configuration/transforms/rocksky.mdx +++ b/docsite/docs/configuration/transforms/rocksky.mdx @@ -9,7 +9,7 @@ import TabItem from '@theme/TabItem'; The **Rocksky** [Stage](/configuration/transforms#stage) matches your Play with metadata from [Rocksky](https://rocksky.app/). If the match score is high enough then Multi-Scrobbler uses the match to correct and fill-in some missing information in your Play data. -**This Stage is useful for normalzing plays for the Rocksky scrobbler or adding metadata ids and artwork from a fast metadata provider.** +**This Stage is useful for normalizing plays for the Rocksky scrobbler or adding metadata ids and artwork from a fast metadata provider.** :::important @@ -291,6 +291,8 @@ services: +To use the configured ENV stage in [Rules and Hooks](#rules-and-hooks) with File/AIO config either [omit `name` or specify it as `"name": "MSEnv"`.](/configuration/transforms#stage-names-and-default-stages) + ## What Data is Applied? Rocksky metadata is still maturing so **the data MS ultimately applies your scrobbles is artifically restricted at this time.** diff --git a/docsite/docs/configuration/transforms/spotify.mdx b/docsite/docs/configuration/transforms/spotify.mdx index 4bdbc0a1..f135cf6d 100644 --- a/docsite/docs/configuration/transforms/spotify.mdx +++ b/docsite/docs/configuration/transforms/spotify.mdx @@ -222,6 +222,8 @@ services: +To use the configured ENV stage in [Rules and Hooks](#rules-and-hooks) with File/AIO config either [omit `name` or specify it as `"name": "MSEnv"`.](/configuration/transforms#stage-names-and-default-stages) + ## Matching with Spotify :::note diff --git a/docsite/docs/configuration/transforms/transforms.mdx b/docsite/docs/configuration/transforms/transforms.mdx index 0a83fc6e..1fa10983 100644 --- a/docsite/docs/configuration/transforms/transforms.mdx +++ b/docsite/docs/configuration/transforms/transforms.mdx @@ -206,7 +206,6 @@ In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?co ] ``` - Multiple stages of the same type may be configured, allowing you to define several sets of default behavior. @@ -287,6 +286,46 @@ In a [VLC](/configuration/sources/vlc) [File Config](/configuration?configType=f +#### Stage Names and Default Stages + +When specifying a Stage within a [Hook](#hook) (like in `preCompare`), the `name` for a Stage is **potentially optional.** + +If Stages exists for the `type` you want to use in the hook and you do not specify a `name`... + +
+ +Example + +```json5 title="vlc.json" +[ + { + "name": "MyVLC", + "data": { /* ... */}, + "options": { + "playTransform": { + "preCompare": [ + { + "type": "rocksky" + // no "name" is specified + } + ] + } + } + } +] +``` + +
+ +Multi-Scrobbler looks for configured Stages in this order: + +* The *first* non-default, non-ENV configured Stage IE a [Stage](#stage) you [configured](#configuring-stages) with an explicit `name` +* An ENV configured stage, like [Rocksky's ENV Configuration](/configuration/transforms/rocksky#env-configuration) + * ENV configured stages are always named `MSEnv` +* The **default**, built-in Stage from Multi-Scrobbler. This is always named `MSDefault` + +All of the [Modification Stages](#stage) have an `MSDefault` configured Stage except for Spotify. + #### Overriding Configuration The default configuration you set for your Stage may be overridden in any usage of the Stage within a Hook. diff --git a/docsite/docs/configuration/transforms/user.mdx b/docsite/docs/configuration/transforms/user.mdx index 0c292d0e..390bb4ec 100644 --- a/docsite/docs/configuration/transforms/user.mdx +++ b/docsite/docs/configuration/transforms/user.mdx @@ -13,8 +13,6 @@ This Stage is most useful for correcting individual instances of bad data, or pa * Removing `Various Artists` from Artist data * Correcting spelling mistakes for individual Artist names -The user [Stage `type`](/configuration/transforms#stage) is `user`. - ## Configuration All [Stage Configuration](/configuration/transforms#configuring-stages) is done using [**search-and-replace** expressions](#search-and-replace-expression) inside individual [rules](#rules). Default configuration for all Rules can still be done using Stage `defaults`. -- 2.51.2