# AIOMetadata: a configurable metadata aggregator for Stremio

> AIOMetadata is a Stremio addon aimed at people who want to choose their metadata source rather than accept the default. It merges TMDB, TVDB, MyAnimeList, AniList, IMDb, TVmaze, Fanart.tv and MDBList into one catalog set, keeps a per-user configuration behind a URL, maps identifiers between the major ID systems, and caches the results in Redis so a second request does not hit the providers again.

**cedya77/aiometadata** — my space for aiometadata

- Repository: https://github.com/cedya77/aiometadata
- Stars: 529 · Forks: 124
- Language: TypeScript
- License: GPL-3.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/cedya77-aiometadata

## A metadata addon for people who dislike the default metadata

AIOMetadata describes itself as the ultimate Stremio metadata addon, and the description in the repository is more specific: a next-generation, power-user-focused metadata addon for Stremio.

It aggregates and enriches movie, series and anime metadata from multiple sources, naming TMDB, TVDB, MyAnimeList, AniList, IMDb, TVmaze, Fanart.tv, MDBList and more, and it gives you full control over catalog sources, artwork and search.

That word power-user is doing the work in that sentence, and it is worth being clear about what it means. A standard Stremio setup has one metadata provider and one set of artwork, and the configuration is whatever that provider serves. AIOMetadata's premise is that you can pick the provider per content type, mix artwork from one place with descriptions from another, and reorder the catalogs you see, and it treats that as the default rather than as an advanced setting.

The stack is TypeScript on Node, with a React and Next.js configuration interface on the front and an addon backend. The repository default branch is dev, the last push was on 2026-10-20, and the releases are v3.5.1 on 2026-10-14, v3.6.0 and v3.6.1 on 2026-10-20, which is a fast release cadence for an addon.

One licensing detail is worth checking before you deploy it. The repository is recorded as GPL-3.0, while the npm package metadata for aio-metadata declares Apache-2.0. Those are different terms for the same code, so the LICENSE file and the terms of the components you distribute are worth reading rather than assuming.

The topics list, tmdb, stremio, addon, metadata, tvdb and MyAnimeList, tells you the same thing the description does: this is a tool for people who already know which metadata services they prefer.

## The feature list, and the parts that are genuinely unusual

The features section is long, and most of it is a list of providers. Three items are worth pulling out.

The first is the per-type provider selection with rich artwork. You choose your preferred provider for each type, whether movie, series or anime, and the artwork comes from TMDB, TVDB, Fanart.tv, AniList and others with language-aware selection and fallback. The language-aware part matters more than it sounds: a series with a Japanese original and an English dub has different poster sets, and picking the wrong one is the single most common complaint about any Stremio addon.

The second is the advanced ID mapping. The addon maps between all the major ID systems, naming MAL, TMDB, TVDB, IMDb, AniList, AniDB, Kitsu and TVmaze. That is the unglamorous feature that makes the rest work. Stremio identifies things by a provider-specific id, and an aggregator that combines four providers has to know that AniList 1234 and MAL 5678 are the same anime. Doing that mapping is most of the work, and doing it badly is why some aggregators show duplicate or mismatched entries.

The third is the caching, described as global and self-healing: Redis-backed, ETag-aware and self-healing, for fast and reliable metadata and catalog responses. The self-healing part means a cached entry that has gone stale is refreshed rather than served, which matters when providers change their artwork or when a title gets new episodes.

The rest of the list covers custom catalogs you can add, reorder and delete in a sortable UI, including MDBList, streaming and custom lists; streaming provider catalogs for Netflix, Disney+ and the rest with region and monetization filters; dynamic search where you enable or disable search engines per type and optionally use AI-powered search with Gemini; per-user configuration with a password and optional addon password protection plus trusted UUIDs for passwordless re-login; and a React interface with drag and drop, tooltips and instant feedback.

## Installing it: a hosted instance or a compose file

There are two ways to get it running, and the hosted one is deliberately the easy path.

On a hosted instance you visit the /configure page, set your catalogs, providers and preferences, save your config and install the generated Stremio addon URL. There is nothing to deploy and nothing to key in except the provider credentials the hosted instance already has.

Self-hosting is a Docker Compose file. The addon service runs the image ghcr.io/cedya77/aiometadata:latest, publishes port 3232, reads its environment from a .env file, mounts a data directory, and waits for the Redis service to be healthy before it starts:

```yaml
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3232/health"]
```

