---
title: Native Stage
toc_min_heading_level: 2
toc_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"]
}
```

## 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-moditication):

```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#modification-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](http://localhost:3000/docs/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:

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

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