Skip to main content

Trakt

Create and sync Plex collections from any public Trakt list. Paste a URL, pick a library, and homescreen-hero handles the rest - matching items to your Plex library, creating the collection, and keeping it in sync.

Setup​

  1. Create a Trakt API application at trakt.tv/oauth/applications
  2. Copy your Client ID
  3. Add it to your .env file:
HSH_TRAKT_CLIENT_ID=your-client-id
  1. If you didn't enable Trakt in the Setup Wizard, simply enable it on the Integrations page (or directly in config.yaml):
trakt:
  enabled: true

Adding a List​

  1. Go to the Integrations page in the dashboard
  2. Click Add Source under Trakt
  3. Enter a name for the collection (this becomes the Plex collection name)
  4. Paste the Trakt list URL (e.g., https://trakt.tv/users/username/lists/list-name)
  5. Select which Plex library to sync to
  6. Click Save, then hit Sync to pull in the list

How Syncing Works​

When you sync a Trakt list, homescreen-hero:

  1. Fetches all items from the Trakt list via the API
  2. Matches each item to your Plex library using a multi-step approach:
    • First tries matching by TMDb ID (most reliable)
    • Falls back to IMDb ID
    • Last resort: title + year search
  3. Creates or updates the Plex collection with all matched items
  4. Removes stale items - if something is removed from the Trakt list, it gets removed from the collection on the next sync
  5. Tracks missing items - any items on the Trakt list that aren't in your Plex library are logged and viewable from the dashboard
note

Syncing is non-destructive on errors. If the Trakt API returns no items (e.g., due to an outage), homescreen-hero won't wipe your existing collection.

Missing Items​

After a sync, you can view which items from the Trakt list weren't found in your Plex library. This is useful for identifying gaps in your library. Each missing item includes its Trakt, TMDb, and IMDb IDs for easy lookup.

Automatic requesting of missing items via Radarr/Sonarr is planned for a future release.