Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/rivenmedia/riven-ts/llms.txt

Use this file to discover all available pages before exploring further.

The TVDB plugin is Riven’s primary metadata provider for TV shows and anime. It is always enabled — you never need to add tvdb to enabledPlugins. Whenever a show or anime item enters the Riven pipeline, this plugin fetches its complete series record, all episodes in official broadcast order, and English translations from TheTVDB API v4. It also calls the TVMaze API as a secondary source to retrieve the show’s broadcast timezone, which TVDB does not provide directly.

​
What TVDB fetches

Series Record

Full series metadata including name, overview, status, genres, and all available translations.

Episode List

Every episode in official broadcast order, with TVDB IDs, season and episode numbers, and air dates.

Translations

English-language overviews and titles via the /series/:id/translations/eng endpoint.

Broadcast Timezone

IANA-compliant timezone of the show’s original network, sourced from TVMaze when TVDB has no timezone data.

​
Always enabled

Because Riven cannot index TV or anime content without episode and season metadata, the TVDB plugin is loaded on every startup regardless of enabledPlugins. The only thing you need to configure is your API key.
Do not add tvdb to RIVEN_SETTING__enabledPlugins. It is automatically active and adding it has no effect.

​
Getting a TVDB API key

  1. Create a free account at thetvdb.com/subscribe.
  2. Navigate to API Access in your account dashboard.
  3. Generate a new API key and copy it.
The default key baked into the plugin (6be85335-5c4f-4d8d-b945-d3ed0eb8cdce) is a public fallback key. For production use, supply your own key to avoid rate-limit sharing with other Riven users.

​
Settings

​
apiKey
string
default:"6be85335-5c4f-4d8d-b945-d3ed0eb8cdce"
The TheTVDB v4 API key used to obtain a bearer token from the /login endpoint. Tokens are cached in memory for 25 days and automatically refreshed. Get your own key at thetvdb.com/subscribe.

​
Configuration

Set the TVDB API key via environment variable: 
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TVDB__apiKey="your-tvdb-api-key"

​
Full .env example

# TVDB metadata plugin (always enabled — no entry in enabledPlugins needed)
RIVEN_PLUGIN_SETTING__REPO_PLUGIN_TVDB__apiKey="your-tvdb-api-key"

​
How it works

When a TV show or anime item is ready for metadata indexing, Riven emits a MediaItemIndexRequested event. The TVDB plugin handles this event in three steps:
1

Series lookup

Calls GET /series/:tvdbId/extended?short=true&meta=translations to retrieve the full series record, including aliases, genres, and available translation languages.
2

Episode fetch

Calls GET /series/:tvdbId/episodes/official/eng with automatic pagination to collect every episode in official broadcast order. Results are accumulated across all pages before continuing.
3

Timezone resolution

Calls the TVMaze GET /lookup/shows?thetvdb=:tvdbId endpoint to retrieve the show’s original network timezone. This is merged into the final series record so that air dates are converted to accurate local broadcast times.
The combined result is transformed into Riven’s internal entity model and persisted to PostgreSQL, making full season and episode trees available to scrapers and the media server plugins.

​
Secondary data source: TVMaze

The TVDB plugin bundles a lightweight TVMaze client (TvMazeAPI) solely to resolve broadcast timezones. TVMaze is queried at a conservative rate (20 requests per 10 seconds) and failures are handled gracefully — if TVMaze cannot return a timezone, the item is still indexed without one.
The TVMaze client does not require any API key or additional configuration. It is invoked automatically as part of every TV show indexing run.

Build docs developers (and LLMs) love

Get started for freeTalk to us