mirror of
https://github.com/FoxxMD/multi-scrobbler.git
synced 2026-05-01 05:09:54 +00:00
docs(musicbrainz): Update search methods
This commit is contained in:
FoxxMD
parent
9833c6c7bb
commit
203411a875
2 changed files with 196 additions and 61 deletions
|
|
@ -236,6 +236,8 @@ Both steps have separate configuration.
|
|||
|
||||
### Searching
|
||||
|
||||
#### Should MS Search?
|
||||
|
||||
Before MS begins a search it checks Scrobble data it checks if your data already contains:
|
||||
|
||||
* [MBIDs](https://musicbrainz.org/doc/MusicBrainz_Identifier) for [artists](https://musicbrainz.org/doc/Artist), [album](https://musicbrainz.org/doc/Release), and specific [track/recording](https://musicbrainz.org/doc/Recording)
|
||||
|
|
@ -258,7 +260,7 @@ Define which data types are required using:
|
|||
// ...
|
||||
"defaults": {
|
||||
// only search if MBIDs for artists or album is missing
|
||||
"searchWithMissing": ['artists', 'album']
|
||||
"searchWithMissing": ["artists", "album"]
|
||||
|
||||
// uncomment to make the stage always search, even if above data is present
|
||||
//forceSearch: true
|
||||
|
|
@ -267,65 +269,50 @@ Define which data types are required using:
|
|||
|
||||
</details>
|
||||
|
||||
If required data is missing then the next step is making [search queries to the Musicbrainz database](https://musicbrainz.org/doc/MusicBrainz_API/Search) to try to get potential candidates. Multi-scrobbler uses the **title, artist(s), and album** from your Scrobble data to query for matches.
|
||||
If required data is missing then the next step is making [search queries to the Musicbrainz database](https://musicbrainz.org/doc/MusicBrainz_API/Search) to try to get potential candidates.
|
||||
|
||||
:::note
|
||||
#### Search Methods
|
||||
|
||||
If your Scrobble data contains an [ISRC](https://musicbrainz.org/doc/ISRC) (usually from Spotify) then Multi-scrobbler will search using this ID first, before the above criteria. If no match is found with the ISRC then it automatically retries with the title, artist(s), and album.
|
||||
Multi-scrobbler can search for Musicbrainz matches using **multiple** methods. You control:
|
||||
|
||||
* the search methods that are used
|
||||
* **the order** in which search methods are executed
|
||||
|
||||
All search methods will be run in the order they were defined until one method returns at least one match.
|
||||
|
||||
**The methods you choose, and the order they run in, can drastically change how many API calls are needed to get a match, and what types of matches are returned.** See [**Search Considerations**](#search-considerations) for guidance on how to decide on methods based on Source.
|
||||
|
||||
To set search methods and their order use the `searchOrder` option in your [Stage Configuration](/configuration/transforms#configuring-stages):
|
||||
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// only searches using these methods, in the order they are listed here
|
||||
"searchOrder": ["isrc", "mbidrecording", "basic","freetext"]
|
||||
}
|
||||
```
|
||||
|
||||
:::tip[Default Search Methods]
|
||||
|
||||
If you do not define `searchOrder`, or use the [Sensible Default/Preset](#sensible-default), then Multi-scrobbler will default to using `isrc` and `basic` methods, in that order.
|
||||
|
||||
:::
|
||||
|
||||
Musicbrainz agressively normalizes these fields in its database which means that if your Scrobble data contains major innaccuracies or phrases fields in a non-normal way, it's possible Musicbrainz won't find any matches. This is a more common occurrence when trying to match Scrobble data from Sources that don't support multiple artist data, like [Subsonic](/configuration/sources/subsonic) and [Last.fm](/configuration/sources/lastfm).
|
||||
<h4>Available Methods</h4>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Examples of Bad Data</summary>
|
||||
|
||||
Last.fm Scrobble returns an Artist in the title and combines two artists into one string:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Endless Possibility (feat. Wheatus)",
|
||||
"artists": ["Bowling For Soup & Punk Rock Factory"]
|
||||
}
|
||||
```
|
||||
|
||||
The corresponding [Musicbrainz Recording](https://musicbrainz.org/release/85bf284b-8b39-414e-8ad9-61f593072588) has all artists separated and no artist in the title:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Endless Possibility",
|
||||
"artists": ["Bowling For Soup", "Punk Rock Factory", "Wheatus"]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
:::note
|
||||
|
||||
If the initial search(es), and any [retried searches](#retrying-search), do not return any results then the stage is marked as [**failed** (`onFailure`) for **Flow Control**](/configuration/transforms/#flow-control).
|
||||
|
||||
:::
|
||||
|
||||
#### Retrying Search
|
||||
|
||||
If normal searches using all the fields mentioned above does not return any matches Multi-scrobbler can try additional searches with modified queries.
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Album Only</summary>
|
||||
|
||||
If your Scrobble data contains a title, artist(s), and an album (all three fields) then Multi-scrobbler can retry the search using only title and album, if `fallbackAlbumSearch` is set in [Stage Configuration](/configuration/transforms#configuring-stages):
|
||||
<summary>ISRC</summary>
|
||||
|
||||
If your Scrobble data contains an [ISRC](https://musicbrainz.org/doc/ISRC) (usually from Spotify) then Multi-scrobbler can search using this ID, only.
|
||||
|
||||
[Stage Configuration](/configuration/transforms#configuring-stages) example:
|
||||
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// will try an additional search using only title + album name
|
||||
"fallbackAlbumSearch": "true"
|
||||
// will only search using isrc
|
||||
"searchOrder": ["isrc"]
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -333,19 +320,111 @@ If your Scrobble data contains a title, artist(s), and an album (all three field
|
|||
|
||||
<details>
|
||||
|
||||
<summary>Artist Extraction</summary>
|
||||
<summary>Track MBID</summary>
|
||||
|
||||
If...
|
||||
If your Scrobble data contains an [Track (Recording) MBID](https://musicbrainz.org/doc/Recording) then Multi-scrobbler can search using this MBID, only.
|
||||
|
||||
* [Album Only](#album-only) returns no results or did not run
|
||||
* Your scrobble data contains only **one** artist string
|
||||
* `fallbackArtistSearch` is set in [Stage Configuration](/configuration/transforms#configuring-stages)
|
||||
[Stage Configuration](/configuration/transforms#configuring-stages) example:
|
||||
|
||||
Then Multi-scrobbler will attempt to extract multiple artists from your artist and track string. **This is not automatic. You must set `fallbackArtistSearch` to enable this additional search.**
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// will only search using recording mbid
|
||||
"searchOrder": ["mbidrecording"]
|
||||
}
|
||||
```
|
||||
|
||||
`fallbackArtistSearch` can be set to **Native** or **Naive** mode:
|
||||
</details>
|
||||
|
||||
<Tabs groupId="fallbackArtist" queryString>
|
||||
<details>
|
||||
|
||||
<summary>Album, Artist, and Title Fields</summary>
|
||||
|
||||
Will search Musicbrainz using any/all available text fields from your scrobble: Album, Artists(s), and Title. Does not leverage any existing MBIDs.
|
||||
|
||||
[Stage Configuration](/configuration/transforms#configuring-stages) example:
|
||||
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// will only search using album, artist(s), and title
|
||||
"searchOrder": ["basic"]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Album/Artist/Title OR MBIDs</summary>
|
||||
|
||||
This is the same as the above **Album, Artist, and Title Fields** search except that if the scrobble data contains any corresponding MBIDs it will use those instead of the plain text field.
|
||||
|
||||
[Stage Configuration](/configuration/transforms#configuring-stages) example:
|
||||
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// will only search using album, artist(s), and title
|
||||
"searchOrder": ["basicOrIds"]
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Endless Possibility (feat. Wheatus)",
|
||||
"artists": ["Bowling For Soup"]
|
||||
"albumMbid": "c9f91cdc-984e-4303-9a51-4ac0dfa2348f",
|
||||
"album": "My Cool Album"
|
||||
}
|
||||
```
|
||||
|
||||
Multi-scrobbler will search Musicbrainz using `title`, `artists`, and `albumMbid` but NOT `album`.
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Album And Title Only</summary>
|
||||
|
||||
If your Scrobble data contains a title, artist(s), and an album (all three fields) then Multi-scrobbler can search using only title and album by using `album` for `searchOrder`:
|
||||
|
||||
[Stage Configuration](/configuration/transforms#configuring-stages) example:
|
||||
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// will only search using only title + album name
|
||||
"searchOrder": ["album"]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Extracted Artists</summary>
|
||||
|
||||
If your scrobble data contains only **one** artist string then Multi-scrobbler can attempt to extract multiple artists from your artist and track string.
|
||||
|
||||
Use `artist` with `searchOrder` and optionally specify the extraction mode with `searchArtistMethod`:
|
||||
|
||||
[Stage Configuration](/configuration/transforms#configuring-stages) example:
|
||||
|
||||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// will only search using title/album + extracted artists
|
||||
"searchOrder": ["artist"],
|
||||
//searchArtistMethod: 'native' // optional
|
||||
}
|
||||
```
|
||||
|
||||
`searchArtistMethod` can be set to **Native** or **Naive** mode:
|
||||
|
||||
<Tabs groupId="searchArtistMethod" queryString>
|
||||
<TabItem value="native" label="Native (Recommended)">
|
||||
|
||||
**Native** (`native`) mode uses an aggressive configuration of the [Native Stage](/configuration/transforms/native) to extract artists using common delimiters and common "joined" artist patterns from the artist and title string of your Scrobble data.
|
||||
|
|
@ -388,8 +467,9 @@ Then Multi-scrobbler will attempt to extract multiple artists from your artist a
|
|||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// ...
|
||||
"fallbackArtistSearch": "native"
|
||||
// will only search using title/album + native extracted artists
|
||||
"searchOrder": ["artist"],
|
||||
"searchArtistMethod": "native"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -426,8 +506,9 @@ Then Multi-scrobbler will attempt to extract multiple artists from your artist a
|
|||
```json5
|
||||
// ...
|
||||
"defaults": {
|
||||
// ...
|
||||
"fallbackArtistSearch": "naive"
|
||||
// will only search using title/album + naive extracted artists
|
||||
"searchOrder": ["artist"],
|
||||
"searchArtistMethod": "naive"
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -461,12 +542,19 @@ If you know your Source's Play data is well organized you **should not** enable
|
|||
// ...
|
||||
"defaults": {
|
||||
// ...
|
||||
"fallbackFreeTextSearch": true
|
||||
// will only search using free text search of all artist/album/title
|
||||
"searchOrder": ["freetext"],
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
:::note
|
||||
|
||||
If all defined search methods do not return any results then the stage is marked as [**failed** (`onFailure`) for **Flow Control**](/configuration/transforms/#flow-control).
|
||||
|
||||
:::
|
||||
|
||||
### Refining
|
||||
|
||||
### Score
|
||||
|
|
@ -585,6 +673,50 @@ Consider adding [Artist Extraction](./?fallbackArtist=native#artist-extraction)
|
|||
}
|
||||
```
|
||||
|
||||
### Search Considerations
|
||||
|
||||
How complete, and accurate, your scrobble data is from a certain Source should dictate what [Search Methods](#search-methods) you should use for matching.
|
||||
|
||||
Musicbrainz agressively normalizes **artist, album, and title** fields in its database which means that if your Scrobble data contains major innaccuracies or phrases fields in a non-normal way, it's possible Musicbrainz won't find any matches. This is a more common occurrence when trying to match Scrobble data from Sources that don't support multiple artist data, like [Subsonic](/configuration/sources/subsonic) and [Last.fm](/configuration/sources/lastfm).
|
||||
|
||||
<details>
|
||||
|
||||
<summary>Examples of Bad Data</summary>
|
||||
|
||||
Last.fm Scrobble returns an Artist in the title and combines two artists into one string:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Endless Possibility (feat. Wheatus)",
|
||||
"artists": ["Bowling For Soup & Punk Rock Factory"]
|
||||
}
|
||||
```
|
||||
|
||||
The corresponding [Musicbrainz Recording](https://musicbrainz.org/release/85bf284b-8b39-414e-8ad9-61f593072588) has all artists separated and no artist in the title:
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Endless Possibility",
|
||||
"artists": ["Bowling For Soup", "Punk Rock Factory", "Wheatus"]
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
**In general, you should prioritize methods that search by unique identifiers** (`isrc` `mbidRecording` `basicOrIds`) if you know your Sources may contain *accurate* data for these. Such as: Spotify, Jellyfin, Plex, and Listenbrainz (Source).
|
||||
|
||||
Use field-based methods if your Sources do not return IDs consistently (or at all). Add more field-based methods the more inaccurate your scrobble data may be, but be aware that more aggressive/broad searches may return less accurate results.
|
||||
|
||||
:::tip[Lastfm]
|
||||
|
||||
Last.fm is inconsistent when it comes to matching your scrobbles. It will accept (almost) any fields for track/title/album and aggressively attempt to match/correct these, regardless of your intentions.
|
||||
|
||||
Unless the client scrobbling to Last.fm is also sending an `mbid`, it's likely your scrobble will not be **consistently** matched correctly and so the `mbid` supplied by last.fm in its scrobble data will be wrong.
|
||||
|
||||
Therefore, you should *avoid* using `mbidRecording` and `basicOrIds` as the primary search methods (or understand the risks of using them). Instead, prefer to use field-based methods *before* falling back to id-based methods.
|
||||
|
||||
:::
|
||||
|
||||
### Filter Considerations
|
||||
|
||||
When using your own filters consider:
|
||||
|
|
@ -751,7 +883,8 @@ Your [AIO Config](/configuration?configType=aio#configuration-types):
|
|||
"releaseStatusPriority": ["official"],
|
||||
"releaseGroupPrimaryTypePriority": ["album", "single", "ep"],
|
||||
"releaseCountryPriority": ["XW"],
|
||||
"fallbackArtistSearch": "native"
|
||||
"searchArtistMethod": "native"
|
||||
"searchOrder": ["isrc", "basic", "artist"]
|
||||
}
|
||||
}
|
||||
]
|
||||
|
|
@ -871,7 +1004,8 @@ Your [AIO Config](/configuration?configType=aio#configuration-types):
|
|||
"releaseStatusPriority": ["official"],
|
||||
"releaseGroupPrimaryTypePriority": ["album", "single", "ep"],
|
||||
"releaseCountryPriority": ["XW"],
|
||||
"fallbackArtistSearch": "native",
|
||||
"searchArtistMethod": "native",
|
||||
"searchOrder": ["isrc","basic", "artist"]
|
||||
}
|
||||
}
|
||||
]
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue