Skip to content

4. Integrations

Jump to bottom
DannyVFilms edited this page Jul 31, 2026 · 6 revisions

Integrations (Overview)

Integrations connect Floppy 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 Floppy.
  • 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. Floppy 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

  • Floppy 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 Floppy 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, Floppy 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 Floppy’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 Floppy.

Auto-logging

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

Troubleshooting

  • If IDs are missing in the payload, Floppy 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 (Floppy / Yamtrack format)

Use the Floppy CSV format (identical to Yamtrack's, so exports from either import cleanly) 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