Skip to content

4. Integrations

Jump to bottom
DannyVFilms edited this page Mar 17, 2026 · 6 revisions

Integrations (Overview)

Integrations connect Yamtrack to external services for imports, scrobbling (auto-logging), collection metadata, or automation. Each integration maps to specific media types and uses either pull-based imports (scheduled or manual) or push-based webhooks.

See Media Types for tracking behavior and provider mapping by type.

Account connections (imports / polling)

  • Plex: imports watch/listen history; optional webhook scrobbling; collection metadata extraction; watchlist sync.
  • Trakt: import movies + TV (public or OAuth for private).
  • Simkl: import movies + TV + anime (OAuth).
  • AniList: import anime + manga (public or OAuth for private).
  • Pocket Casts: import podcast history; scheduled every 2 hours.
  • Last.fm: poll recent music scrobbles on a schedule.
  • Steam: import games using Steam ID 64.
  • Audiobookshelf: import audiobook progress from a self-hosted Audiobookshelf server.

Webhooks (push events)

  • Plex: playback and rating events for TV/Movie/Music.
  • Jellyfin: playback events for TV/Movie.
  • Emby: playback events for TV/Movie.
  • Jellyseerr: request automation for TV/Movie status updates.

Import Overview

Imports are pull-based jobs that run in the background (Celery). Most support once or scheduled runs and a mode:

  • new: skip items already in your library.
  • overwrite: delete existing items for the matched media type/source and re-import.

Matching + dedupe

  • Imports match by provider IDs (TMDB, MAL, IGDB, etc.). Entries missing IDs are skipped.
  • Importers dedupe within a run and skip duplicates across runs. Some sources (Pocket Casts) perform extra merge steps for duplicate episodes.

Retries + SQLite locks

What imports affect

  • Imports create or update media items, statuses, and History entries.
  • They trigger calendar reloads and can schedule collection metadata updates (Plex).
  • Stats/history caches may refresh after imports (Last.fm polling explicitly refreshes Statistics).

See Celery and Background Tasks for worker/beat details.

Jump to providers

Plex

Media types

  • Movies (TMDB; see Movies), TV/Seasons/Episodes (TMDB; see TV Shows), Music (MusicBrainz; see Music).

Connect

  • Pin-based OAuth flow; stores a Plex token, account ID, and library sections.
  • Optional Plex username allowlist controls webhook processing.

Import

  • Pulls Plex watch/listen history and replays it into Yamtrack.
  • Supports once or scheduled runs and new/overwrite modes.
  • Can target a specific Plex library or all libraries.

Auto-logging (webhooks)

  • Supports media.play, media.scrobble, and media.rate events.
  • media.play marks items in progress; media.scrobble marks completed plays.
  • Ratings are updated when Plex sends media.rate (not always reliable).

Collection metadata

  • Collection metadata is fetched from Plex library items and stored on the item.
  • A separate “update_collection” mode can refresh collection metadata.
  • Rating key + Plex URI caching speeds up metadata refresh and avoids full library scans.

GUID parsing + rating key caching

  • Plex GUIDs can be incomplete or inconsistent. Yamtrack resolves TMDB IDs using TMDB/IMDB/TVDB IDs and title search fallbacks.
  • Cached rating keys allow future metadata updates without re-scanning Plex.

Watchlist sync

  • Yamtrack can poll your Plex Discover watchlist every 15 minutes and mirror it into your library.
  • Items on the watchlist are added as Planning status (Movies and TV via TMDB).
  • Items removed from the Plex watchlist are cleaned up in Yamtrack only if the item is still Planning and has not been modified (no score, progress, notes, or dates).
  • Enable watchlist sync in Settings → Integrations under Plex.

Troubleshooting

  • If items fail to match, check that Plex GUIDs include TMDB/IMDB/TVDB IDs.
  • If ratings don’t update, Plex may not emit media.rate; run an import to sync ratings.
  • Missing collection metadata usually means the item wasn’t matched or metadata fetch failed.

Pocket Casts

Media types

  • Podcasts (Show -> Episode; see Podcasts).

Connect

  • Email/password login; stores access + refresh tokens.

Import pipeline

  • Runs an initial import on connect, then scheduled imports every 2 hours.
  • Always uses new mode (no overwrite), and merges duplicate episodes.

