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"
  ]
}

Local Custom Mappings

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

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.