README.md

April 19, 2026 ยท View on GitHub

CURATORR

SMART PLAYLIST CURATOR

Latest release Discord License AGPL-3.0 Docker Hub

Support me on Ko-fi Buy Me a Coffee

Curatorr is a self-hosted Plex, Jellyfin, and Emby companion for playback tracking, smart playlist generation, artist discovery, and optional Lidarr automation.

Preview

Curatorr dashboard overview

What It Does

  • Tracks playback from Plex, Jellyfin, or Emby
  • Builds per-user smart playlists from real listening behavior
  • Supports personal playlists, blended playlists, Curatorr rotating playlists, and configurable Daily Mix
  • Adds feature-driven playlist building with BPM, key, Camelot, energy, and danceability filters when analysis data is available
  • Surfaces library-based suggestions and external discovery
  • Integrates with Lidarr for optional add, queue, and progression workflows
  • Supports Last.fm history/station features and ListenBrainz playlist suggestions on supported server paths

Media Server Support

  • Plex: broadest feature set, including Plex SSO, Plex Home users, native Plex webhooks, optional Tautulli support, Daily Mix, Last.fm station playlists, and ListenBrainz playlist suggestions
  • Jellyfin: native server login, library indexing, live playback tracking, smart playlists, personal playlists, blended playlists, discovery, and Lidarr automation
  • Emby: native server login, library indexing, live playback tracking, smart playlists, personal playlists, blended playlists, discovery, and Lidarr automation

Current Plex-only features:

  • Tautulli integration
  • Daily Mix sync
  • Last.fm station playlists
  • ListenBrainz playlist suggestion sync
  • Sonic ordering and loudness-aware sequencing

Quick Start

Minimal Docker Compose example:

services:
  curatorr:
    image: mickygx/curatorr:latest
    container_name: curatorr
    ports:
      - "7676:7676"
    environment:
      - CONFIG_PATH=/app/config/config.json
      - DATA_DIR=/app/data
      - BASE_URL=http://localhost:7676
      - TRUST_PROXY=true
      - TRUST_PROXY_HOPS=1
      - SESSION_SECRET=replace-this-with-a-random-secret
      - WEBHOOK_SECRET=replace-this-with-a-random-secret
    volumes:
      - ./config:/app/config
      - ./data:/app/data
      - ./data/icons/custom:/app/public/icons/custom
    network_mode: bridge
    restart: unless-stopped

Generate SESSION_SECRET and WEBHOOK_SECRET with:

openssl rand -hex 32

Start Curatorr with:

docker compose up -d

Then open http://localhost:7676/wizard and complete the setup wizard for Plex, Jellyfin, or Emby.

Optional Features

Curatorr supports an optional analyzer sidecar for BPM, musical key, Camelot key, energy, and danceability enrichment. For setup and workflow details, see Track Analysis.

Spotify support is optional and user-specific. Users can connect Spotify accounts to browse and import playlists after app-level credentials are configured on the Curatorr container. Owned Spotify playlists imported through the connected-account flow are the most reliable option, especially for larger playlists. Shared or public Spotify playlist URLs imported through the URL tab depend on whatever Spotify exposes on its public web pages, so some playlists may only preview or import part of the track list. If a shared/public playlist is incomplete, copy its tracks into a new playlist you own in Spotify and import that owned copy from the Spotify tab instead. For setup details, see Spotify in Integrations.

YouTube playlist URL import is optional and server-level. Public YouTube playlists can be previewed and imported when YOUTUBE_API_KEY is configured on the Curatorr container. For setup details, see Integrations.

Documentation

For installation, setup, configuration, and troubleshooting:

Support