vrr/multi-scrobbler
2
0
Fork 0
mirror of https://github.com/FoxxMD/multi-scrobbler.git synced 2026-04-30 21:00:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs: Improve MB docs

Browse source
This commit is contained in:
FoxxMD 2026-01-07 16:13:08 +00:00
parent c33ed61220
commit a3aa0b9988
2 changed files with 175 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

189
docsite/docs/configuration/transforms/musicbrainz.mdx
View file

@ -129,7 +129,6 @@ Example:
],
"defaults": {
"releaseStatusPriority": ["official"],
"fallbackArtistSearch": "native",
"releaseAllowEmpty": true
}
},
@ -138,25 +137,97 @@ Example:
}
```
### Rules
### Rules and Hooks
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):
[Add your Stage](https://foxxmd.github.io/multi-scrobbler/configuration/transforms/#stage) to a Source or Client by specifying it in a [Hook](/configuration/transforms/#hook):
```json5
{
"type": "musicbrainz",
"name": "MyMB"
// ...
"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
"meta": true // adds MusicBrainz MBIDs to scrobble data
}
```json5 title="subsonic.json"
[
{
"name": "MySubsonic",
"data": { /* ... */},
"options": {
"playTransform": {
"preCompare": [
{
"type": "musicbrainz",
"name": "MyMB"
}
]
}
}
}
]
```
Each [**Stage 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):
<details>
<summary>Example</summary>
```json5 title="subsonic.json"
[
{
"name": "MySubsonic",
"data": { /* ... */},
"options": {
"playTransform": {
"preCompare": [
{
"type": "musicbrainz",
"name": "MyMB"
// ...
"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
"meta": true // adds MusicBrainz MBIDs to scrobble data
}
]
}
}
}
]
```
</details>
:::tip[Per Component Override]
The `defaults` you set in [Stage Configuration](#stage-configuration) [can be overriden/added to](/configuration/transforms/#overriding-configuration) (per property) in each Hook.
<details>
<summary>Example</summary>
```json5 title="subsonic.json"
[
{
"name": "MySubsonic",
"data": { /* ... */},
"options": {
"playTransform": {
"preCompare": [
{
"type": "musicbrainz",
"name": "MyMB",
"releaseStatusPriority": ["psuedo-release"], // override from defaults
"searchOrder": ["freetext"] // add new property, combined with defaults
}
]
}
}
}
]
```
</details>
:::
## ENV Configuration
The general configuration shown above can also be configured from a selection of *presets* using [ENV Config](/configuration?configType=env#configuration-types) for individual Sources/Clients.
@ -1093,4 +1164,90 @@ In a [Jellyfin](/configuration/clients/jellyfin) [File Config](/configuration?co
}
]
```
</details>
### Different Search Methods Based on Source (Last.fm and Spotify) {#override-stage-configuration-example}
[Last.fm has unreliable MBIDs](#search-considerations) and Spotify provides an [ISRC](https://musicbrainz.org/doc/ISRC) and consistent formatting.
* For Spotify, we want to rely on ID [searches](#search-methods) and matches that are [close to original scrobble text](#field-scoring)
* For Last.fm, we want to use only text searches and take whatever correction is given to us
Use [**Per Component Overrides**](#rules-and-hooks) with the default (or [sensible](#sensible-default)) [Stage Configuration](#stage-configuration) to specify different search behavior for each Source.
<details>
<summary>Example</summary>
Stage Configuration
```json5 title="config.json"
{
// ...
"transformers": [
{
"type": "musicbrainz",
"name": "MyMB",
"data": {
"apis": [
{
"contact": "contact@mydomain.com"
}
],
"defaults": {} // maybe use sensible?
},
}
]
}
```
```json5 title="lastfm.json"
[
{
"name": "MyLFM",
"configureAs": "source"
"data": { /* ... */},
"options": {
"playTransform": {
"preCompare": [
{
"type": "musicbrainz",
"name": "MyMB",
"searchArtistMethod": "native"
// does not use any ID searches
// fallback to more aggressive/broad searches
"searchOrder": ["basic", "artist", "freetext"]
}
]
}
}
}
]
```
```json5 title="spotify.json"
[
{
"name": "MySpotify",
"data": { /* ... */},
"options": {
"playTransform": {
"preCompare": [
{
"type": "musicbrainz",
"name": "MyMB",
// use ISRC as first search
"searchOrder": ["isrc", "basic"]
// bias matches towards similarity to original data
"albumWeight": 0.33,
"titleWeight": 0.33,
"artistWeight": 0.33
}
]
}
}
}
]
```
</details>

4
docsite/docs/configuration/transforms/transforms.mdx
View file

@ -193,7 +193,7 @@ In a [Subsonic](/configuration/sources/subsonic) [File Config](/configuration?co
"preCompare": [
{
"type": "native"
// when "name" is not defined, uses first found "native" transformer
"name": "MyNativeTransformer" // when "name" is not defined, uses first found "native" transformer
}
]
}
@ -363,7 +363,7 @@ The actual value of each property may be different for each Stage. Check the doc
Generically, though, each property may be some value **or** an object combining a [`when` condition](#conditional-modification) and that value.
If none of the properties are specified in the stage then it's assumed all transformed data should be used.
**If none of the properties are specified in the stage then it's assumed all transformed data should be used.**
:::note