Skip to main content

# Native Stage

The Native Stage uses built-in heuristics to try to extract Artists from Play artist/track data.

This Stage is most useful for Sources that report limited data such as:

- 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

    {
        "title": "Endless Possibility (feat. Wheatus)",
        "artists": ["Bowling For Soup & Punk Rock Factory"]
    }

Will be transformed into this

    {
        "title": "Endless Possibility",
        "artists": ["Bowling For Soup", "Punk Rock Factory", "Wheatus"]
    }

## Configuration​

Available properties for Stage Configuration:

- `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

Example of the behavior for `artistsParseFrom`

    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": []                          =>

### Rules​

Each Rule should be either a boolean, specifying if the transformed data should be used for this field, or a `when` condition.:

    {
        "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 then multi-scrobbler automatically builds one using the defaults shown in configuration.

This can be used by omitting the `name` in your modification Stage.

Example

In a Subsonic File Config:

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 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 with all 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 ENVs look like `SUBSONIC_USER=myuser` etc...
- Use `SUBSONIC_TRANSFORMS=native`

Example Full Docker Deploy with ENV Configuration

Using Jellyfin + Maloja example from Quickstart:

    services:
      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

## Examples​

### Parse only artists string using a custom delimiter​

Example

Your AIO Config:

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 File Config:

subsonic.json

    [
      {
        "name": "MySubsonic",
        "data": { /* ... */},
        "options": {
          "playTransform": {
            "preCompare": [
              {
                "type": "native",
                "name": "MyNativeTransformer"
              }
            ]
          }
        }
      }
    ]

### Don't parse specific artists​

Example

Your AIO Config:

config.json

    {
      // ...
      "transformers": [
        {
          "type": "native",
          "name": "MyNativeTransformer",
          "defaults": {
            "artistsIgnore": [
                "Crosby, Stills, Nash & Young",
                "Polo & Pan"
            ]
          }
        }
      ]
    }

In a Subsonic File Config:

subsonic.json

    [
      {
        "name": "MySubsonic",
        "data": { /* ... */},
        "options": {
          "playTransform": {
            "preCompare": [
              {
                "type": "native",
                "name": "MyNativeTransformer"
              }
            ]
          }
        }
      }
    ]

### 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 is required so we can use the default Stage.

In a Subsonic File Config:

subsonic.json

    [
      {
        "name": "MySubsonic",
        "data": { /* ... */},
        "options": {
          "playTransform": {
            "preCompare": [
              {
                "type": "native",
                "title": false // do not modify title
              }
            ]
          }
        }
      }
    ]