Anime ID Mapping

Anime ID Mapping improves matching between AniList and providers that mainly use TMDb, TVDb, or IMDb IDs.

Overview

Anime services often use AniList, MAL, or AniDB IDs.

Media servers and general trackers usually use TMDb, TVDb, or IMDb IDs.

Without a shared identifier, the same anime can appear as two unrelated items.

CrossWatch uses the AniBridge mapping dataset to connect these ID systems.

CrossWatch downloads the dataset and builds a local SQLite index.

Lookups run locally during sync.

CrossWatch can use Anime ID Mapping for Watchlist and Ratings pairs that contain AniList.

When to use it

Enable Anime ID Mapping when an AniList watchlist or ratings pair syncs with:

Plex
Jellyfin
Emby
Trakt
SIMKL
MDBList
TMDb
PublicMetaDB

You usually do not need it for pairs that do not include an anime-specific provider.

For pair-level Watchlist and Ratings controls, see AniList pair options.

Enable Anime ID Mapping

Open the settings

Open Settings → Connections.

Expand Anime ID Mapping

Open the Anime ID Mapping panel.

Enable it

Turn on Enable.

Leave Auto update on unless you want manual control.

The setting saves immediately.

When you enable it for the first time, CrossWatch downloads the dataset and builds the local index.

That first activation can take longer than a normal settings change.

The setup is ready when the panel shows:

Dataset: Installed
Index: Ready
a green status indicator

The setting applies to future sync runs.

Status fields

Used for

This shows which provider pairs activate Anime ID Mapping.

The default is AniList pairs.

That means CrossWatch enables mapping when AniList appears on either side of a configured pair.

Auto update

Daily means automatic updates are on.

Manual means CrossWatch keeps the installed dataset and skips automatic checks.

The default interval is 24 hours.

Dataset

Installed means the AniBridge mapping file exists locally.

Missing means CrossWatch has no usable downloaded dataset.

Updating or Downloading means an update is running.

Error means the last update or download failed.

CrossWatch shows extra details below the status cards and in the logs.

Index

Ready means the SQLite lookup index was built successfully.

Missing means the dataset may exist, but the index is unavailable or incomplete.

Generated

This is the generation timestamp reported by AniBridge.

It is not the local install time.

Size

This shows the number of mapping sources and mapping edges.

A source is a known ID entry.

An edge is a relationship between two IDs.

CrossWatch builds lookup entries in both directions.

That is why edge counts are usually much larger.

How matching works

CrossWatch indexes items from both providers.
CrossWatch checks whether Anime ID Mapping should run.
CrossWatch queries the local index with known IDs.
CrossWatch adds any missing related IDs.
CrossWatch recalculates the canonical item key.
CrossWatch plans the sync with the enriched IDs.

Supported ID types are:

AniList
MAL
AniDB
TMDb
TVDb
IMDb

CrossWatch can follow mappings up to two levels deep.

Example:

AniList -> MAL -> TMDb

Existing IDs stay in place.

Anime ID Mapping enriches items.

It does not intentionally replace an ID already provided by the source.

Automatic updates

When Enable and Auto update are both on, CrossWatch runs a background update worker.

By default, it checks once every 24 hours.

It first downloads stats.json.

Then it compares the published dataset generation time with the installed version.

CrossWatch downloads the full mapping file only when:

no local dataset exists
no local index exists
AniBridge published a newer dataset

If the installed dataset is current, CrossWatch records the check and keeps the existing files.

Manual actions

Update now

Update now checks AniBridge for a newer dataset immediately.

When a newer dataset exists, CrossWatch:

downloads stats.json
downloads mappings.min.json
validates the JSON
replaces the existing mapping file
rebuilds the SQLite index
updates the status and counts

If the installed dataset is already current, CrossWatch does not download the full mapping file again.

Rebuild index

Rebuild index recreates the SQLite index from the installed mapping file.

Use it when:

Dataset shows Installed
Index shows Missing
the index file is damaged
an update completed but the index could not open
lookups stopped working after an interrupted shutdown

Rebuilding the index does not download a new dataset.

If the mapping file is missing, use Update now instead.

Behavior when no mapping exists

Anime ID Mapping is ID based.

It needs at least one supported ID to query the local index.

When an item has no usable ID, or the dataset has no relationship for it:

the original item stays unchanged
CrossWatch continues with normal matching
AniList can still use title and year fallback
the full sync does not stop because one item could not be mapped

The AniBridge dataset decides coverage.

Not every anime, edition, compilation, or regional variant has a complete ID set.

Troubleshooting

The main toggle is on, but the status is not green