RSS fallback

  • If a show lacks a feed URL, Yamtrack tries iTunes to discover the RSS feed.
  • RSS episodes are synced to fill in missing metadata and episode lists.

Common failure modes

  • OAuth logins (Apple/Google) require setting a password first.
  • If the connection is marked broken, reconnect to refresh tokens.
  • Missing episode metadata often resolves after RSS sync.

Last.fm

Media types

  • Music (scrobbles -> track plays; see Music).

Connect

  • Username-only connection; requires public scrobbles.

Polling vs scrobbling

  • Uses scheduled polling (default every 15 minutes) to fetch recent tracks.
  • All Last.fm scrobbles are treated as completed plays.

History + stats

  • Scrobbles create track-level history entries that roll up to albums/artists.
  • Statistics cache is refreshed after polling.

Troubleshooting

  • Rate limits can delay imports; try again later.
  • Private profiles or invalid usernames will not connect.

Jellyseerr

Media types

Webhook setup

  • Configure Jellyseerr to POST a JSON payload to Yamtrack’s webhook URL.
  • Payload keys: media_type, media_tmdbid, media_status, requestedBy_username.

Automation behavior

  • Creates the item if missing and sets status (Planning or In Progress).
  • Triggered statuses and allowed requesters are configurable per user.
  • Does not log history plays; it only adds or updates items.

Jellyfin

Media types

  • Movies and TV (via TMDB/IMDB/TVDB IDs in webhook payloads; see Movies and TV Shows).

Webhook setup

  • Configure Jellyfin webhook to send Play/Stop events to Yamtrack.

Auto-logging

  • Marks items watched when Jellyfin reports UserData.Played.
  • No bulk import; webhook events only.

Troubleshooting

  • If IDs are missing in the payload, Yamtrack can’t match items.

Emby

Media types

  • Movies and TV (via TMDB/IMDB/TVDB IDs in webhook payloads; see Movies and TV Shows).

Webhook setup

  • Configure Emby webhook to send playback.start/playback.stop events.

Auto-logging

  • Marks items watched when PlaybackInfo.PlayedToCompletion is true.
  • No bulk import; webhook events only.

Troubleshooting

  • Ensure Emby sends provider IDs (TMDB/IMDB/TVDB) for matching.

Trakt

Media types

  • Movies and TV (including seasons/episodes; see Movies and TV Shows).

Public profile import

  • Enter a public Trakt username to import watch history and statuses.

Private profile import (OAuth)

  • OAuth is required to access private history.

Notes

  • Imports can be run once or scheduled.
  • Uses TMDB IDs to match movies and shows.
  • Watchlist entries are imported as Planning status in the standard Trakt import.
  • Trakt lists and watchlist can also be imported into Custom Lists from the Lists page (separate Trakt OAuth + client ID/secret).

Simkl

Media types

Configuration

  • OAuth connection required (SIMKL ID + secret).

Notes

  • Imports can be run once or scheduled.
  • Movies/TV map to TMDB; anime maps to MAL IDs.

AniList

Media types

Public import

  • Enter a public AniList username to import lists and history.

Private import (OAuth)

  • OAuth is required to access private lists.

Notes

  • Imports can be run once or scheduled.

Steam

Media types

Configuration

  • Requires a Steam API key and Steam ID 64.

Import requirements

  • Your Steam profile must be public.

Notes

  • Imports can be run once or scheduled.

Audiobookshelf

Media types

  • Books (source audiobookshelf; see Books).

Connect

  • Enter your Audiobookshelf server URL and API token in Settings → Integrations.
  • Credentials are stored per user in the database; no global environment variable is required.

Import

  • Syncs audiobook progress, completion status, and metadata from your Audiobookshelf library.
  • Only entries changed since the last sync are processed (change detection via timestamp).
  • Imported items are tagged format=audiobook to distinguish them from other book sources.
  • When Audiobookshelf metadata is incomplete, the importer enriches it using Hardcover or OpenLibrary ISBN lookups.

Notes

  • Imports can be run once or scheduled.
  • If metadata is missing after import, the importer falls back to Hardcover/OpenLibrary; re-running the import after Audiobookshelf syncs new metadata will fill in gaps.

CSV Import (Yamtrack format)

Use the Yamtrack CSV format for bulk migrations or offline exports. CSV imports are pull-based jobs and use the same new/overwrite modes as other importers.

For the full format specification and field list, see:

Clone this wiki locally