Skip to content
Stremio Setup Guide

AIOMetadata - Complete Configuration and Operations Guide (2026)

38 min readAdvanced
Legal & Safety Notice

AIOMetadata is a metadata addon layer. It provides metadata, posters, and catalog/search wiring. It is not a stream host.

What AIOMetadata Does (System View)

AIOMetadata unifies metadata for movies, series, and anime into one configurable addon endpoint.

Request lifecycle:

  1. Stremio requests catalog/search/meta data.
  2. AIOMetadata chooses provider routes based on your config.
  3. Catalog/search responses are normalized.
  4. Art provider and rating-poster logic are applied.
  5. Result is cached and returned.

Why this matters:

  • You tune one metadata/control plane instead of many addons.
  • You can keep provider choice explicit per media type.
  • You can trade speed, quality, and strictness with clear toggles.

Prerequisites

  • Stremio account and at least one signed-in client.
  • AIOMetadata configure URL (public instance or self-host endpoint).
  • API keys for providers you actually plan to use.
  • Optional OAuth sessions (TMDB, Trakt, AniList, Simkl) if you need account-linked catalogs.

Safe Setup Sequence

  1. Open the AIOMetadata configure page.
  2. Set Providers first (movie/series/anime sources).
  3. Add API keys in Integrations and run key validation.
  4. Configure Art Providers and poster rating provider.
  5. Configure Catalogs and Search.
  6. Apply filter/safety toggles (SFW, unreleased, age rating).
  7. Save configuration and install URL in Stremio.
  8. Verify with 3 test titles (movie, series, anime).
Warning

If metadata appears unchanged after install, verify addon priority and client cache state before changing settings again.

Complete Configure Menu Reference

1) General Settings

These options control global metadata behavior.

  • language (default en-US): preferred metadata language.
  • includeAdult (default false): allows adult catalogs/items where provider supports it.
  • blurThumbs (default false): blurs thumbnails for safer browsing.
  • showPrefix (default false): display source/provider prefixes in output labels.
  • showMetaProviderAttribution (default false): shows provider attribution text in metadata output.
  • castCount (default 10): max cast entries shown.
  • displayAgeRating (default false): show age-rating metadata badges.
  • ageRating (default None): content age filter baseline.
  • sfw (default false): safe-for-work mode.
  • hideUnreleasedDigital (default false): suppress unreleased digital content in catalogs.
  • hideUnreleasedDigitalSearch (default false): suppress unreleased digital content in search results.
  • showDisabledCatalogs (default false): expose disabled catalogs in configure view for management.
  • catalogModeOnly (optional): catalog-focused behavior mode for special deployments.
  • timezone: used for time-sensitive catalog behavior.

Operational note:

  • hideUnreleasedDigital and hideUnreleasedDigitalSearch reduce false positives and placeholder results in discovery-heavy workflows.

2) Integrations and API Keys

This section controls external API credentials and account sessions.

Supported key fields:

  • tmdb
  • tvdb
  • fanart
  • rpdb
  • topPoster
  • mdblist
  • gemini

Session/token fields:

  • sessionId (TMDB auth session)
  • traktTokenId
  • anilistTokenId
  • simklTokenId

Related behavior toggles:

  • posterRatingProvider: rpdb or top
  • usePosterProxy (default true)
  • mdblistWatchTracking (default true)
  • anilistWatchTracking (default true)
  • simklWatchTracking (default true)

How TMDB auth works:

  1. You provide TMDB API key.
  2. Configure page starts TMDB OAuth flow.
  3. TMDB returns request token.
  4. Addon creates/stores session id.

Practical rule:

  • Keep only keys you use. Large key sets increase troubleshooting surface.

3) Metadata Providers

Provider mapping is explicit per media family.

Movie provider

Options:

  • tmdb
  • tvdb
  • imdb

Default:

  • tmdb

Series provider

Options:

  • tvdb (recommended by UI)
  • tmdb
  • tvmaze
  • imdb

Default:

  • tvdb

Anime provider

Options:

  • kitsu (recommended by UI)
  • mal
  • tvdb
  • imdb

Default:

  • mal

Anime ID provider

Options:

  • imdb (compatibility-first)
  • kitsu
  • mal

Default:

  • imdb

Provider behavior toggles

  • forceAnimeForDetectedImdb (default false): forces anime meta provider after IMDb-detection mapping.
  • tvdbSeasonType (default default): official, default, dvd, absolute, alternate, regional.

MAL options

  • skipFiller (default false)
  • skipRecap (default false)
  • allowEpisodeMarking (default false)
  • useImdbIdForCatalogAndSearch (default false)

If useImdbIdForCatalogAndSearch is enabled, anime-provider choices are constrained in UI to avoid incompatible ID paths.

TMDB options

  • scrapeImdb (default false): enriches via IMDb mapping.
  • forceLatinCastNames (default false): normalize cast naming style.

4) Art Providers

Art routing is independent from metadata routing.

