Easy Ratings Database (ERDB) - Stateless Edition

ERDB generates poster/backdrop/logo images with dynamic ratings on-the-fly.

Quick Start

Install From GitHub

git clone https://github.com/realbestia1/erdb
cd erdb

1. Install dependencies: sudo npm install
2. Build: npm run build
3. Start the app: npm run start
4. App available at http://localhost:3000

Scalability & Docker

The compose file includes a reverse proxy (Caddy) to handle app scaling.

Recommended Requirements

For high performance (on-the-fly image rendering), a server with a strong CPU and plenty of RAM is recommended.

Minimum recommended:

• CPU: 4 vCPU
• RAM: 4 GB

Basic start:

docker compose up -d --build

Scale to multiple instances (e.g. 4):

docker compose up -d --build --scale app=4

The public port is ERDB_HTTP_PORT (default 3000) exposed by Caddy. Set it in the .env file. Data (SQLite database and image cache) is persisted in ./data.

Custom port (with scale):

ERDB_HTTP_PORT=4000 docker compose up -d --build --scale app=4

HuggingFace Guide (NOT RECOMMENDED)

(to avoid bans on HuggingFace)

1. Go to the ERDB GitHub repo: https://github.com/realbestia1/erdb
2. Click the "Fork" button in the top-right corner
3. Choose any name for the fork (do not use "erdb")

HuggingFace Steps

1. Create a new Space
2. Choose any name
3. Select Docker
4. Select Blank
5. Set it as a Public space
6. Click Create Space

Now click "Create the Dockerfile" (near the bottom of the page).

Copy and paste the content of Dockerfile.hf into the editor that opens, replacing "realbestia1" with your GitHub username.

Line to change:

RUN git clone https://github.com/realbestia1/erdb.git .

After the edit, click "Commit new file to main".

ERDB URL

To get your personal link:

1. Click the three dots in the top-right corner
2. Go to "Embed this Space"
3. Copy the Direct URL

Done! Your ERDB is ready to use on HuggingFace.

Note: to update ERDB quickly, go to the Space settings and click "Factory Rebuild" only after syncing your fork on GitHub.

API Usage

Main endpoint: GET /{type}/{id}.jpg?ratings={providers}&lang={lang}&ratingStyle={style}...

Examples

• Poster with IMDb and TMDB: /poster/tt0133093.jpg?ratings=imdb,tmdb&lang=it
• Minimal backdrop: /backdrop/tmdb:603.jpg?ratings=mdblist&style=plain

Supported Query Parameters

Parameter	Description	Supported Values	Default
type	Image type (Path)	poster, backdrop, logo	-
id	Media ID (Path)	IMDb (tt...), TMDB (tmdb:...), Kitsu (kitsu:...)	-
lang	Image language	Any TMDB ISO 639-1 code (e.g. it, en, es, fr, de, ru, ja)	en
streamBadges	Quality badges via Torrentio (global fallback)	auto, on, off	auto
posterStreamBadges	Poster quality badges	auto, on, off	auto
backdropStreamBadges	Backdrop quality badges	auto, on, off	auto
qualityBadgesSide	Quality badges side (top-bottom poster layout)	left, right	left
posterQualityBadgesPosition	Quality badges position (top/bottom poster layouts)	auto, left, right	auto
qualityBadgesStyle	Quality badges style (global fallback)	glass, square, plain	glass
posterQualityBadgesStyle	Poster quality badges style	glass, square, plain	glass
backdropQualityBadgesStyle	Backdrop quality badges style	glass, square, plain	glass
ratings	Rating providers (global fallback)	tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd, metacritic, metacriticuser, trakt, rogerebert, myanimelist, anilist, kitsu	all
posterRatings	Poster rating providers	tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd, metacritic, metacriticuser, trakt, rogerebert, myanimelist, anilist, kitsu	all
backdropRatings	Backdrop rating providers	tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd, metacritic, metacriticuser, trakt, rogerebert, myanimelist, anilist, kitsu	all
logoRatings	Logo rating providers	tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd, metacritic, metacriticuser, trakt, rogerebert, myanimelist, anilist, kitsu	all
ratingStyle (or style)	Badge style	glass (Pill), square (Dark), plain (No BG)	glass (poster/backdrop), plain (logo)
tmdbKey	TMDB v3 API Key (Stateless)	String (e.g. your_key)	Required
mdblistKey	MDBList API Key (Stateless)	String (e.g. your_key)	Required
imageText	Image text (poster/backdrop only)	original, clean, alternative	original (poster), clean (backdrop)
posterRatingsLayout	Poster layout	top, bottom, left, right, top-bottom, left-right	top-bottom
posterRatingsMaxPerSide	Max badges per side	Number (1-20)	auto
backdropRatingsLayout	Backdrop layout	center, right, right-vertical	center

