Something went wrong. Try again.
[READ-ONLY] Mirror of https://github.com/FoxxMD/multi-scrobbler. Scrobble plays from multiple sources to multiple clients docs.multi-scrobbler.app
deezer docker jellyfin koito lastfm listenbrainz maloja mopidy mpris music music-assistant plex scrobble self-hosted spotify subsonic tautulli youtube-music
Something went wrong. Try again.
9.0 kB · 301 lines
MDX
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301---title: Native Stagedescription: Enhancing Scrobbles with Built-in Parsingtoc_min_heading_level: 2toc_max_heading_level: 5---
The **Native** [Stage](/configuration/transforms#stage) uses [built-in heuristics](https://github.com/FoxxMD/multi-scrobbler/blob/master/src/backend/tests/plays/playParsing.test.ts) to try to extract Artists from Play artist/track data.
This Stage is most useful for Sources that report limited data such as:
* [Subsonic](/configuration/sources/subsonic) - Reports Artists as a single string
A non-exhaustive list of heuristics:
* Splits artists in artist string using common delimiters EX `Foo Artist, Bar Guy, Baz Band - My Cool Song` * Does not split artists with `&` in name, if other delimiters are present * Does not split artist name when only one delimiter is present* 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"]}```
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):
* `delimitersExtra` - A list of string characters that should be considered delimiters for artists **in addition to** multi-scrobbler's default list (`, / \ `)* `delimiters` - A list of string characters that should be considered delimiters for artists. * **Replaces** all delimiters (MS not use any defaults, only what you give it)* `artistsIgnore` - a list of strings and/or regular expressions. Any monolothic artist string that matches from the list _will not be modified._* `artistsParseFrom` a list of the properties that should be used to try to extract artists. Can be `artists` `title` or both. Defaults to both when not provided in options ( `["artists", "title"]` ) * When `artists` is present it tries to extract additional artists from artist strings * When `title` is present it tries to extract artists from ft. feat. vs. etc... found in the track title * Importantly, if `artists` is _not_ present in `artistsParseFrom` then _no artists_ are used at all (only those from `title`, if present)* `artistsParseMonolithicOnly` - boolean value, defaults to `true`. When `true` native tranformer will only attempt to extract artists if the scrobble data has _only one string for artist_ (pre-transform) * This means that, for Sources like Spotify/Jellyfin/etc. that provide proper lists of artists in their data _and the list has more than one string_, it will not try to extract artists from their strings
<details>
<summary>Example of the behavior for `artistsParseFrom`</summary>
```The Foos, The Bars - My Cool Track (ft. Frank)```
Config => extracted artists
```"artistsParseFrom": ["artists", "title"] => The Foos, The Bars, Frank"artistsParseFrom": ["artists"] => The Foos, The Bars"artistsParseFrom": ["title"] => Frank"artistsParseFrom": [] =>```
</details>
### Rules
Each [Rule](/configuration/transforms#stage-rules) should be either a boolean, specifying if the transformed data should be used for this field, or a [`when` condition.](/configuration/transforms#conditional-modification):
```json5{ "type": "native", // ... "title": false, // will not apply any changes to Play title "artists": { "when": {/* ... */}, // will only apply changes to Play artists if "when" is satisfied /* ... */ }, "album": true // will always apply changes to Play album}```
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#stage).
<details>
<summary>Example</summary>
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 } ] } } }]```</details>
## ENV Configuration
The default configuration shown above can also be applied using [ENV Config](/configuration?configType=env#configuration-types) for individual Sources/Clients.
Use ENV `*_TRANSFORMS=native` on each Source/Client you wish to apply this stage to. This applies the stage in the [`preTransform` Hook](/configuration/transforms#lifecycle-hooks) with all [Rules](#rules) enabled.
The `*` stands for the prefix used for each Source/Client's ENV keys. Refer to the individual Source/Client Configuration sections to find this. Example
* All [Subsonic Source](/configuration/sources/subsonic/) ENVs look like `SUBSONIC_USER=myuser` etc...* Use `SUBSONIC_TRANSFORMS=native`
<details>
<summary>Example Full Docker Deploy with ENV Configuration</summary>
Using [Jellyfin + Maloja](/quickstart#create-docker-compose-file) example from Quickstart:
```yamlservices: multi-scrobbler: image: foxxmd/multi-scrobbler container_name: multi-scrobbler environment: - JELLYFIN_URL=192.168.0.110:8096 - JELLYFIN_APIKEY=c9fae8756fbf481ebd9c5bb56b - JELLYFIN_USER=MyUser - JELLYFIN_TRANSFORMS=native # applies native Stage to preTransform of Jellyfin source
- MALOJA_URL=http://192.168.0.100:42010 # maloja receives enhanced scrobble from Jellyfin - MALOJA_API_KEY=myApiKey
volumes: - "./config:/config" ports: - "9078:9078" restart: unless-stopped```
</details>
## Examples
### Parse only artists string using a custom delimiter
<details>
<summary>Example</summary>
Your [AIO Config](/configuration?configType=aio#configuration-types):
```json5 title="config.json"{ // ... "transformers": [ { "type": "native", "name": "MyNativeTransformer", "defaults": { // default delimiters when this Stage is used in a hook "delimiters": [ "•" ], // default delimiters when this Stage is used in a hook "artistsParseFrom": ["artists"] } } ]}```
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", "name": "MyNativeTransformer" } ] } } }]```</details>
### Don't parse specific artists
<details>
<summary>Example</summary>
Your [AIO Config](/configuration?configType=aio#configuration-types):
```json5 title="config.json"{ // ... "transformers": [ { "type": "native", "name": "MyNativeTransformer", "defaults": { "artistsIgnore": [ "Crosby, Stills, Nash & Young", "Polo & Pan" ] } } ]}```
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", "name": "MyNativeTransformer" } ] } } }]```</details>
### 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:
<details>
<summary>Example</summary>
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 } ] } } }]```</details>