PlexAniBridge Mappings

Last generated at: November 17, 2025 12:03 AM UTC

This repository contains an autogenerated mapping list that links AniList IDs to other media database IDs, including AniDB, MyAnimeList, TVDB, and IMDb. It's primarily designed for use with PlexAniBridge for media matching and metadata retrieval.

The mapping list is automatically generated daily to keep it up-to-date with the latest information from various sources.

A huge thank you to the primary mappings maintainer, @LuceoEtzio, for contributing over 4,000 mapping edits! ❤️

Key Features

• Comprehensive Aggregation: Gathers and merges ID data from multiple trusted sources.
• Automated Daily Updates: A GitHub Action runs daily to refresh the mappings.
• Manual Overrides: Easily correct or add mappings through a simple YAML edit file (mappings.edits.yaml).
• Detailed TVDB Mapping: Supports complex TVDB season and episode mappings, including split episode ranges, ratios, and offsets.
• Problem Reporting: Automatically flags entries with inconsistencies that may require manual review.

How It Works

The mapping process is powered by a Python script that performs the following steps:

1. Fetches Data: The script collects data from the sources listed below.
2. Aggregates & Merges: It consolidates all the fetched data, using the AniList ID as the primary key.
3. Applies Manual Edits: It overrides or adds data from the mappings.edits.yaml file.
4. Data Validation: Using pre-fetched information like episode counts and season details, it verifies the accuracy of the mappings and flags any inconsistencies.
5. Output Mappings: Finally, it produces the final mappings.json file.

Data Sources

The final mappings are a result of data aggregated from the following sources:

Source	Description
Anime-Lists/anime-lists	Maps AniDB IDs to TVDB series IDs and IMDb IDs.
manami-project/anime-offline-database	Maps AniDB IDs to MyAnimeList IDs and AniList IDs.
notseteve/AnimeAggregations	Maps AniDB links to TMDB IDs, IMDb IDs, and MyAnimeList IDs.
Wikidata	Provides various cross-database links via SPARQL queries.
LuceoEtzio/PlexAniBridge-Custom-Mappings	Provides episode mappings for TMDB and alternate show orders

Mappings Schema

The primary output of this repository is the mappings.json file. You can find the schema of this file at mappings.schema.json.

mappings.json

This file contains the complete set of ID mappings. The primary key for each entry is the AniList ID.

Example Entry

{
  "98310": {
    "anidb_id": 12820,
    "mal_id": [
      34915,
      36186,
      36529
    ],
    "tvdb_id": 333234,
    "tvdb_mappings": {
      "s0": "e1",
      "s1": "e1-e13"
    }
  }
}

Field Definitions

Field	Type	Description
anidb_id	int	The corresponding ID on AniDB.
imdb_id	str | list[str]	The IMDb ID(s) in tt... format.
mal_id	int | list[int]	The MyAnimeList ID(s).
tmdb_movie_id	int | list[int]	The TMDB Movie ID(s).
tmdb_show_id	int	The TMDB Show ID.
tvdb_id	int	The TVDB ID.
tmdb_mappings	object	An object mapping TMDB seasons to AniList episodes. See the detailed explanation below.
tvdb_mappings	object	An object mapping TVDB seasons to AniList episodes. See the detailed explanation below.

The Episode Mappings Object

The tmdb_mappings and tvdb_mappings objects define the episode and season mappings between AniList and TMDB/TVDB. The keys represent a season (e.g., "s1"), and the values are string patterns that define the mapping rules.

Note

The PlexAniBridge-Mappings repository only supports (the default) aired order mappings for TVDB and TMDB. If you are looking alternate orders such as DVD or absolute order, check out the LuceoEtzio/PlexAniBridge-Custom-Mappings repository.

Pattern Format: 'e{start}-e{end}|{ratio},e{start2}-e{end2}|{ratio2},...'

• e{start}: The starting episode number of a range on TVDB.
• e{end}: The ending episode number. If omitted (e.g., e13-), the range is open-ended.
• |{ratio} (optional): A multiplier to handle different episode granularities.
  • Positive Ratio (e.g., |2): 2 TVDB episodes are equivalent to 1 AniList episode.
  • Negative Ratio (e.g., |-2): 1 TVDB episode is equivalent to 2 AniList episodes.

Examples:

// Maps Season 1 episodes 1-12. The |2 ratio means that every 2 TMDB/TVDB episodes
// in this range correspond to 1 episode on AniList. Ranges must be divisible
// by the ratio when positive.
"s1": "e1-e12|2"

// Maps all episodes in Season 2 starting from episode 13 onwards.
"s2": "e13-"

