XRDB | eXtended Ratings DataBase

Docs for direct routes,
proxy setup, and integrations.

XRDB, eXtended Ratings DataBase, keeps route examples, supported IDs, deployment guidance, and integration details here so the configurator can stay focused on artwork output.

Open ConfiguratorOpen XRDB Repo

Route examples

These examples show the direct image route shape. Use the configurator whenever live export values or full query strings are needed.

Movie poster with OMDb + AlloCiné
https://xrdb.example.com/poster/tt0133093.jpg?tmdbKey={tmdbKey}&mdblistKey={mdblistKey}&posterArtworkSource=omdb&posterRatings=imdb,allocine,allocinepress
Typed TMDB backdrop with Bottom Row
https://xrdb.example.com/backdrop/tmdb:tv:1399.jpg?tmdbKey={tmdbKey}&mdblistKey={mdblistKey}&backdropRatings=tmdb,imdb&backdropBottomRatingsRow=true
Episode thumb with XRDBID
https://xrdb.example.com/thumbnail/xrdbid:tt0944947/S01E01.jpg?tmdbKey={tmdbKey}&mdblistKey={mdblistKey}&thumbnailRatings=tmdb,imdb

Supported IDs

IMDb uses `tt...` values.

TMDB works best with typed IDs such as `tmdb:movie:603` and `tmdb:tv:1399`.

Anime routes accept providers such as `anilist:`, `mal:`, `tvdb:`, `anidb:`, and `kitsu:`.

Episodes use `/thumbnail/{id}/S{season}E{episode}.jpg` and accept base IDs such as plain IMDb, `xrdbid:`, `tvdb:`, `kitsu:`, `anilist:`, `mal:`, and `anidb:`.

Thumbnail ratings use their own `thumbnailRatings` order and currently support `tmdb` and `imdb`.

Quick flow

1. Start in the configurator and tune the live result.

2. Copy the config string, AIOMetadata URLs, or proxy manifest from the configured output.

3. Use the docs for examples, supported format notes, and integration guidance.

XRDB feature explanations

This guide explains what each major setting does and how it changes image output, proxy behavior, and exported integration URLs.

ID formats and sources

XRDB accepts multiple ID families. Typed IDs are the safest choice when the source can provide them.

IMDb
`tt0133093`
Direct IMDb IDs are accepted as is. This is the broad compatibility path for many addons.
TMDB plain
`tmdb:603`
Plain TMDB IDs are accepted. XRDB can infer the media kind from context, but this is less explicit than typed TMDB.
TMDB typed
`tmdb:movie:603` or `tmdb:tv:1399`
Typed TMDB IDs are explicit and avoid movie vs show collisions. This is the recommended format for backdrops and logos and the default AIOMetadata poster mode.
Anime families
`mal:`, `anilist:`, `kitsu:`, `tvdb:`, `anidb:`
Anime ID prefixes are accepted directly. They are useful when your source metadata already uses anime native IDs.

Poster ID source

Auto (recommended)
`/poster/tmdb:{type}:{tmdb_id}.jpg?idSource=tmdb...`
Uses typed TMDB IDs for poster patterns. This gives broader and more consistent poster coverage.
IMDb
`/poster/{imdb_id}.jpg?...`
Uses IMDb IDs for poster patterns. Use this for integrations that require IMDb IDs, with possible coverage tradeoffs when IMDb IDs are missing.

Artwork sources

Artwork source controls let each image type prefer a different upstream source while keeping fallback behavior predictable.

`tmdb`
Poster, backdrop, thumbnail, logo
Uses normal TMDB artwork selection for the active type.
`fanart`
Poster, backdrop, thumbnail, logo
Prefers fanart.tv assets when a fanart key is available, then falls back to TMDB.
`cinemeta`
Poster, backdrop, thumbnail, logo
Prefers MetaHub Cinemeta assets when an IMDb ID is available, then falls back to TMDB.
`random`
Poster, backdrop, thumbnail, logo
Picks a deterministic random source from the type supported pool, then falls back if needed.
`omdb`
Poster only
Poster only path that uses OMDb poster data when server OMDb access and IMDb IDs are available, then falls back to TMDB.

Presentation modes

Presentation controls define the rating overlay style. Each type can use its own presentation mode.