Config families:

  • artProviders.movie
  • artProviders.series
  • artProviders.anime
  • artProviders.englishArtOnly

Each media family can be configured either as:

  • Single provider value
  • Per-asset object:
    • poster
    • background
    • logo

Movie/series provider options:

  • meta
  • tmdb
  • tvdb
  • fanart
  • imdb

Anime art provider options:

  • meta
  • mal
  • anilist
  • tvdb
  • fanart
  • imdb

Important interaction:

  • Rating poster providers (rpdb / top) can override poster output, so art-provider poster choice is not always final.
  • Search results may use search-engine poster sources for performance, not full art-provider pipeline.

5) Catalogs

Catalog configuration is one of the largest surfaces in AIOMetadata.

Each catalog entry supports these core fields:

  • id
  • name
  • type (movie, series, anime, all)
  • source (tmdb, tvdb, mal, tvmaze, mdblist, trakt, streaming, stremthru, custom, anilist, letterboxd, simkl)
  • enabled
  • showInHome
  • sourceUrl (for custom/stremthru style sources)
  • displayType (manifest type override)
  • cacheTTL
  • pageSize
  • enableRatingPosters
  • randomizePerPage

Optional filter/sort fields:

  • sort
  • order
  • sortDirection
  • genreSelection (standard, anime, all)
  • filter_score_min
  • filter_score_max
  • genres

Metadata payload subfields may include:

  • itemCount, privacy, author, description
  • AniList-specific fields (username, listName, isCustomList)
  • Trakt-specific fields (useShowPosterForUpNext, airingSoonDays)
  • Letterboxd-specific fields (isWatchlist, identifier, url)
  • TMDB discover state (listId, listDescription, discover, discoverParams)
  • Simkl fields (interval, pageSize, status)

Built-in catalog groups include:

  • TMDB popular/trending/top-rated/by-year/by-language
  • TVDB trending/genres/collections
  • TVmaze daily schedule
  • MAL airing/upcoming/schedule/seasons/top/popular/decade catalogs
  • Streaming service catalogs by provider and media type

Catalog-level tuning guidance:

  • Use shorter cacheTTL only for volatile lists.
  • Keep high-value catalogs on Home (showInHome=true), push noisy sets to Discover-only.
  • Enable per-catalog rating posters only where poster overlays are useful.

Search has a global enable flag plus per-engine controls.

Top-level controls:

  • search.enabled
  • search.ai_enabled
  • search.searchOrder
  • search.searchNames
  • search.searchDisplayTypes
  • search.engineEnabled
  • search.engineRatingPosters

Primary provider map:

  • search.providers.movie: tmdb.search, tvdb.search, trakt.search, mdblist.search
  • search.providers.series: tmdb.search, tvdb.search, tvmaze.search, trakt.search, mdblist.search
  • search.providers.anime_movie: mal.search.movie, kitsu.search.movie
  • search.providers.anime_series: mal.search.series, kitsu.search.series
  • search.providers.people_search_movie: tmdb.people.search, tvdb.people.search, trakt.people.search
  • search.providers.people_search_series: tmdb.people.search, tvdb.people.search, trakt.people.search

Additional optional engines:

  • tvdb.collections.search (requires TVDB key)
  • gemini.search (requires Gemini key and AI toggle)

Search-specific controls that matter in production:

  • Per-engine enable switch (engineEnabled) lets you keep provider mapping but disable execution.
  • Search catalog drag-and-drop order controls UX priority.
  • Custom search name/type helps align Stremio display taxonomy.

7) Poster/Library Extras

  • enableRatingPostersForLibrary (default true): keeps rating posters in Continue Watching and Library contexts.
  • showRateMeButton (default false): adds rate-action entry in meta pages.
  • displayTypeOverrides.movie / displayTypeOverrides.series: global type overrides when required by downstream behavior.

8) Hidden / Internal State Keys (Do Not Tune Blindly)

  • catalogSetupComplete
  • deletedCatalogs
  • streaming
  • searchEnabled (legacy/top-level companion)

Treat these as migration/state keys unless you are debugging config serialization.

Save, Install, and Priority Behavior

  1. Save config (UUID/password profile on backend).
  2. Install generated URL in Stremio.
  3. Verify catalog/search order in UI.
  4. If behavior appears stale, restart app client and re-check same title.

Common failure pattern:

  • Users change config but do not persist/save the profile, then assume provider logic is broken.

Self-Hosting: Environment Configuration Reference

If you run AIOMetadata yourself, these env groups control behavior.

Core runtime

  • PORT
  • HOST_NAME
  • NODE_ENV
  • LOG_LEVEL
  • TZ
  • ADDON_LOGO_URL
  • ADDON_NAME_SUFFIX
  • CUSTOM_DESCRIPTION_BLURB

Data and cache

  • DATABASE_URI
  • REDIS_URL
  • CATALOG_TTL
  • META_TTL
  • CATALOG_LIST_ITEMS_SIZE

Security and control

  • ADMIN_KEY
  • ADDON_PASSWORD
  • DISABLE_METRICS