The green indicator needs all of these:

mapping is enabled
dataset is installed
index is ready
no active error exists

Check Dataset and Index first.

Dataset shows Missing

Use Update now.

If the download fails, verify:

CrossWatch has outbound HTTPS access
GitHub is reachable from the container
the /config volume is writable
enough free disk space exists
the logs do not show an ANIME_MAPPING download error

Dataset shows Installed, but Index shows Missing

Use Rebuild index.

If rebuilding fails, verify that mappings.min.json is readable and the config directory is writable.

Update now finishes immediately

This usually means the installed dataset is already current.

CrossWatch checks the published generation timestamp before downloading the full mapping file.

Mapping was enabled after a sync finished

Run the pair again.

CrossWatch applies mapping while it builds provider indexes.

It does not rewrite a completed sync plan.

An item is still unmatched

Make sure the source item has at least one supported ID.

Anime ID Mapping does not search by title.

If no mapping exists, CrossWatch falls back to the destination provider behavior.

The dataset is outdated

Use Update now.

Or turn on Auto update.

The Generated date in the panel is the authoritative publication date from AniBridge.

Default configuration

{
  "anime_mapping": {
    "enabled": false,
    "auto_update": true,
    "provider": "anibridge",
    "release_tag": "v3",
    "refresh_hours": 24,
    "stale_after_days": 14,
    "use_for_pairs": [
      "anilist"
    ],
    "features": [
      "watchlist",
      "ratings"
    ]
  }
}

Config fields

`enabled`

Enables or disables Anime ID Mapping.

`auto_update`

Enables or disables the background update worker.

`provider`

Selects the mapping dataset provider.

The current UI uses anibridge.

`release_tag`

Selects the AniBridge release tag.

The current default is v3.

`refresh_hours`

Controls the minimum interval between automatic update checks.

The default is 24.

Values below one hour are internally clamped to one hour.

`stale_after_days`

Controls when CrossWatch marks the dataset as stale in the status UI.

The default is 14 days.

This does not disable the dataset.

`use_for_pairs`

Lists providers that activate mapping when present in a pair.

The default is:

[
  "anilist"
]

`features`

Lists sync features where pair index enrichment runs.

The default is:

[
  "watchlist",
  "ratings"
]

The current UI supports AniList watchlist and ratings syncing.

Treat manual expansion of these values as advanced configuration.

Local files

CrossWatch stores the mapping data in the config directory.

For a standard container install, the location is:

/config/.cw_cache/anime_mapping/anibridge/v3/

The directory contains:

stats.json
mappings.min.json
anime_mapping.sqlite
state.json

File roles

stats.json stores metadata about the published dataset.

mappings.min.json stores the downloaded AniBridge relationships.

anime_mapping.sqlite is the local lookup index.

state.json stores the last check time, last update time, index build time, and dataset generation timestamp.

Disabling Anime ID Mapping does not delete these files.

CrossWatch stops lookups and stops the automatic updater.

If you enable it again later, CrossWatch reuses the installed files.

Network and privacy

All mapping lookups run locally against the SQLite index.

CrossWatch only connects out to download public AniBridge release files.

Watchlist contents, account details, and sync payloads are not sent to AniBridge during lookup.

CrossWatch needs outbound HTTPS access to GitHub for first install and future updates.

Internal flow details

At sync start, CrossWatch builds provider indexes for both sides.

It reads IDs already attached to each item.

Example:

{
  "anilist": "16498",
  "mal": "16498",
  "tmdb": "1429",
  "tvdb": "267440",
  "imdb": "tt2560140"
}

Mapping runs only when all of these are true:

Anime ID Mapping is enabled
the sync feature is configured for mapping
at least one provider in the pair is listed in use_for_pairs
the local index is ready

The current UI can enable mapping for the watchlist and ratings features on pairs that include anilist.

After enrichment, CrossWatch recalculates the canonical item key.

That lets AniList and a second provider resolve to the same media item through mapped IDs.

When writing to AniList, CrossWatch prefers a direct AniList ID.

If no direct AniList ID exists, CrossWatch can resolve AniList through MAL.

Title and year matching stays available as the last fallback.

Mapping example

An AniList item may start with:

{
  "anilist": "16498",
  "mal": "16498"
}

CrossWatch may enrich it to:

{
  "anilist": "16498",
  "mal": "16498",
  "tmdb": "1429",
  "tvdb": "267440",
  "imdb": "tt2560140"
}

The exact result depends on the installed AniBridge dataset.

PreviousTMDb Metadata NextProfiles

Last updated 5 days ago

Was this helpful?