Supported ID Formats

ERDB supports multiple formats to identify media:

• IMDb: tt0133093 (standard tt + numbers)
• TMDB: tmdb:603 (prefix tmdb: followed by the ID)
• Kitsu: kitsu:1 (prefix kitsu: followed by the ID)
• Anime Mappings: provider:id (e.g. anilist:123, myanimelist:456)

Addon Developer Guide

To integrate ERDB into your addon:

1. Config String: use a single erdbConfig string (base64url) generated by the ERDB configurator. It contains base URL, TMDB key, MDBList key, and all parameters (ratings with per-type overrides, lang, quality badges with per-type overrides, side, style, per-type style, per-type text, layouts).
2. Addon UI: show ONLY the toggles to enable/disable poster, backdrop, logo. No modal and no extra settings panels.
3. Fallback: if a type is disabled, keep the original artwork (do not call ERDB for that type).
4. Decode: decode erdbConfig (base64url -> JSON) once and reuse it.
5. URL build: {baseUrl}/{type}/{id}.jpg?tmdbKey=...&mdblistKey=...&ratings=...&posterRatings=...&backdropRatings=...&logoRatings=...&lang=...&streamBadges=...&posterStreamBadges=...&backdropStreamBadges=...&qualityBadgesSide=...&posterQualityBadgesPosition=...&qualityBadgesStyle=...&posterQualityBadgesStyle=...&backdropQualityBadgesStyle=...&ratingStyle=...&imageText=... using the per-type config fields:
   • poster: posterRatingStyle, posterImageText
   • backdrop: backdropRatingStyle, backdropImageText
   • logo: logoRatingStyle (omit imageText)

AI Integration Prompt

If you are using an AI agent (Claude, ChatGPT, etc.) to build your addon, copy this prompt:

Act as an expert addon developer. I want to implement the ERDB Stateless API into my media center addon.

--- CONFIG INPUT ---
Add a single text field called "erdbConfig" (base64url). The user will paste it from the ERDB site after configuring there.
Do NOT hardcode API keys or base URL. Always use cfg.baseUrl from erdbConfig.

--- DECODE ---
Node/JS: const cfg = JSON.parse(Buffer.from(erdbConfig, 'base64url').toString('utf8'));

--- FULL API REFERENCE ---
Endpoint: GET /{type}/{id}.jpg?...queryParams

Parameter               | Values                                                              | Default
type (path)             | poster, backdrop, logo                                               | -
id (path)               | IMDb (tt...), TMDB (tmdb:id / tmdb:movie:id / tmdb:tv:id), Kitsu (kitsu:id), AniList, MAL          | -
ratings                 | tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd,         | all
                        | metacritic, metacriticuser, trakt, rogerebert, myanimelist,          |
                        | anilist, kitsu (global fallback)                                     |
posterRatings           | tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd,         | all
                        | metacritic, metacriticuser, trakt, rogerebert, myanimelist,          |
                        | anilist, kitsu (poster only)                                         |
backdropRatings         | tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd,         | all
                        | metacritic, metacriticuser, trakt, rogerebert, myanimelist,          |
                        | anilist, kitsu (backdrop only)                                       |
logoRatings             | tmdb, mdblist, imdb, tomatoes, tomatoesaudience, letterboxd,         | all
                        | metacritic, metacriticuser, trakt, rogerebert, myanimelist,          |
                        | anilist, kitsu (logo only)                                           |