That health check line is the one to copy carefully, because the addon service is configured to wait for Redis to report healthy rather than merely to start, and the Redis service has its own check that pings the server.

The compose file also carries a commented out Postgres service, with its own environment and a pg_isready check. That block is a leftover from the database design rather than something you need to enable, since the running configuration uses Redis for the cache.

The Redis service is run with appendonly yes and a save policy of 3600 seconds and one change, so the cache survives a restart without being written on every operation.

You create a .env file with your API keys and settings, following the .env.example in the repository, and then start it:

```bash
docker compose up -d
```

The Traefik labels in the compose file are all commented out as well, so the default deployment is a plain published port, and a reverse proxy is something you add if you need it.

## The optional pieces, and the Jikan shutdown

The README lists three optional pieces of infrastructure with guides of their own, and the note that none of them is needed to run the addon is important, because people often assume the full stack is required.

The image cache serves artwork from disk instead of re-fetching it upstream, which is the difference between an addon that hammers an image CDN and one that does not.

The self-hosted Jikan API is the one with a story behind it. The public Jikan API has shut down, the addon defaults to the public Tenrai API instead, and running your own instance gives you more headroom. That is a concrete illustration of the fragility of building on other people's free API tiers, and the addon has adapted rather than broken.

LumiereDB is a self-hosted IMDb database, and it adds LumiereDB search, people search, and Popular and Trending catalogs for movies and series. People search in particular is the kind of feature that a metadata aggregator cannot get from the standard providers, because it is about the people in the credits rather than about the titles.

Then there are two integrations that are about how the addon is presented rather than about what it fetches. Sign-in with an identity provider lets people sign in with an existing account instead of a UUID and a password, and reach their saved configurations from the list. And the Jellyfin server option presents a configuration as a Jellyfin server, so Jellyfin clients browse your catalogs and collections, play through your stream addon, and keep Continue Watching, Next Up and watched state in step with your trackers.

That last one is ambitious. A Stremio addon is a manifest and a set of JSON endpoints, and exposing that as a Jellyfin library with watched state synchronised is a different kind of integration than serving a catalog.

## The endpoints, and what the per-user URL actually is

The API section lists the endpoints, and one of them explains how the whole per-user configuration model works.

The Stremio manifest lives at /stremio/:userUUID/:compressedConfig/manifest.json. That is the URL you paste into Stremio, and the configuration is compressed into the path rather than sent as a header or a cookie. The consequence is that a configuration is a self-contained URL, which is why it can be shared, bookmarked and used on another device without a login, and why the addon keeps a per-user record keyed by the UUID.

Around it are the configuration endpoints. Saving is a POST to /api/config/save, loading is a POST to /api/config/load/:userUUID, updating is a PUT to /api/config/update/:userUUID, and there is a GET to /api/config/is-trusted/:uuid for the trusted UUID mechanism that lets a returning user skip the password.

