From 88b81dcd122e47adc83860f6a22d569fc1277885 Mon Sep 17 00:00:00 2001 From: FoxxMD Date: Thu, 11 Dec 2025 16:23:16 +0000 Subject: [PATCH] docs(tranforms): Add default stage --- .../configuration/transforms/musicbrainz.mdx | 2 +- .../docs/configuration/transforms/native.mdx | 83 +++++++++++++++++++ .../configuration/transforms/transforms.mdx | 8 +- .../docs/configuration/transforms/user.mdx | 36 ++++++++ 4 files changed, 127 insertions(+), 2 deletions(-) diff --git a/docsite/docs/configuration/transforms/musicbrainz.mdx b/docsite/docs/configuration/transforms/musicbrainz.mdx index 425f20c2..50c1f12d 100644 --- a/docsite/docs/configuration/transforms/musicbrainz.mdx +++ b/docsite/docs/configuration/transforms/musicbrainz.mdx @@ -656,7 +656,7 @@ In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?co ### Sensible Default -Using the config shown in [Sensible Default](#sensible-default). +Using the config shown in [Sensible Default](#sensible-default) with File/AIO config, instead of [ENV Config](#env-configuration).
diff --git a/docsite/docs/configuration/transforms/native.mdx b/docsite/docs/configuration/transforms/native.mdx index 45f2e773..c8dd6412 100644 --- a/docsite/docs/configuration/transforms/native.mdx +++ b/docsite/docs/configuration/transforms/native.mdx @@ -18,6 +18,25 @@ A non-exhaustive list of heuristics: * Splits artists on common joiner phrases (ft. feat. vs. etc...) * Extracts artists from Play title using joiner phrases EX `My Cool Song (feat. SomeGuy)` +A practical example of what the Native Stage will do to Play data: + +This Scrobble from [Subsonic](/configuration/sources/subsonic) + +```json +{ + "title": "Endless Possibility (feat. Wheatus)", + "artists": ["Bowling For Soup & Punk Rock Factory"] +} +``` + +Will be transformed into this + +```json +{ + "title": "Endless Possibility", + "artists": ["Bowling For Soup", "Punk Rock Factory", "Wheatus"] +} +``` ## Configuration @@ -73,6 +92,38 @@ Each [Rule](/configuration/transforms#stage-rules) should be either a boolean, s If a rule is not present then multi-scrobbler defaults it to `true`. +### Default Stage + +For your convenience, if you do not define any Native [Stage Configurations](/configuration/transforms#configuring-stages) then multi-scrobbler automatically builds one using the defaults shown in [configuration](#configuration). + +This can be used by omitting the `name` in your [modification Stage](/configuration/transforms#modification-stage). + +
+ +Example + +In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?configType=file#configuration-types): + +```json5 title="subsonic.json" +[ + { + "name": "MySubsonic", + "data": { /* ... */}, + "options": { + "playTransform": { + "preCompare": [ + { + "type": "native", + // do not include name, the default native stage will be used + } + ] + } + } + } +] +``` +
+ ## ENV Configuration The default configuration shown above can also be applied using [ENV Config](/configuration?configType=env#configuration-types) for individual Sources/Clients. @@ -215,4 +266,36 @@ In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?co } ] ``` +
+ +### Extract Artists from Title but do not modify Title + +In the scenario where you want to extract Artists from Track titles with joiners like `My Cool Track (feat. Foobar)` but want to keep the title as-is: + +
+ +Example + +No additional [stage configuration](#configuration) is required so we can use the [default Stage](#default-stage). + +In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?configType=file#configuration-types): + +```json5 title="subsonic.json" +[ + { + "name": "MySubsonic", + "data": { /* ... */}, + "options": { + "playTransform": { + "preCompare": [ + { + "type": "native", + "title": false // do not modify title + } + ] + } + } + } +] +```
\ No newline at end of file diff --git a/docsite/docs/configuration/transforms/transforms.mdx b/docsite/docs/configuration/transforms/transforms.mdx index f40e6a39..57c5bacf 100644 --- a/docsite/docs/configuration/transforms/transforms.mdx +++ b/docsite/docs/configuration/transforms/transforms.mdx @@ -92,6 +92,12 @@ For example, to modify the track so it's the same anywhere it is processed in mu ::: +:::tip[TLDR] + +**To modify a scrobble coming from one of your Sources use the `preCompare` hook.** + +::: +
Using `compare` hook @@ -125,7 +131,7 @@ Each [**hook**](#hook) is made up of one or more **Stages**. A Stage is a self-c * The [User](/configuration/transforms/user) Stage allows a user to define search-and-replace terms for Artist/Title/Album * The [Native](/configuration/transforms/native) Stage uses MS's built-in heuristics to extract Artists from a single Artist string -* The Musicbrainz Stage tries to match Play data with the Musicbrainz database and to standardize the Artist/Title/Album data +* The [Musicbrainz](/configuration/transforms/musicbrainz) Stage tries to match Play data with the Musicbrainz database and to standardize the Artist/Title/Album data Each Stage in a Hook receives Play data from the previous Stage. diff --git a/docsite/docs/configuration/transforms/user.mdx b/docsite/docs/configuration/transforms/user.mdx index 7492f8a7..5b87f2fe 100644 --- a/docsite/docs/configuration/transforms/user.mdx +++ b/docsite/docs/configuration/transforms/user.mdx @@ -44,6 +44,42 @@ All [Stage Configuration](/configuration/transforms#configuring-stage) is done u
+#### Default Stage + +For your convenience, if you do not define any User [Stage Configurations](/configuration/transforms#configuration) then multi-scrobbler automatically builds an empty one for you. + +This can be used by omitting the `name` in your [modification Stage](/configuration/transforms#modification-stage). + +
+ +Example + +In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?configType=file#configuration-types): + +```json5 title="subsonic.json" +[ + { + "name": "MySubsonic", + "data": { /* ... */}, + "options": { + "playTransform": { + "preCompare": [ + { + "type": "user", + // do not include name, the default user stage will be used + "title": [ + // removes badterm from track title + "badterm" + ] + } + ] + } + } + } +] +``` +
+ ### Search-And-Replace Expression A Search-And-Replace Expression can be a plain string that matches a literal, then removes it: -- 2.51.2