lang                    | Any TMDB ISO 639-1 code (en, it, fr, es, de, ja, ko, etc.)            | en
streamBadges            | auto, on, off (global fallback)                                      | auto
posterStreamBadges      | auto, on, off (poster only)                                          | auto
backdropStreamBadges    | auto, on, off (backdrop only)                                        | auto
qualityBadgesSide       | left, right (poster top-bottom only)                                 | left
posterQualityBadgesPosition | auto, left, right (poster top/bottom only)                       | auto
qualityBadgesStyle      | glass, square, plain (global fallback)                               | glass
posterQualityBadgesStyle| glass, square, plain (poster only)                                   | glass
backdropQualityBadgesStyle| glass, square, plain (backdrop only)                               | glass
ratingStyle             | glass, square, plain                                                 | glass
imageText               | original, clean, alternative                                         | original
posterRatingsLayout     | top, bottom, left, right, top-bottom, left-right                     | top-bottom
posterRatingsMaxPerSide | Number (1-20)                                                        | auto
backdropRatingsLayout   | center, right, right-vertical                                        | center
tmdbKey (REQUIRED)      | Your TMDB v3 API Key                                                 | -
mdblistKey (REQUIRED)   | Your MDBList.com API Key                                             | -

--- INTEGRATION REQUIREMENTS ---
1. Use ONLY the "erdbConfig" field (no modal and no extra settings panels).
2. Add toggles to enable/disable: poster, backdrop, logo.
3. If a type is disabled, keep the original artwork (do not call ERDB for that type).
4. Build ERDB URLs using the decoded config and inject them into both catalog and meta responses.

--- PER-TYPE SETTINGS ---
poster   -> ratingStyle = cfg.posterRatingStyle, imageText = cfg.posterImageText
backdrop -> ratingStyle = cfg.backdropRatingStyle, imageText = cfg.backdropImageText
logo     -> ratingStyle = cfg.logoRatingStyle (omit imageText)
Ratings providers can be set per-type via cfg.posterRatings / cfg.backdropRatings / cfg.logoRatings (fallback to cfg.ratings).
Quality badges can be set per-type via cfg.posterStreamBadges / cfg.backdropStreamBadges (fallback to cfg.streamBadges).
Quality badges style can be set per-type via cfg.posterQualityBadgesStyle / cfg.backdropQualityBadgesStyle (fallback to cfg.qualityBadgesStyle).

--- URL BUILD ---
const typeRatingStyle = type === 'poster' ? cfg.posterRatingStyle : type === 'backdrop' ? cfg.backdropRatingStyle : cfg.logoRatingStyle;
const typeImageText = type === 'backdrop' ? cfg.backdropImageText : cfg.posterImageText;
${cfg.baseUrl}/${type}/${id}.jpg?tmdbKey=${cfg.tmdbKey}&mdblistKey=${cfg.mdblistKey}&ratings=${cfg.ratings}&posterRatings=${cfg.posterRatings}&backdropRatings=${cfg.backdropRatings}&logoRatings=${cfg.logoRatings}&lang=${cfg.lang}&streamBadges=${cfg.streamBadges}&posterStreamBadges=${cfg.posterStreamBadges}&backdropStreamBadges=${cfg.backdropStreamBadges}&qualityBadgesSide=${cfg.qualityBadgesSide}&posterQualityBadgesPosition=${cfg.posterQualityBadgesPosition}&qualityBadgesStyle=${cfg.qualityBadgesStyle}&posterQualityBadgesStyle=${cfg.posterQualityBadgesStyle}&backdropQualityBadgesStyle=${cfg.backdropQualityBadgesStyle}&ratingStyle=${typeRatingStyle}&imageText=${typeImageText}&posterRatingsLayout=${cfg.posterRatingsLayout}&posterRatingsMaxPerSide=${cfg.posterRatingsMaxPerSide}&backdropRatingsLayout=${cfg.backdropRatingsLayout}

Omit imageText when type=logo.

Skip any params that are undefined. Keep empty ratings/posterRatings/backdropRatings/logoRatings to disable providers.

---

Addon Proxy (Stremio)

ERDB can act as a proxy for any Stremio addon and always replace images (poster, background, logo) with the ones generated by ERDB.

Manifest Proxy (Stremio)

Stremio does not use query params here. You must generate the link from the ERDB site using the "Addon Proxy" section:

https://YOUR_ERDB_HOST/proxy/{config}/manifest.json

{config} is created automatically by the site based on the inserted parameters.

Notes

• The proxy rewrites enabled meta.poster, meta.background, meta.logo (types can be toggled in the Addon Proxy UI).
• The url field must point to the original addon's manifest.json.
• tmdbKey and mdblistKey are required.

for.supported.addons.mp4

for.unsupported.addons.mp4

© 2026 ERDB Project