The cache endpoints live under /api/cache/*, described as cache health and admin endpoints.

Then there are the image endpoints, and these are the ones a Stremio client calls constantly. The poster proxy is /poster/:type/:id, with fallback and RPDB support, so when the configured provider has no artwork for an item the proxy can fall back to another source, and RPDB is the poster database that fills the remaining gaps. There is a resize-image proxy and an image blur proxy at /api/image/blur.

So the addon is a metadata aggregator in front of the providers, an image proxy in front of the artwork, and a configuration store in front of the user. Those three roles are the whole design, and the endpoints map onto them one for one.

## The codebase: two applications and a multi-stage image

The repository holds two applications rather than one, and the build scripts say how they fit together.

The backend lives in the addon/ directory and the frontend in configure/, with data/ for static content, docker/ for the entrypoint and compose pieces, docs/ for the guides, scripts/ for the build helper scripts, and public/ for assets served as they are.

The npm scripts are the clearest map. The dev script runs Vite for the frontend, dev:server runs the backend under nodemon, and there are TypeScript variants of the backend scripts using ts-node. The build script runs Vite for the frontend and build:backend runs tsc against tsconfig.backend.json, producing a compiled server, and start:backend runs the compiled output. There are four lint scripts, one for the backend and scripts directory, one for the frontend source, one for the repository configuration files, and eslint itself for everything. The check:env script runs a small TypeScript program that validates the environment against a registry.

The engine requirement is Node 24, from version 24.0.0 up to but not including 25, which is worth noting because it rules out Node 22 images that many deployments still use.

The Dockerfile is a two stage build on node:24-alpine. The builder copies the manifests, installs with npm ci using a cache mount, copies the source and runs both builds. The runner copies the manifests, installs production dependencies only, and copies the addon, dist and public directories across from the builder, along with the entrypoint script whose line endings are fixed with sed and made executable. It adds ca-certificates and wget, the second because the compose health check uses wget to spider the health endpoint. Two environment variables are set, UV_THREADPOOL_SIZE at 16 and DOTENV_CONFIG_QUIET, the latter so that the dotenv loader does not print what it has loaded.

## Where AIOMetadata is the wrong choice

There are cases where a metadata aggregator is the wrong answer, and the first one is the most obvious.

It does not provide video. It is a metadata addon, and a Stremio user still needs a stream addon, which this project is not and does not try to be. For somebody who simply wants the standard catalog and does not care which provider served the poster, the default setup is less to maintain and one less service to run.

The second limit is the dependency on other people's APIs. The Jikan shutdown is the proof: an upstream service that was free and popular disappeared, and the addon had to move to a different public instance and then offer a self-hosted option. Any configuration you choose is only as reliable as the provider behind it, and the more providers you mix, the more failure modes you inherit.

The third is the operational weight. The interesting settings live in the configure page and per-user configurations live in the database, so there is state to back up and, for a shared instance, a user model to think about, including the addon password and the trusted UUID mechanism.

The alternative approach is to use the stock Stremio addons for the providers you actually care about, or to call the provider APIs directly in a script of your own. The difference in approach is that AIOMetadata is a single configurable aggregator with cross-provider ID mapping and a per-user configuration, which is what you want when you want to mix sources, and it is a lot of machinery for what you want when you want one provider done well. The self-hosted LumiereDB and Jikan options blur that line, since at that point you are running the upstream services yourself anyway.

## Conclusion

AIOMetadata suits a Stremio user who wants per-title control over where artwork and metadata come from, and who is willing to run a container and hold API keys for several providers. It does not suit somebody who wants a plug and play install, since the interesting settings live behind a configure page and a set of provider keys, and it does not suit a deployment that cannot depend on third party APIs staying online. Check three things before you deploy it: which provider keys you are prepared to hold, since the richness of the output depends on them, whether you are going to self-host the anime metadata source, because the README says the public Jikan API has shut down and the default is the public Tenrai API, and which optional pieces you want, from the image cache to the self-hosted IMDb database. The last push to the repository was on 2026-10-20 and the newest release is v3.6.1.

## FAQ

### What does AIOMetadata do for Stremio?

It is a Stremio addon that aggregates and enriches movie, series and anime metadata from sources including TMDB, TVDB, MyAnimeList, AniList, IMDb, TVmaze, Fanart.tv and MDBList, letting you choose the provider per content type, reorder catalogs and control artwork and search.

### How do I self-host AIOMetadata?

With Docker Compose. The addon image ghcr.io/cedya77/aiometadata:latest is published on port 3232, reads a .env file, mounts a data directory and waits for the Redis service to be healthy, and the compose file also carries a commented out Postgres block. You create the .env file from .env.example and run docker compose up -d.

### What optional pieces does AIOMetadata support?

An image cache that serves artwork from disk, a self-hosted Jikan API for anime metadata, the self-hosted LumiereDB IMDb database with people search and Popular and Trending catalogs, sign-in with an identity provider, and a Jellyfin server presentation so Jellyfin clients can browse the catalogs and keep watched state in step.

### How does AIOMetadata store per-user configuration?

The Stremio manifest URL carries the user UUID and the compressed configuration in the path, and the configuration is saved per user in the database through the /api/config/save, /api/config/load and /api/config/update endpoints, with a trusted UUID check for passwordless re-login.

### Why does the AIOMetadata documentation mention the Jikan API?

Because the public Jikan API has shut down. The addon defaults to the public Tenrai API instead, and the documentation explains how to run your own Jikan instance for more headroom, since the whole addon depends on third party metadata sources being reachable.

## Sources

- [cedya77/aiometadata on GitHub](https://github.com/cedya77/aiometadata)
- [Issues](https://github.com/cedya77/aiometadata/issues)
- [License: GPL-3.0](https://github.com/cedya77/aiometadata/blob/dev/LICENSE)
- [README](https://github.com/cedya77/aiometadata/blob/dev/README.md)
- [Releases](https://github.com/cedya77/aiometadata/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cedya77-aiometadata