> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/providers/metadata-id-mapping/anime-id-mapping.md).
# Anime ID Mapping
Anime ID Mapping improves matching between AniList and providers that mainly use TMDb, TVDb, or IMDb IDs.
Starting in `v0.9.22`, find it in **Settings → Connections → Metadata / ID Mapping**.
{% tabs %}
{% tab title="Standard" %}
### 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.
Anime ID Mapping is most useful when:
* AniList items do not match by title
* titles differ between English, Romaji, or native names
* a movie is misread as a series
* a provider supplies only TMDb, TVDb, or IMDb IDs
* two providers use different IDs for the same title
For pair-level **Watchlist** and **Ratings** controls, see [AniList pair options](/crosswatch/configure-pairs/anilist-pair-options.md).
### Enable Anime ID Mapping
{% stepper %}
{% step %}
### Open the settings
Open **Settings → Connections → Metadata / ID Mapping**.
{% endstep %}
{% step %}
### Expand Anime ID Mapping
Open the **Anime ID Mapping** panel.
{% endstep %}
{% step %}
### Enable it
Turn on **Enable**.
Leave **Auto update** on unless you want manual control.
{% endstep %}
{% endstepper %}
The setting saves immediately.
There is no separate save button.
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
1. CrossWatch indexes items from both providers.
2. CrossWatch checks whether Anime ID Mapping should run.
3. CrossWatch queries the local index with known IDs.
4. CrossWatch adds any missing related IDs.
5. CrossWatch recalculates the canonical item key.
6. 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.
#### Example
An AniList item may start with:
```json
{
"anilist": "16498",
"mal": "16498"
}
```
CrossWatch may enrich it to:
```json
{
"anilist": "16498",
"mal": "16498",
"tmdb": "1429",
"tvdb": "267440",
"imdb": "tt2560140"
}
```
The exact result depends on the installed AniBridge dataset.
### 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:
1. downloads `stats.json`
2. downloads `mappings.min.json`
3. validates the JSON
4. replaces the existing mapping file
5. rebuilds the SQLite index
6. 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.
{% endtab %}
{% tab title="Advanced" %}
### Default configuration
```json
{
"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:
```json
[
"anilist"
]
```
#### `features`
Lists sync features where pair index enrichment runs.
The default is:
```json
[
"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:
```json
{
"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.
{% endtab %}
{% endtabs %}
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://wiki.crosswatch.app/crosswatch/providers/metadata-id-mapping/anime-id-mapping.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.