AniDB

For anime, the metadata your *arr stack carries (TVDB or TMDB IDs) often doesn’t match what subtitle providers expect (AniDB IDs, episode numbering by absolute number). Sublarr resolves the mapping in four tiers, falling through if a tier doesn’t have an answer. AniDB is the most reliable tier — when it’s enabled and the local cache is up to date, anime providers return the right episode every time.

Why AniDB matters for anime

Anime publishers often split a season differently from how TVDB or TMDB carries it. Examples:

What TVDB shows	What AniDB shows
”Frieren — Season 1 (28 episodes)"	"Frieren — Episodes 1–28 absolute, anime IDs distinct from TVDB IDs"
"JoJo’s Bizarre Adventure — Season 5 (Stone Ocean)"	"JoJo’s Bizarre Adventure: Stone Ocean — anime IDs separate from preceding parts”
Specials and OVAs lumped under “Season 0”	Distinct AniDB IDs per OVA, sometimes with their own subtitle releases

Subtitle providers like Jimaku, Kitsunekko, and AnimeTosho key on AniDB IDs. Without an AniDB-aware lookup, Sublarr would search by show name and pick whatever the provider returns — often wrong for split seasons.

The four-tier resolution

Sublarr tries each tier in order and uses the first match:

Tier	Source	Speed	Quality
1. Custom field	Sonarr/Radarr custom field on the series (“AniDB ID = 12345”)	Instant	Authoritative
2. Online lookup	Live API call to AniDB	~ 200 ms / call	Authoritative
3. Anime-list mapping	The community-maintained anime-list.xml mapping AniDB ↔ TVDB ↔ MAL	Instant (local file)	Good for mainstream
4. Offline dump	Local AniDB XML dump shipped with Sublarr	Instant	Authoritative for everything in the dump

Tiers 3 and 4 are read from disk, so they cost nothing. Tier 1 is opt-in (you set the custom field manually). Tier 2 requires network and respects AniDB’s rate limit.

Configuring AniDB

Open Settings → Connections → Metadata → AniDB:

Field	Effect
Enabled	Master toggle. When off, only tiers 1, 3, 4 are used.
Cache TTL (days)	How long online lookups stay cached before re-querying. Default 30.
Custom field name	The Sonarr/Radarr custom field where you keep the manual override. Default anidb_id.
Fallback to mapping	If the live lookup fails, try the anime-list.xml mapping. Default on.

Using a custom field

If automatic resolution gets a particular series wrong, set the AniDB ID manually in Sonarr or Radarr:

1. Open the series in Sonarr/Radarr.
2. Edit → Custom Fields → add anidb_id (or whatever you set in Sublarr).
3. Enter the AniDB ID (find it on anidb.net/anime/<id>).
4. Trigger a re-scan in Sublarr.

Tier 1 will pick this up on the next lookup and skip the slower tiers.

Refreshing the offline dump

The XML dump is part of the Docker image but goes stale over time. Refresh it:

1. Settings → Connections → Metadata → AniDB → Refresh dump.
2. Sublarr downloads the latest anime-titles.xml.gz from AniDB’s open dataset.
3. The new file replaces the bundled one and is read on the next lookup.

Tip

Schedule the dump refresh as part of your regular maintenance — adding it as a custom job in Settings → System → Scheduler is straightforward. Once a quarter is plenty for most installs.

Per-series cache key

Sublarr caches provider responses keyed on (provider, anidb_id, episode). Without AniDB the key falls back to (provider, series_name, season, episode), which is fine for live action but causes cache collisions on split-season anime. Enabling AniDB therefore both improves accuracy AND makes the cache smarter.

Troubleshooting

Symptom	Likely cause	Fix
Wrong-anime subtitles for one series	Auto resolution picked the parent show instead of the spin-off	Set the manual anidb_id custom field on that series.
Anime never resolves	AniDB live lookup blocked / rate-limited	Increase Cache TTL, or switch to Fallback to mapping only.
Live lookup is slow	First lookup of a series — subsequent are cached	Pre-warm the cache by running a library scan with AniDB enabled.
Specials never get subtitles	Special is in a different AniDB anime ID	Add it explicitly via the custom field.

What it does NOT do

AniDB resolution affects subtitle provider lookups, not metadata enrichment. Your library still uses Sonarr/Radarr’s titles, posters, and episode numbering. Sublarr only consults AniDB to ask “what’s the right ID to send to this subtitle provider?”