// Maps the entirety of Season 1 with a direct 1:1 episode correspondence.
// An empty string is the simplest form of mapping.
"s1": ""

// Maps TMDB/TVDB Season 1, episodes 4 through 6. The |-2 ratio means that
// every TMDB/TVDB episode in this range corresponds to 2 episodes on AniList.
"s1": "e4-e6|-2"

The API

While using the mappings.json file directly is encouraged, there is also a simple API available at https://plexanibridge-api.elias.eu.org/.

The API is self documented with both OpenAPI and Swagger UI. Below is a brief overview of the available endpoints:

Endpoint	Method	Description
/api/v2/all	GET	Returns all mappings in the mappings.json file.
/api/v2/search	GET	Searches for all mappings that match any given ID(s).

Contributing

The best way to contribute is to fix incorrect or missing mappings. The automated script isn't perfect, and manual corrections are sometimes necessary.

You can make changes by editing the mappings.edits.yaml file and submitting a pull request.

How to Edit mappings.edits.yaml

Find the AniList ID you want to correct, or add it if it's missing. Then, specify the fields you want to add or override.

Example Scenario:

Let's say the automated script has incorrect tvdb_id and tvdb_mappings for AniList ID 12345. You can correct it like this:

12345: # Add or find the AniList ID at the root of the file.
  # Override the incorrect tvdb_id.
  tvdb_id: 98765
  # Provide the correct TVDB season-to-episode mapping.
  tvdb_mappings:
    s1: e1-e12
    s2: e1-e12

The script will automatically apply these edits during its next run, and your changes will be reflected in mappings.json.

Writing Comments:

If you feel the need to explain your changes, you can add comments in the YAML file using the # symbol (not required for contributing). For example:

12345: # This is a comment explaining why this mapping was changed.
  # Another comment explaining the changes in more detail.
  tvdb_id: 98765 # Corrected TVDB ID based on recent updates.

Make sure that your comments are NOT at the root level of the YAML file, as the script may not sort them correctly. Instead, place comments next to the specific fields you are editing or inside the mapping entry object in their own lines like in the example above.

Known Issues

Uncorrectable Entries

Some entries can be fully added to plex, but cannot be synced:

---

The Melancholy of Haruhi Suzumiya

• As Anilist has the second season with 28 episodes, which contains the episodes of the first season as well, TVDB having two 14 episode seasons, and the original airing being out of order, there is no default option that would satisfy most people, so it has been intentionally unmapped. However it is still syncable and users can use custom mappings to do so.

In This Corner of the World

• Anilist has separate entries for the regular and extended edition of this film, which do not have unique entries on IMDb nor TMDB, so there is no way to know which it is, and it has been intentionally unmapped. However it is still syncable and users can use custom mappings to do so.

The Seven Deadly Sins

• Plex has an incorrect internal ID for the series. May be rectified in future.

Super Dragon Ball Heroes

• Plex has an incorrect internal ID for the series. May be rectified in future.

Inazuma Eleven Ares

• Plex has an incorrect internal ID for the series. May be rectified in future.

Super Gals!

• There are duplicate TVDB entries with different season layouts that Plex has merged into one entry. Intentionally unmapped. May be rectified in future. However it is still syncable and users can use custom mappings to do so.

Silver Fang

• Plex has an incorrect internal ID for the series. May be rectified in future.

Nyanpire

• Plex has an incorrect internal ID for the series. May be rectified in future.

The Daughter of Twenty Faces

• Plex has an incorrect internal ID for the series. May be rectified in future.

Witchy Precure!/Mahoutsukai PreCure!

• Plex has an incorrect internal ID for the series. May be rectified in future.

---

Unintuitive Entries

There are a small number of entries that do not behave as the average user might expect, but have been left this way for consistency's sake:

---

Monogatari Second Season

• Anilist includes the three recap episodes that were not included in the Blu-ray release, and are not included in the TVDB season. Users may use custom mappings to ensure correct watch status without the recaps.

Cowboy Bebop

• The TVDB Aired order presents the episodes by first air date, out of order. The DVD order's episodes are in order, but the specials are differently ordered, which would cause the wrong specials to be marked watched. Users may use custom mappings to ensure correct watch status.

Community Custom Mappings

Community-maintained custom mappings are available in the LuceoEtzio/PlexAniBridge-Custom-Mappings repository.

Acknowledgements

• This project's code and structure were heavily inspired by work in the Kometa-Team/Anime-IDs repository.
• A huge thank you to LuceoEtzio for contributing the vast majority of the mapping edits and corrections.