Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Adapter: PublicMetaDB

PublicMetaDB adapter notes for syncing watchlist, history, ratings, and progress with TMDb-based matching.

PublicMetaDB adapter lets CrossWatch sync with PublicMetaDB. It supports watchlist, history, ratings, and progress.

Connect PublicMetaDB first. Use: PublicMetaDB (Authentication provider).

PublicMetaDB uses request pacing, retry/backoff, and hourly rating quotas.

Defaults and tuning: Provider rate limiting.

What it supports

  • Direction: source or target in a pair (one-way or two-way)

  • Features:

    • Watchlist (movies and shows)

    • History (movies and episodes)

    • Ratings (movies, shows, and episodes)

    • Progress (movies and episodes)

    • Playlists (not supported)

  • Rating scale: CrossWatch 1–10, converted to PublicMetaDB 0–100

  • Indexing: present-state snapshot (reads “what exists now”)

How matching works

PublicMetaDB works best with TMDb IDs.

CrossWatch uses TMDb IDs to tell PublicMetaDB exactly which item changed.

For writes, CrossWatch usually needs:

  • Movies: ids.tmdb

  • Episodes: show ids.tmdb plus season and episode

  • History: watched_at

  • Progress: current position plus total duration

If an item has no TMDb ID, PublicMetaDB sync often can’t write it.

If an episode is missing show TMDb ID or episode numbers, CrossWatch marks it unresolved.

Using PublicMetaDB in a pair

  1. Open Settings → Authentication and connect PublicMetaDB.

  2. Create or edit a pair.

  3. Choose PublicMetaDB as the source, destination, or both.

  4. Enable Watchlist, History, Ratings, or Progress.

  5. Optionally set a pair-level watchlist name.

  6. Save and run the pair.

Internal provider name: PUBLICMETADB.

Watchlist behavior

  • Supports movies and shows.

  • Supports source, destination, or two-way sync.

  • Uses a PublicMetaDB list as the destination container.

  • Default list name: Watchlist.

  • If the list does not exist, CrossWatch can create it automatically.

Created lists are private and marked as managed by CrossWatch.

Pair-level overrides can use a different list name for each pair.

Examples:

  • Movies to Watch

  • Family Watchlist

  • Anime Queue

PublicMetaDB watchlist does not support seasons or individual episodes.

History behavior

  • Supports movies and episodes.

  • Reads watched items from PublicMetaDB and can sync them elsewhere.

  • Writes watched movies and watched episodes into PublicMetaDB.

History is event-based.

The same movie or episode can appear more than once if it was watched multiple times.

CrossWatch keeps those events distinct by including watched_at in the internal key.

Ratings behavior

  • Supports movies, shows, and episodes.

  • Uses a CrossWatch 1–10 rating scale.

  • Converts ratings before sending them to PublicMetaDB.

Examples:

  • 8/10 → 80

  • 10/10 → 100

Default label: Overall.

Power users can change the default with publicmetadb.ratings_label.

Ratings are label-aware.

A rating for the same item with a different label is treated as a separate rating.

Progress behavior

  • Supports movies and episodes.

  • Syncs partial playback state such as resume position.

  • Requires current position and total duration.

PublicMetaDB needs both values to store progress.

If duration is missing, CrossWatch can’t send the progress entry.

If PublicMetaDB reports an item as completed or ignored after a progress update, CrossWatch removes the local resume reference from shadow state.

Related: Progress.

Settings and state (advanced)

Important config keys

Stored under publicmetadb.

Core settings:

  • api_key

  • base_url

  • timeout

  • max_retries

Watchlist:

  • watchlist_list_id

  • watchlist_name

  • watchlist_auto_create

  • watchlist_page_size

History and progress:

  • history_per_page

  • history_max_pages

  • progress_per_page

  • progress_max_pages

Ratings and pacing:

  • ratings_label

  • ratings_submit_per_hour

  • ratings_update_per_hour

  • rate_limit.get_per_sec

  • rate_limit.post_per_sec

Defaults:

  • base_url: https://publicmetadb.com

  • timeout: 15.0

  • max_retries: 3

  • ratings_label: Overall

  • rate_limit.get_per_sec: 20

  • rate_limit.post_per_sec: 3

  • ratings_submit_per_hour: 200

  • ratings_update_per_hour: 100

Rate control layers

PublicMetaDB uses three layers:

  • Request pacing for GET and non-GET calls

  • Retry and backoff for 429 and temporary 5xx errors

  • Pair-scoped hourly rating quotas

DELETE shares the same pacing bucket as POST.

For 429, CrossWatch honors Retry-After when PublicMetaDB sends it.

If a rating quota is reached, CrossWatch marks affected items unresolved and finishes the run.

Watchlist selection order

CrossWatch chooses the destination list in this order:

  1. Use publicmetadb.watchlist_list_id if set.

  2. Find a list matching watchlist_name.

  3. Use the first list with type watchlist.

  4. Fall back to common names like crosswatch or watchlist.

  5. Create a private list if auto-create is enabled.

Local shadow and quota files

Stored under /config/.cw_state/.

Typical files:

  • publicmetadb_watchlist.<pair-scope>.shadow.json

  • publicmetadb_history.<pair-scope>.shadow.json

  • publicmetadb_progress.<pair-scope>.shadow.json

  • publicmetadb_ratings.<pair-scope>.shadow.json

  • publicmetadb_ratings.<pair-scope>.quota.json

If no pair scope is available, CrossWatch uses unscoped.

Deletes usually need PublicMetaDB remote item IDs, not only TMDb IDs.

That makes the first sync or build-index pass important.

Common unresolved reasons

  • missing_tmdb_id — item has no TMDb ID

  • missing_show_tmdb_or_episode_numbers — episode is missing show TMDb ID, season, or episode

  • missing_watched_at — history item has no watched timestamp

  • missing_duration — progress item has no runtime or duration

  • missing_remote_item_id — missing remote ID for watchlist remove

  • missing_remote_history_id — missing remote ID for history remove

  • missing_remote_resume_id — missing remote ID for progress remove

  • missing_remote_rating_id — missing remote ID for rating remove

  • publicmetadb_hourly_rating_submit_limit — local rating submit quota reached

  • publicmetadb_hourly_rating_update_limit — local rating update quota reached

Notes and limitations

  • Watchlist sync does not support seasons or episodes.

  • History sync does not support whole-show watched state.

  • Progress sync does not support whole-show progress.

  • Ratings sync depends on local shadow state for stable remove behavior.

  • Reliable TMDb IDs are the main compatibility requirement.

Pair compatibility still depends on what the other provider supports.

Good pair examples:

  • Plex → PublicMetaDB history

  • PublicMetaDB → Plex watchlist

  • Jellyfin → PublicMetaDB progress

PreviousAdapter: MDBListNextAdapter: Plex

Last updated

Was this helpful?