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
          }
        ]
      }
    }
  }
]