Provider/API keys

  • TMDB_API
  • TVDB_API_KEY
  • FANART_API_KEY
  • RPDB_API_KEY
  • MDBLIST_API_KEY
  • GEMINI_API_KEY

OAuth integrations

  • TRAKT_CLIENT_ID
  • TRAKT_CLIENT_SECRET
  • TRAKT_REDIRECT_URI
  • ANILIST_CLIENT_ID
  • ANILIST_CLIENT_SECRET
  • ANILIST_REDIRECT_URI
  • SIMKL_CLIENT_ID
  • SIMKL_CLIENT_SECRET
  • SIMKL_REDIRECT_URI

Request and provider limits

  • DISABLE_TRAKT_SEARCH
  • TRAKT_CONCURRENCY
  • TRAKT_MIN_TIME
  • SIMKL_ACTIVITIES_TTL

Global warming and refresh

  • ENABLE_CACHE_WARMING
  • CACHE_WARMUP_UUIDS
  • CACHE_WARMUP_UUID
  • CACHE_WARMUP_MODE
  • CATALOG_WARMUP_INTERVAL_HOURS
  • CATALOG_WARMUP_INITIAL_DELAY_SECONDS
  • CATALOG_WARMUP_MAX_PAGES_PER_CATALOG
  • CATALOG_WARMUP_RESUME_ON_RESTART
  • CATALOG_WARMUP_QUIET_HOURS_ENABLED
  • CATALOG_WARMUP_QUIET_HOURS
  • CATALOG_WARMUP_TASK_DELAY_MS
  • CATALOG_WARMUP_LOG_LEVEL
  • CATALOG_WARMUP_AUTO_ON_VERSION_CHANGE
  • TMDB_POPULAR_WARMING_ENABLED
  • CACHE_WARM_INTERVAL_HOURS
  • CACHE_WARM_LANGUAGE
  • CACHE_WARMUP_ON_STARTUP

MAL-specific warming

  • MAL_WARMUP_ENABLED
  • MAL_WARMUP_INTERVAL_HOURS
  • MAL_WARMUP_INITIAL_DELAY_SECONDS
  • MAL_WARMUP_TASK_DELAY_MS
  • MAL_WARMUP_QUIET_HOURS_ENABLED
  • MAL_WARMUP_QUIET_HOURS_RANGE
  • MAL_WARMUP_PRIORITY_PAGES
  • MAL_WARMUP_PRIORITY
  • MAL_WARMUP_SCHEDULE
  • MAL_WARMUP_DECADES
  • MAL_WARMUP_SFW
  • MAL_WARMUP_LOG_LEVEL

Cleanup scheduler

  • CACHE_CLEANUP_AUTO_ENABLED
  • CACHE_CLEANUP_QUIET_HOURS_ENABLED
  • CACHE_CLEANUP_QUIET_HOURS

Proxy and transport

  • SOCKS_PROXY_URL
  • HTTP_PROXY
  • HTTPS_PROXY
  • TMDB_SOCKS_PROXY_URL
  • MAL_SOCKS_PROXY_URL

Managed deployment override variables

Public/managed deployments can inject built-in provider keys and warmup defaults. Keep these for operators only:

  • BUILT_IN_TMDB_API_KEY, BUILT_IN_TVDB_API_KEY, BUILT_IN_FANART_API_KEY, BUILT_IN_RPDB_API_KEY, BUILT_IN_MDBLIST_API_KEY, BUILT_IN_GEMINI_API_KEY
  • BUILT_IN_MAL_WARMUP_* family
  • API validator and rate-limit controls (RATE_LIMIT_*, API_KEY_VALIDATOR_*)

Practical Presets

Preset A: Balanced (Most Users)

  • Movie provider: TMDB
  • Series provider: TVDB
  • Anime provider: MAL
  • Art providers: meta default
  • Search AI: off
  • hideUnreleasedDigital: on
  • Catalog TTL: default (24h)

Preset B: Anime-Heavy

  • Anime provider: Kitsu or MAL (test both)
  • Anime ID provider: Kitsu
  • MAL skipFiller: on
  • MAL skipRecap: on
  • MAL warmup enabled (self-host)

Preset C: Performance-First

  • Disable rarely used search engines
  • Keep engineRatingPosters only on primary engines
  • Increase TTLs for stable catalogs
  • Keep provider count minimal

Reddit-Informed Operational Notes

Recurring community findings (useful for troubleshooting):

  • Some users report stale config until save + client restart cycle is completed.
  • Catalog order confusion is often just low-priority placement in Stremio UI.
  • Wrapping AIOMetadata inside AIOStreams is usually unnecessary; running them separately is simpler for most setups.
  • AIOStreams users commonly reduce addon timeouts and rely on dynamic conditions for speed tuning.

Post-Setup Audit Tool

AIOMetadata Configuration Checklist

Run this after changing metadata providers, catalogs, or integrations. The checklist is stored locally in this browser.

Sources