Providers¶
A provider is an external metadata source Stillwater queries for an artist's biography, genres, images, and external IDs. This page is the reference. For the behavior (priority, aggregation, refresh semantics), see providers in core concepts.
Capability matrix¶
The table below is generated from the provider definitions in the codebase. Don't edit it directly -- regenerate with make generate-docs after changes to the registry or any provider package.
| Provider | Tier | Sign-up | Rate limit | Mirror | Metadata fields | Image types |
|---|---|---|---|---|---|---|
| MusicBrainz | Free | Not required | 1/sec | Yes | Name, Sort name, Type, Gender, Disambiguation, Origin, Born, Formed, Died, Disbanded, Years active, Genres, Styles, Moods, Members, Aliases | None |
| Wikipedia | Free | Not required | 5/sec | No | Name, Type, Biography, Born, Died, Years active, Origin, Genres, Members | None |
| Fanart.tv | Free key | Sign up | 3/sec | No | Image only | thumb, fanart, logo, hdlogo, banner |
| TheAudioDB | Freemium | Sign up | 30/min | No | Name, Gender, Origin, Biography, Genres, Styles, Moods, Born, Formed, Died, Disbanded, Aliases | thumb, logo, widethumb, banner, fanart |
| Discogs | Free key | Sign up | 1/sec, 1000/day | No | Name, Biography, Aliases, Members | thumb |
| Last.fm | Free key | Sign up | 5/sec | No | Name, Biography, Genres, Styles, Moods, Similar artists | None |
| Wikidata | Free | Not required | 5/sec | No | Name, Formed, Disbanded, Origin, Genres | thumb, logo |
| Deezer | Free | Not required | 5/sec | No | Name | thumb |
| Genius | Free key | Sign up | 5/sec | No | Name, Biography, Aliases | None |
| Spotify | Paid | Sign up | 5/sec | No | Name | thumb |
How the fallback chain works¶
For every field Stillwater can populate (name, biography, genres, thumb, fanart, ...) you set a per-field provider priority list. When that field needs to be populated:
- Stillwater walks the priority list from top to bottom.
- Providers that aren't available (no API key, disabled in settings, missing the right ID) are skipped.
- Providers that structurally cannot supply the field (e.g., neither MusicBrainz nor Wikidata returns biography text) are skipped.
- The first provider that returns a usable value populates the field -- with one important caveat below.
The lists are configured under Settings > Providers > Priorities. You can override the global list per library, so a library of jazz recordings can prefer different sources than one containing pop or rock artists.
Per-field aggregation¶
Two kinds of fields behave differently in step 4 above:
- First-match wins -- text fields like biography, name, sort name, born date, etc. The first non-empty answer wins; later providers in the list are not asked.
- Aggregated -- tag fields (genres, styles, moods) and image fields (thumb, fanart, logo, banner). Every provider in the list is asked, and Stillwater merges the results -- preserving priority order so the most-trusted source's contribution sits first.
The split lets you pick "definitive" sources for some fields (MusicBrainz for sort name) while pooling diversity for others (genres from MusicBrainz + Last.fm + Discogs combined).
Image fetch protection¶
Image fields have one extra rule: a provider is only marked as "asked" when its image fetch actually attempted -- meaning either succeeded or returned a definitive "no images for this artist." Two scenarios skip the marker:
- No usable ID. If a provider needs its own ID (Spotify needs a Spotify ID; Discogs needs a Discogs ID) and Stillwater doesn't have one yet, the call is skipped without marking the field as queried.
- Transient failure. If the provider returned a timeout or 5xx, the call is treated as not-yet-tried.
In both cases, your existing artwork is preserved -- the orchestrator never blanks an image field on the strength of a transient outage. The next refresh will retry naturally.
Provider ID propagation¶
Most providers want their own ID, not a MusicBrainz ID. Stillwater stores every ID it learns and feeds them down the chain. As IDs are discovered (a MusicBrainz response often includes a discogs.com/artist/12345 link, for example), Stillwater extracts them and the next provider gets a real ID instead of an MBID it can't use. The discoveries also persist on the artist record, so the next refresh starts from a stronger position. You don't have to back-fill IDs by hand.
Auth tiers¶
Providers fall into four tiers:
| Tier | Meaning | Sign-up required |
|---|---|---|
| Free | No key needed at all | No |
| Free key | Free of charge but you sign up for an API key | Yes |
| Freemium | Free tier with rate limits; paid tiers for more headroom | Yes |
| Paid | Account is paid for | Yes |
Any keys you provide are encrypted at rest and scrubbed from logs. Set keys under Settings > Providers.
Web image search¶
DuckDuckGo is a web image search adapter, not a metadata provider. It surfaces in the comparison view as an "I'll go look on the web" option for cases where curated providers don't have what you need. It runs only on demand, never as part of an automatic refresh.
Rate-limit awareness¶
Each provider has its own rate limit. The capability matrix above lists them. Stillwater's orchestrator caches each provider's full response within a single refresh -- so even if a provider appears in the priority list for many fields, it's only called once. This matters most for the tighter limits (AudioDB's free tier is 30 requests per minute; Discogs caps at 1000/day on a free key).
If you're driving heavy bulk evaluation, two knobs help: increase library scope to spread fetches over time, and stagger Fix-all runs rather than running multiple at once.
The per-provider limit above is the proactive defense: it spaces requests so they stay under quota. Reactive backoff handles the case where a rate-limit response comes back anyway.
On a 429 Too Many Requests, Stillwater honors the server's Retry-After hint. It parses both the seconds form and the HTTP-date form. When no hint is present, it falls back to a jittered exponential backoff. Retries are bounded to a few attempts, after which the call surfaces a transient error rather than blocking indefinitely.
A 503 Service Unavailable is treated more conservatively, with a smaller bounded number of attempts and jittered backoff. This is how MusicBrainz usually signals throttling, typically with no Retry-After. The conservative retry lets a throttled call recover instead of being dropped, without hammering a server that may genuinely be unhealthy.
What to configure where¶
| You want to | Go to |
|---|---|
| Enable / disable a provider | Settings > Providers |
| Set or update an API key | Settings > Providers |
| Change priority for a field | Settings > Providers > Priorities |
| Override priority for one library | Settings > Libraries > (library) > Provider overrides |
| Enable a web image search adapter | Settings > Providers > Web search providers |
| Adjust how much Wikipedia biography text is fetched | Settings > Providers > (gear icon on the Wikipedia card) |
Field verbosity¶
Some providers can return a field at more than one level of detail. Open the gear icon on a provider card in Settings > Providers to set it.
| Provider | Field | Levels | Default |
|---|---|---|---|
| Wikipedia | Biography | Intro only, Full article | Intro only |
Intro only fetches just the introductory section of the Wikipedia article, a concise summary. Full article fetches the complete article text. The default is Intro only; a change takes effect the next time the artist is refreshed.