Skip to content

Custom Mappings

PlexAniBridge allows you to define custom mappings for Plex content to AniList, supplementing the default mappings database. This feature is particularly helpful for content that is missing or incorrectly mapped in the default database.

Note

Custom mappings merge with the default mappings, they do not override them. This means that if you add a custom mapping for a series that is already in the default database, only the fields specified in the custom mapping will be updated. The remaining pre-existing fields will remain unchanged.

Below is an example mappings file. You can use the JSON schema or the PlexAniBridge-Mappings database as reference.

mappings.custom.json
{
  "$schema": "https://raw.githubusercontent.com/eliasbenb/PlexAniBridge-Mappings/v2/mappings.schema.json",
  "$includes": [
    "/path/to/another/mappings.json",
    "https://url.to/another/mappings.json"
  ],
  "99999": {
    "anidb_id": 9999,
    "imdb_id": "tt9999999",
    "mal_id": 9999,
    "tmdb_show_id": 9999,
    "tvdb_id": 9999,
    "tvdb_mappings": {
      "s0": "e1",
      "s1": "e1-e13"
    }
  },
  "99998": {
    "anidb_id": 9998,
    "imdb_id": "tt9999998",
    "mal_id": 9998,
    "tmdb_movie_id": 9998
  }
}
YAML Format for Mappings

The mappings file can also be written in YAML format. Here is the same example in YAML:

mappings.custom.yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/eliasbenb/PlexAniBridge-Mappings/v2/mappings.schema.json

"$includes":
  - "/path/to/another/mappings.json"
  - "https://url.to/another/mappings.json"

"99999":
  anidb_id: 9999
  imdb_id: "tt9999999"
  mal_id: 9999
  tmdb_show_id: 9999
  tvdb_id: 9999
  tvdb_mappings:
    s0: "e1"
    s1: "e1-e13"

"99998":
  anidb_id: 9998
  imdb_id: "tt9999998"
  mal_id: 9998
  tmdb_movie_id: 9998

Including External Mappings

To include external mappings within a mappings file, you can use the $includes key. This key should contain an array of paths or HTTP URLs to other mappings files. The included mappings will be merged with the current mappings file in the order they are specified.

mappings.custom.json
{
  "$includes": [
    "https://example.com/mappings.json",
    "/path/to/mappings.json",
    "./relative/path/to/mappings.json"
  ]
}

Mapping File Formats

JSON or YAML can be used as the format for the custom mappings file. The file extension determines the format of the file (.json, .yaml, or .yml).

Local Custom Mappings

PlexAniBridge will look for a custom mappings file with the name mappings.custom.(json|yaml|yml) in the DATA_PATH directory. The file extension determines the format of the file (JSON or YAMLL).

Community Custom Mappings

There are community maintained mappings repositories that you can use to get pre-made mappings for your content. You can include these mappings in your custom mappings file using the $includes key as explained above.

Default Mappings

If you want to contribute your custom mappings to the community, you can submit a pull request to the PlexAniBridge-Mappings repository. Your pull request should modify the mappings.edits.json and not the mappings.json file.

To browse the existing mappings with a web UI, you can use the PlexAniBridge-Mappings Query Builder.