`standard`
Provider badges in the selected style and layout.
Balanced default when you want provider specific badges visible.
`minimal`
One compact aggregate chip.
Clean look with minimal badge density.
`average`
One labeled aggregate badge (Overall, Critics, or Audience).
Simple single score display with label clarity.
`dual`
Two aggregate badges, one for critics and one for audience.
When both perspectives should stay visible at the same time.
`dual-minimal`
Two compact aggregate chips for critics and audience.
Dual view with lower visual weight.
`editorial`
Poster uses an integrated top left editorial score mark.
Poster focused editorial look. Non poster outputs fall back to a clean average badge.
`blockbuster`
Dense promo style rendering with heavy badge presence.
High impact poster variants and showcase style outputs.
`none`
No rating badges.
Artwork only output where ratings should be hidden.
Episode thumbnails use the same 16:9 layout model as backdrops and expose thumbnail scoped layout controls (`thumbnailRatingsLayout`, `thumbnailBottomRatingsRow`, `thumbnailSideRatingsPosition`, `thumbnailSideRatingsOffset`) so they can mirror or diverge from backdrop behavior.

Rating provider ordering

Provider order is configured per image type with `posterRatings`, `backdropRatings`, `thumbnailRatings`, and `logoRatings`. The order you set controls the provider sequence for that type.

Episode thumbnail ratings are type limited today and default to `tmdb,imdb`.

Keep values per type if you want different provider emphasis across poster, backdrop, thumbnail, and logo outputs.

Metadata translation

Proxy metadata translation is controlled by `translateMeta` and `translateMetaMode`.

`translateMeta=true`
Enables proxy side metadata translation for catalog and meta responses while image rendering settings remain unchanged.
`translateMetaMode=fill-missing` (safe default)
Keeps good source text, then fills blank or placeholder fields. This is the conservative default for most proxy installs.
AIOMetadata URL exports are image URL patterns. They do not change merge behavior by themselves. Translation settings matter when those addons are consumed through XRDB proxy routes.

Proxy functionality

XRDB supports both encoded and query based proxy configuration styles.

`/proxy/{config}/manifest.json`
Encoded install URL form used by the configurator proxy export.
`/proxy/manifest.json?url={manifestUrl}&tmdbKey=...&mdblistKey=...`
Query based manifest form for tools that build URLs dynamically instead of using the encoded config path.
`/proxy/catalog/...`, `/proxy/meta/...`, and other addon resource paths
Passthrough routes that forward addon resources while applying the same XRDB config for image rewrites and optional metadata translation.
Proxy rewrites `meta.poster`, `meta.background`, and `meta.logo` to XRDB image routes using the active config and passes non image resources through unchanged.

BYOK stateless setup

XRDB is stateless by design. User provided keys flow through generated URLs and encoded config payloads instead of server side session storage.

This lets one XRDB deployment serve many users while each user keeps their own API usage and limits through URL scoped credentials.

AIOMetadata exports

The configurator generates four ready to paste patterns for AIOMetadata fields: poster, background, logo, and episode thumbnail.

Poster pattern behavior follows the Poster ID source control. Episode thumbnail pattern behavior follows Episode ID source and thumbnail specific settings including artwork source, ratings, layout, and text mode. The Hide credentials toggle can mask key values with placeholders without changing live runtime URLs.

Per type rendering controls

Most rendering controls are type scoped so one setup can drive different poster, backdrop, thumbnail, and logo outputs from the same base config.

Poster
`posterRatings`, `posterArtworkSource`, `posterRatingPresentation`, `posterRatingsLayout`, `posterRatingsMaxPerSide`, `posterQualityBadgesStyle`
Backdrop
`backdropRatings`, `backdropArtworkSource`, `backdropRatingPresentation`, `backdropRatingsLayout`, `backdropBottomRatingsRow`, `backdropQualityBadgesStyle`
Episode thumbnail
`thumbnailRatings`, `thumbnailArtworkSource`, `thumbnailEpisodeArtwork`, `thumbnailRatingPresentation`, `thumbnailRatingsLayout`, `thumbnailBottomRatingsRow`
Logo
`logoRatings`, `logoArtworkSource`, `logoRatingPresentation`, `logoRatingsMax`, `logoBottomRatingsRow`, `logoBackground`

For the full parameter catalog and deployment references, use the README in the repository root.

What is IbbyLabs Uptime Tracker?

It is the IbbyLabs public status board for popular Stremio addons, including current health and incident updates.

View the tracker