Custom Mappings

AniBridge allows you to define mappings to supplement the upstream mappings database. This feature is particularly helpful for correcting entries that are missing or incorrectly mapped in the default database.

Note

Custom mappings merge with the upstream mappings, they do not override them. This means that if you add a custom mapping for a series that is already in the upstream 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 anibridge-mappings database as reference.

mappings.yaml

# yaml-language-server: $schema=https://raw.githubusercontent.com/anibridge/anibridge-mappings/refs/heads/main/mappings.schema.json

$meta:
  schema_version: 3.0.0
  description: Example mappings illustrating AniBridge v3 format

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

anidb:99999:R:
  anilist:99999:
    "1-12": "1-12"
  mal:99999:
    "1-12": "1-12"
  tmdb_show:99999:s1:
    "1-6": "1-6"
    "7-12": "7-12"
  tvdb_show:99999:s1:
    "1-12": "1-12"

tvdb_show:88888:s0:
  anidb:88888:S:
    "1": "1,3"
    "2": "2,4"
  tmdb_show:88800:s0:
    "1": "1"

Including Other Mapping Files

You can include other mapping files (local or remote) using the $includes key. This allows you to modularize your custom mappings or leverage community-maintained mapping files.

mappings.yaml

$includes:
  - "https://example.com/mappings.json"
  - "/path/to/mappings.yaml"
  - "./relative/path/to/mappings.yml"

JSON Format for Mappings

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

mappings.json

{
  "$schema": "https://raw.githubusercontent.com/anibridge/anibridge-mappings/refs/heads/main/mappings.schema.json",
  "$meta": {
    "schema_version": "3.0.0",
    "description": "Example mappings illustrating AniBridge v3 format"
  },
  "$includes": [
    "https://url.to/another/mappings.yaml",
    "/path/to/another/mappings.json",
    "./relative/path/to/another/mappings.json.zst"
  ],
  "anidb:99999:R": {
    "anilist:99999": {
      "1-12": "1-12"
    },
    "mal:99999": {
      "1-12": "1-12"
    },
    "tmdb_show:99999:s1": {
      "1-6": "1-6",
      "7-12": "7-12"
    },
    "tvdb_show:99999:s1": {
      "1-12": "1-12"
    }
  },
  "tvdb_show:88888:s0": {
    "anidb:88888:S": {
      "1": "1,3",
      "2": "2,4"
    },
    "tmdb_show:88800:s0": {
      "1": "1"
    }
  }
}

Zstandard compression

AniBridge supports loading custom mappings from Zstandard compressed files with the .zst extension. This is useful for reducing file size when dealing with large mapping files.

Local Custom Mappings

AniBridge will look for a custom mappings file with the name mappings.(json|yaml|yml)(.zst)? in the $AB_DATA_PATH directory (defaults to ./data). The file extension determines the format of the file (YAML or JSON).

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.

LuceoEtzio/AniBridge-Custom-Mappings

Default Mappings

If you want to contribute your custom mappings to the community, you can submit a pull request to the anibridge-mappings repository. Your pull request should modify the mappings.edits.yaml file.