PlexMix syncs your Plex music library to a local SQLite database, generates semantic embeddings for tracks, and uses AI to create personalized playlists based on mood descriptions.

Features

• ✨ Simple Setup - Only requires a Google API key to get started
• 🎵 Smart Sync - Syncs Plex music library with incremental updates and pre-flight token validation
• 🤖 AI-Powered - Uses Google Gemini, OpenAI GPT, Anthropic Claude, Cohere Command, or fully local Gemma/Mistral models
• 🔌 Bring-Your-Own LLM - Point PlexMix at any OpenAI-compatible local endpoint (Ollama, LM Studio, llama.cpp) with auto-discovery and SSE streaming
• 🏷️ AI Tagging - Automatically generates tags, environments, and instruments with stale tag detection and re-tagging
• 🎵 Audio Analysis - Extract tempo, key, energy, danceability via Essentia DSP (optional)
• 🎸 MusicBrainz Enrichment - Community-curated genres, canonical artist IDs, and recording type detection (optional)
• 🔍 Semantic Search - FAISS vector similarity search with incremental index updates
• 🎨 Mood-Based - Generate playlists from natural language descriptions
• 🔀 Smart Ordering - 4 track ordering modes: similarity, random, alternating artists, and energy curve
• 📋 Templates - Save and reuse playlist generation configs with 5 built-in presets
• ⚡ Fast - Local database with optimized indexes, full-text search, and versioned migrations
• 🎯 Flexible - Filter by genre, year, rating, artist, environment, instrument, tempo, energy, key, and danceability
• 📦 Export/Import - Export playlists as JSON or M3U; import from files with track matching
• ⌨️ Keyboard Shortcuts - Vim-style navigation (g+key), / to search, Esc to blur
• 🐳 Docker Ready - Deploy with Docker Compose for containerized setups
• 🛡️ Resilient - Automatic database recovery if deleted or corrupted

Quick Start

Option 1: Command Line Interface (Recommended)

# Install from PyPI
pip install plexmix

# Run setup wizard
plexmix config init

# Sync your Plex library (incremental, generates embeddings automatically)
plexmix sync

# Generate AI tags for tracks (enhances search quality)
plexmix tags generate

# Create a playlist
plexmix create "upbeat morning energy"

# With filters
plexmix create "chill evening vibes" --genre jazz --year-min 2010 --limit 30

# Filter by environment and instrument
plexmix create "focus music" --environment study --instrument piano

# Filter by audio features (requires audio analysis)
plexmix create "dance party" --tempo-min 120 --energy high --danceable 0.7

# Smart ordering modes
plexmix create "workout mix" --shuffle energy_curve
plexmix create "variety hour" --shuffle alternating_artists

# Avoid tracks from recent playlists
plexmix create "fresh picks" --avoid-recent 5

# Use alternative AI provider
plexmix create "workout motivation" --provider openai

# Retag tracks older than 30 days
plexmix tags generate --retag-stale 30

# Export/import playlists
plexmix playlist list
plexmix playlist export 1 --format json
plexmix playlist import my_playlist.json

# If you encounter issues (e.g., "0 candidate tracks")
plexmix doctor

# Regenerate all tags and embeddings from scratch (WARNING: destructive)
plexmix sync regenerate

Option 2: Docker

Pre-built multi-platform images (amd64 + arm64) are published to GHCR on every release in two variants:

# Pull the slim image (recommended for most users)
docker pull ghcr.io/izzoa/plexmix:latest

# Or pull the local/offline image (includes sentence-transformers + PyTorch)
docker pull ghcr.io/izzoa/plexmix:latest-local

# Run with Docker Compose (clone the repo for docker-compose.yml)
git clone https://github.com/izzoa/plexmix.git
cd plexmix
cp .env.example .env
# Edit .env with your PLEX_TOKEN, GOOGLE_API_KEY, etc.
docker compose up -d

# Access the web UI at http://localhost:3000

# Run CLI commands via Docker
docker compose run plexmix sync
docker compose run plexmix create "chill evening vibes"

Option 3: Web User Interface (Alpha)

Note: The Web UI is currently in Alpha status. The CLI is the recommended way to interact with PlexMix for production use.

# Install with UI extras
pip install "plexmix[ui]"

# Or if using poetry
poetry install -E ui

# Launch the web UI
plexmix ui

# Optional: Specify host and port
plexmix ui --host 0.0.0.0 --port 8000

Then open your browser to http://localhost:3000

Password Protection: Set PLEXMIX_UI_PASSWORD to require a password before accessing the UI. This is recommended when binding to 0.0.0.0 or exposing the UI on a network.

PLEXMIX_UI_PASSWORD=mysecret plexmix ui --host 0.0.0.0

Screenshots

Web UI Features

The web interface is built around a slim glass icon rail and a ⌘K command palette:

• 📊 Dashboard - Library stats, configuration status, quick actions, and recent playlists at a glance
• 🎵 Playlist Generator - The showpiece: describe a vibe and watch an animated AI-thinking pipeline (embed → vector search → diversity → order) curate a playlist, then reorder/save the result (4 ordering modes, advanced audio filters, cancellable)
• 📚 Library Manager - Browse, search, filter by tag/genre/audio, sync with live progress, bulk tag/delete operations
• 🏷️ AI Tagging - Batch generate tags with stale tag detection, retag support, and inline tag editing
• 📜 Playlist History - Album-mosaic cards; view, rerun, export (JSON/M3U/Plex), and import playlists
• 🩺 Doctor - Database health checks with one-click fixes
• ⚙️ Settings - Configure Plex, AI providers, and embeddings (with model auto-discovery), plus theme / density / accent under Appearance

Key UI Features

• 🧭 Glass icon rail + ⌘K command palette - A slim navigation rail with hover tooltips and g+key hints, plus a command palette (⌘K or /) to jump to any page, run an action, or fire a quick vibe
• 🎬 Generator showpiece - An animated "AI-thinking" pipeline with a live particle vector-field, a four-phase tracker bound to the real generation pipeline, and a streaming terminal log
• 🌓 Light-first theme + appearance controls - Light by default with a dark toggle (auto logo switching), plus Density (comfortable/compact) and Accent-intensity (subtle/balanced/vivid) preferences in Settings → Appearance
• ⌨️ Keyboard-driven - Vim-style g+key navigation, ⌘K / / to open the palette, ↑↓ + Enter to pick a command, Esc to close
• Real-time Progress - Live updates for sync, tagging, and generation operations
• Resilient UX - Form validation, empty/loading states, and user-friendly error messages with recovery options

Installation

From PyPI (Recommended)

pip install plexmix

From Source

git clone https://github.com/izzoa/plexmix.git
cd plexmix
poetry install

With Local Embeddings / Local LLM (Optional)

# Install sentence-transformers + PyTorch for offline embeddings and local LLM
pip install "plexmix[local]"

# Or with Poetry
poetry install -E local

With Audio Analysis (Optional)

# Install with Essentia for audio feature extraction
pip install "plexmix[audio]"

# Or with Poetry
poetry install -E audio

Multiple Extras

Combine any extras in a single install:

# Install with UI + audio + local LLM support
pip install "plexmix[ui,audio,local]"

# Or with Poetry
poetry install -E ui -E audio -E local

With Docker

# Pre-built image from GHCR
docker pull ghcr.io/izzoa/plexmix:latest

# Or build locally
git clone https://github.com/izzoa/plexmix.git
cd plexmix
docker compose up -d

Configuration

PlexMix uses Google Gemini by default for both AI playlist generation and embeddings, requiring only a single API key! Credentials can be stored in the system keyring or passed as environment variables.

Required

• Plex Server: URL and authentication token
• Google API Key (or Gemini API Key): For Gemini AI and embeddings (Get one here)

Optional Alternative Providers

• OpenAI API Key: For GPT models and text-embedding-3-small
• Anthropic API Key: For Claude models (AI only, no embeddings)
• Cohere API Key: For Command R7B and Embed v4 models
• Local Embeddings: sentence-transformers (free, offline, no API key needed)
• Local LLM: Run Gemma 3 1B/4B, Liquid LFM 1.2B, Yarn-Mistral 7B-128K, or hook into an Ollama/LM Studio endpoint

Getting a Plex Token

1. Open Plex Web App
2. Play any media item
3. Click the three dots (...) → Get Info
4. View XML
5. Copy the X-Plex-Token from the URL

Usage

Configuration Commands

# Interactive setup wizard
plexmix config init

# Test Plex server connection
plexmix config test

# Show current configuration
plexmix config show

Troubleshooting Connection Issues:

If you get a "400 Bad Request" error when connecting to Plex:

1. Check your Plex token - Make sure there are no extra spaces when copying
2. Try HTTPS - Use https:// instead of http:// if your server requires secure connections
3. Verify the URL - Ensure the server address and port (default: 32400) are correct
4. Check server settings - In Plex Server settings, look for network/authentication requirements
5. Test the connection - Run plexmix config test to diagnose the issue

Common Plex Server URLs:

• Local: http://localhost:32400
• Remote: http://192.168.1.X:32400 (replace X with your server's IP)
• Secure: https://your-server:32400

Sync Commands

PlexMix offers three sync modes:

# Incremental sync (default) - Only syncs new/changed/deleted tracks
plexmix sync

# Same as above, but explicit
plexmix sync incremental

# Sync with audio feature analysis (requires essentia)
plexmix sync --audio

# Sync with MusicBrainz metadata enrichment
plexmix sync --musicbrainz

# Regenerate everything from scratch (WARNING: Deletes ALL tags and embeddings)
plexmix sync regenerate

# Legacy alias for incremental sync
plexmix sync full

# Sync without embeddings (faster, but you'll need to generate them later)
plexmix sync --no-embeddings

Sync Mode Comparison:

When to use each:

• plexmix sync → Default for daily use, adding new music
• plexmix sync regenerate → When you want to completely regenerate all AI data (tags, embeddings)

Database Health Check

# Diagnose and fix database issues
plexmix doctor

# Force regenerate all tags and embeddings (DEPRECATED: use 'plexmix sync regenerate' instead)
plexmix doctor --force

What does plexmix doctor do?

• Detects orphaned embeddings (embeddings that reference deleted tracks)
• Shows database health status (track count, embeddings, orphans)
• Interactively removes orphaned data
• Regenerates missing embeddings
• Rebuilds vector index

When to use:

• After "No tracks found matching criteria" errors
• When playlist generation finds 0 candidates
• After database corruption or manual track deletion
• Periodic maintenance to keep database healthy

Note: For complete regeneration of all tags and embeddings, use plexmix sync regenerate instead of doctor --force

Database Management

# Show database information and statistics
plexmix db info

# Reset database and embeddings (with automatic backup)
plexmix db reset

# Reset without backup (not recommended)
plexmix db reset --no-backup

# Skip confirmation prompt
plexmix db reset --force

What gets deleted:

• SQLite database (~/.plexmix/plexmix.db)
• FAISS embeddings index (~/.plexmix/embeddings.index)
• All synced music metadata
• User-applied tags (moods, environments, instruments)
• Playlist history
• AI-generated embeddings

What gets preserved:

• Your music files on Plex server (unchanged)
• Plex server metadata (unchanged)
• PlexMix configuration (.env, config.yaml)
• API keys

When to use:

• Complete fresh start
• Switching embedding providers
• Database corruption that doctor can't fix
• Testing or development

After reset:

1. Run plexmix sync to re-sync your library
2. (Optional) Run plexmix tags generate to re-tag tracks

By default, a timestamped backup is created in ~/.plexmix/backups/ before deletion.

Database Command Reference:

Tag Generation

# Generate AI tags for all untagged tracks
plexmix tags generate

# Also retag tracks whose tags are older than 30 days
plexmix tags generate --retag-stale 30

# Use alternative AI provider
plexmix tags generate --provider openai

# Use the offline/local provider
plexmix tags generate --provider local

# Skip embedding regeneration (faster, but tags won't be in search)
plexmix tags generate --no-regenerate-embeddings

Embedding Generation

# Generate embeddings for tracks without them
plexmix embeddings generate

# Regenerate all embeddings from scratch
plexmix embeddings generate --regenerate

What are tags? AI-generated metadata (per track) that enhances semantic search:

• Tags (3-5): Mood descriptors like energetic, melancholic, upbeat, chill, intense
• Environments (1-3): Best-fit contexts like work, study, focus, relax, party, workout, sleep, driving, social
• Instruments (1-3): Most prominent instruments like piano, guitar, saxophone, drums, bass, synth, vocals, strings

All metadata is automatically included in embeddings for more accurate mood-based playlist generation.

Audio Feature Analysis (Optional)

PlexMix can extract DSP-level audio features from your tracks using Essentia. This enriches embeddings and enables audio-aware playlist filters.

# Install with audio support
pip install "plexmix[audio]"

# Analyze all tracks that don't have audio features yet
plexmix audio analyze

# Re-analyze all tracks (overwrites existing features)
plexmix audio analyze --force

# Show audio analysis statistics
plexmix audio info

# Analyze during sync
plexmix sync --audio

Extracted features:

• Tempo (BPM) with confidence score
• Key & Scale (e.g., C major, A minor)
• Energy Level (low / medium / high)
• Danceability (0.0 - 1.0)
• Loudness (dB)
• Spectral Centroid and Zero Crossing Rate
• MFCCs (13-coefficient timbral fingerprint)

Audio features are automatically incorporated into embeddings for richer semantic search and can be used as playlist filters (see below).

Playlist Generation

# Basic playlist (prompts for track count)
plexmix create "happy upbeat summer vibes"

# Specify track count
plexmix create "rainy day melancholy" --limit 25

# Filter by genre
plexmix create "energetic workout" --genre rock --limit 40

# Filter by year range
plexmix create "90s nostalgia" --year-min 1990 --year-max 1999

# Filter by environment (work, study, focus, relax, party, workout, sleep, driving, social)
plexmix create "workout energy" --environment workout

# Filter by instrument (piano, guitar, saxophone, drums, etc.)
plexmix create "piano jazz" --instrument piano

# Use specific AI provider
plexmix create "chill study session" --provider claude

# Force the offline/local provider
plexmix create "ambient focus" --provider local

# Filter by audio features (requires audio analysis)
plexmix create "high energy dance" --tempo-min 120 --tempo-max 140
plexmix create "chill lounge" --energy low
plexmix create "piano ballads in C major" --key C --instrument piano
plexmix create "dance floor bangers" --danceable 0.7

# Custom playlist name
plexmix create "morning coffee" --name "Perfect Morning Mix"

# Track ordering modes
plexmix create "workout" --shuffle energy_curve       # Arc-shaped energy progression
plexmix create "party" --shuffle alternating_artists   # Maximize artist diversity
plexmix create "random mix" --shuffle random           # Fully random order

# Avoid tracks from recent playlists
plexmix create "fresh discoveries" --avoid-recent 10

# Adjust candidate pool multiplier (default: 25x playlist length)
plexmix create "diverse mix" --limit 20 --pool-multiplier 50

# Don't create in Plex (save locally only)
plexmix create "test playlist" --no-create-in-plex

Playlist Management

# List all saved playlists
plexmix playlist list

# Export a playlist to JSON
plexmix playlist export 1 --format json --output my_playlist.json

# Export to M3U format
plexmix playlist export 1 --format m3u

# Import a playlist from file
plexmix playlist import my_playlist.json

Architecture

PlexMix uses a multi-stage pipeline for intelligent playlist generation:

1. AI Tagging (One-time setup) → Tracks receive:

   • 3-5 descriptive tags (mood, energy, tempo, emotion)
   • 1-3 environments (work, study, focus, relax, party, workout, sleep, driving, social)
   • 1-3 instruments (piano, guitar, saxophone, drums, bass, synth, vocals, strings, etc.)

2. Audio Analysis (Optional) → Tracks receive DSP features:

   • Tempo (BPM), key, scale, energy level, danceability, loudness, spectral features, MFCCs

3. Playlist Generation Pipeline:

   • SQL Filters → Apply optional filters (genre, year, rating, artist, environment, instrument, tempo, energy, key, danceability)
   • Candidate Pool → Search using FAISS vector similarity (default: 25x playlist length)
   • Diversity Selection → Apply algorithmic diversity rules:
     • Max 3 tracks per artist
     • Max 2 tracks per album
     • No duplicate track/artist combinations
   • Track Ordering → Apply selected ordering mode:
     • similarity (default): Closest semantic match first
     • random: Fully randomized order
     • alternating_artists: Round-robin artist interleaving for maximum variety
     • energy_curve: Arc-shaped energy progression using audio features
   • Final Playlist → Return curated, diverse track list

Technology Stack

• Language: Python 3.10+
• CLI: Typer with Rich console output
• Database: SQLite with FTS5 full-text search
• Vector Search: FAISS (CPU) with cosine similarity
• AI Providers: Google Gemini (default), OpenAI GPT, Anthropic Claude, Cohere, Local Gemma/Yarn presets or any OpenAI-compatible endpoint
• Embeddings: Google Gemini (3072d), OpenAI (1536d), Cohere (1024d), Local (384-768d)
• Audio Analysis: Essentia (optional) for DSP feature extraction
• Plex Integration: PlexAPI
• Deployment: Docker & Docker Compose support

Project Structure

plexmix/
├── src/plexmix/
│   ├── ai/               # AI provider implementations
│   │   ├── base.py       # Abstract base class
│   │   ├── gemini_provider.py
│   │   ├── openai_provider.py
│   │   ├── claude_provider.py
│   │   ├── cohere_provider.py
│   │   ├── local_provider.py   # Managed Hugging Face + custom endpoint (SSE streaming)
│   │   └── tag_generator.py    # AI-based tag generation
│   ├── audio/            # Audio feature analysis (optional)
│   │   └── analyzer.py   # Essentia-based DSP feature extraction
│   ├── cli/              # Command-line interface (modular)
│   │   ├── main.py       # Typer CLI app (entrypoint)
│   │   ├── create_cmd.py # Playlist creation with shuffle/avoid-recent
│   │   ├── tags_cmd.py   # Tag generation with --retag-stale
│   │   ├── playlist_cmd.py # Playlist export/import/list
│   │   └── ...           # sync, config, db, doctor, embeddings, audio, ui
│   ├── config/           # Configuration management
│   │   ├── settings.py   # Pydantic settings
│   │   └── credentials.py # Keyring + env var credential storage
│   ├── database/         # Database layer
│   │   ├── models.py     # Pydantic models (incl. PlaylistTemplate)
│   │   ├── sqlite_manager.py # SQLite CRUD with versioned migrations
│   │   └── vector_index.py   # FAISS IndexIDMap (incremental updates)
│   ├── plex/             # Plex integration
│   │   ├── client.py     # PlexAPI wrapper (token validation, file paths)
│   │   └── sync.py       # Sync engine (audio-aware embeddings)
│   ├── playlist/         # Playlist generation
│   │   └── generator.py  # Core logic (4 ordering modes, audio filters)
│   ├── services/         # Shared service layer
│   │   ├── providers.py  # Centralized provider construction
│   │   └── registry.py   # Provider/model/dimension registry
│   ├── ui/               # Web UI (Reflex)
│   │   ├── pages/        # UI pages (8 pages)
│   │   ├── states/       # State management
│   │   ├── components/   # Reusable components (navbar, track_table, etc.)
│   │   ├── job_manager.py # Centralized background task lifecycle
│   │   └── utils/        # UI utilities
│   └── utils/            # Utilities
│       ├── embeddings.py # Embedding providers (audio-enriched, dimension verify)
│       └── logging.py    # Logging setup
├── Dockerfile            # Container image definition
├── docker-compose.yml    # Multi-service orchestration
└── tests/                # Test suite (520+ tests)
    └── ui/               # UI tests

Database Schema

PlexMix stores all music metadata locally:

• artists: Artist information
• albums: Album details with artist relationships
• tracks: Track metadata with full-text search, AI-generated tags (3-5), environments (1-3), instruments (1-3), and tags_generated_at timestamp
• embeddings: Vector embeddings for semantic search (includes all AI-generated metadata + audio features)
• audio_features: DSP-extracted features per track (tempo, key, scale, energy, danceability, loudness, spectral centroid, MFCCs, zero crossing rate)
• playlists: Generated playlist metadata with generation_config JSON for rerun capability
• playlist_tracks: Track positions within playlists (supports reordering)
• playlist_templates: Saved generation presets (5 built-in + user-created)
• schema_version: Versioned migration tracking (currently 9 migrations)
• sync_history: Synchronization audit log

AI Provider Comparison

Legend:

• ⭐ Default/recommended option
• Speed: ⚡ Slow, ⚡⚡ Moderate, ⚡⚡⚡ Fast
• Quality: ⭐ Basic → ⭐⭐⭐⭐⭐ Outstanding
• Cost: 💰 Low, 💰💰 Medium, 💰💰💰 High
• ¹ Reasoning models (GPT-5, Gemini 3, Claude Opus 4.7+) ignore the temperature setting

Embedding Provider Comparison

Key Features:

• Gemini: Highest dimensions (3072d) for maximum semantic precision
• OpenAI: Industry standard, excellent ecosystem integration
• Cohere: Configurable dimensions (256/512/1024/1536), supports images with v4
• Local: Completely free, offline, private, no internet required, with multiple Hugging Face options (MiniLM, MXBAI, EmbeddingGemma, Nomic) to balance speed vs. recall

* EmbeddingGemma and Nomic embeddings support Matryoshka truncation if you need smaller vectors (128/256/512d) without retraining.

How the “Local” Provider Works

When you choose local on the Settings page, PlexMix instantiates the selected Hugging Face sentence-transformers model directly in-process—no HTTP endpoints, API keys, or port configuration are needed. The model weights download once into your Hugging Face cache (e.g., ~/.cache/huggingface) and subsequent embedding calls run entirely on your machine, which keeps everything offline and private.

Set PLEXMIX_LOCAL_EMBEDDING_DEVICE (default cpu) if you want to force a specific device (e.g., cpu to avoid macOS MPS instability, or cuda when running on a GPU server). The UI and CLI will reuse that cached model/device combination whenever local embeddings are needed.

Local LLM Presets & Custom Endpoints

You can now generate playlists with fully local LLMs—no outbound network traffic required. The AI tab in the UI (or plexmix config init) lets you choose between:

• Managed downloads (same workflow as local embeddings) with curated Hugging Face repos:
  • google/gemma-3-1b — fast, CPU-friendly drafts (8K context / ~768 new tokens)
  • liquid/lfm2-1.2b — lightweight music-focused reasoning (32K context)
  • google/gemma-3-4b — higher-quality 4B param model (32K context)
  • NousResearch/Yarn-Mistral-7b-128k — 7B param 128K context for huge playlists (GPU recommended)
• Custom endpoints that speak the OpenAI Chat Completions API (Ollama, LM Studio, llama.cpp server, OpenRouter running on your LAN, etc.)

When you select "Local (Offline)" as the AI provider you can toggle between Managed (Downloaded) and Custom Endpoint modes:

1. Managed (Downloaded)

   • Click Download / Warm Up Model to prefetch weights into your Hugging Face cache
   • Models are loaded in a background worker and reused across tagging/playlist runs
   • Set PLEXMIX_LOCAL_LLM_DEVICE to cpu, cuda, or mps to force device placement (defaults to auto)

2. Custom Endpoint

   • Point PlexMix at any OpenAI-compatible URL (e.g., http://localhost:11434/v1/chat/completions for Ollama)
   • Optionally provide a bearer token; PlexMix will include it as Authorization: Bearer <token>
   • Responses must return a JSON payload with choices[0].message.content

From the CLI you can force the local provider as well:

# Use the configured local model for tagging
plexmix tags generate --provider local

# Run the playlist doctor flow with your offline LLM
plexmix doctor --force

If you ever want to nuke cached weights, delete the relevant directories under ~/.cache/huggingface.

Dimension Trade-offs:

• Higher dimensions = Better semantic understanding but larger storage
• Lower dimensions = Faster search but slightly less accurate
• Cohere's Matryoshka embeddings allow dynamic dimension selection

Optimal Setup

Online (Best Latency & Reasoning)

• AI Provider: gemini-3.5-flash (default). For more advanced reasoning, upgrade to claude-sonnet-4-6, gpt-5.5, or claude-opus-4-8 if you have the budget.
• Embeddings: gemini-embedding-001 for maximum semantic precision, or text-embedding-3-small if you want faster generation with a slightly smaller vector size.
• Network Tips: Keep API keys in ~/.plexmix/credentials and run plexmix config init to verify connectivity. Use plexmix ui --reload during development to check the status cards.

Hybrid (Cloud AI + Local Embeddings)

• AI Provider: Keep using gemini-3.5-flash (or gpt-5.4-mini) for playlist prompts so you get the latest reasoning updates.
• Embeddings: Run mixedbread-ai/mxbai-embed-large-v1 locally so FAISS never leaves your machine while still benefiting from high-quality vectors.
• Workflow Tips: Regenerate embeddings locally after every sync, but keep the AI provider online. This gives you the best of both worlds—fast semantic search without exposing track metadata, plus cloud-scale LLM quality.

Fully Local (Offline-Friendly)

• AI Provider: Use local with managed models (Gemma 3 1B/4B, Liquid LFM 1.2B, Yarn-Mistral 7B) or point at any Ollama/LM Studio endpoint. SSE streaming keeps the UI responsive.
• Embeddings: mixedbread-ai/mxbai-embed-large-v1 (1024d) for the best similarity recall while keeping everything on disk.
• Device: Set PLEXMIX_LOCAL_EMBEDDING_DEVICE=cpu (or cuda if you have a local GPU) so sentence-transformers always uses the right hardware.
• Storage Tips: Keep FAISS index on SSD (~/.plexmix/embeddings.index) and prune unused tracks to reduce RAM usage when generating playlists.

Docker Deployment

PlexMix publishes multi-platform Docker images (amd64 + arm64) to GitHub Container Registry on every release in two variants:

Quick Start

# Option A: Slim image (cloud AI providers)
docker pull ghcr.io/izzoa/plexmix:latest

# Option B: Local/offline image (includes PyTorch for local embeddings + LLM)
docker pull ghcr.io/izzoa/plexmix:latest-local

# Use Docker Compose (clone repo for compose file)
cp .env.example .env
# Edit .env with your credentials (PLEX_TOKEN, GOOGLE_API_KEY, etc.)
docker compose up -d

Sample docker-compose.yml

services:
  plexmix:
    image: ghcr.io/izzoa/plexmix:latest
    ports:
      - "3000:3000"   # Web UI
      - "8000:8000"   # Reflex backend
    volumes:
      - plexmix-data:/data
      # Mount your music library read-only for audio analysis
      # - /path/to/music:/music:ro
    environment:
      - PLEX_URL=http://host.docker.internal:32400
      - PLEX_TOKEN=${PLEX_TOKEN}
      - GOOGLE_API_KEY=${GOOGLE_API_KEY:-}
      # Optional alternative AI providers
      # - OPENAI_API_KEY=${OPENAI_API_KEY:-}
      # - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY:-}
      # - COHERE_API_KEY=${COHERE_API_KEY:-}
      # Optional: protect the web UI with a password
      # - PLEXMIX_UI_PASSWORD=changeme
      # Audio path remapping (translate Plex paths → container paths)
      # - AUDIO_PATH_PREFIX_FROM=/data/music
      # - AUDIO_PATH_PREFIX_TO=/music
    restart: unless-stopped

volumes:
  plexmix-data:

Custom Port Mapping

If you map Docker ports to different external ports, set PLEXMIX_API_URL so the frontend can reach the backend:

    ports:
      - "3152:3000"   # Web UI on port 3152
      - "8154:8000"   # Reflex backend on port 8154
    environment:
      - PLEXMIX_API_URL=http://your-host-ip:8154

Environment Variables

All credentials can be passed as environment variables (no keyring required in containers):

Running CLI Commands

# Sync library
docker compose run plexmix sync

# Generate tags
docker compose run plexmix tags generate

# Create a playlist
docker compose run plexmix create "chill evening vibes"

# Check database health
docker compose run plexmix db info

Audio Path Remapping

Plex reports file paths from its own perspective (e.g., /data/music/Artist/track.flac inside Plex's container). When PlexMix runs in Docker or on a different machine, those paths won't match. Use path remapping to translate Plex paths to local paths for audio analysis:

# docker-compose.yml
services:
  plexmix:
    volumes:
      - /path/to/music:/music:ro    # Mount your music library
    environment:
      - AUDIO_PATH_PREFIX_FROM=/data/music   # Plex's path prefix
      - AUDIO_PATH_PREFIX_TO=/music          # Local path prefix

Or in ~/.plexmix/config.yaml:

audio:
  enabled: true
  path_prefix_from: /data/music
  path_prefix_to: /music

Data Persistence

All data (SQLite database, FAISS index, logs) is stored in a named Docker volume (plexmix-data) mapped to /data inside the container. This persists across container restarts.

Development

Setup Development Environment

# Clone repository
git clone https://github.com/izzoa/plexmix.git
cd plexmix

# Install with development dependencies
poetry install

# Run tests
poetry run pytest

# Format code
poetry run black src/

# Lint
poetry run ruff src/

# Type check
poetry run mypy src/

Running Tests

poetry run pytest
poetry run pytest --cov=plexmix --cov-report=html

Troubleshooting

"No music libraries found"

• Ensure your Plex server has a music library
• Verify your Plex token is correct
• Check server URL is accessible

"Failed to generate embeddings"

• Verify API keys are configured correctly
• Check internet connection
• Try local embeddings: --embedding-provider local

"AI tagging stopped" / "rejected before it reached the model"

• This means the AI provider rejected the request at the network edge before it reached the model — tagging stops immediately instead of retrying every track.
• Most common cause: a malformed or invalid API key. Re-enter the key in Settings (or plexmix config); leading/trailing spaces and newlines are now stripped automatically, but an otherwise-wrong key still needs correcting.
• If the key is correct, check for a corporate proxy, VPN, or firewall that may be intercepting HTTPS requests to the provider.
• Keys containing invalid characters (interior spaces, control, or non-ASCII characters) are now rejected up front with a clear message rather than failing mid-run.

"No tracks found matching criteria"

• First, try: plexmix doctor to check for database issues
• Ensure library is synced: plexmix sync
• Check filters aren't too restrictive
• Verify embeddings were generated

"0 candidate tracks" or "No orphaned embeddings"

• This usually means embeddings reference old track IDs
• Solution: Run plexmix doctor to detect and fix orphaned embeddings
• The doctor will clean up orphaned data and regenerate embeddings

Performance Tips

• Use local embeddings for faster offline operation
• Run sync during off-peak hours for large libraries
• Adjust candidate pool multiplier based on library size (default: 25x playlist length)
  • Smaller libraries: Use lower multiplier (10-15x) for faster generation
  • Larger libraries: Use higher multiplier (30-50x) for better diversity
• Use filters to narrow search space

FAQ

How does PlexMix work?

PlexMix syncs your Plex music library to a local SQLite database, generates AI-powered tags (mood, instruments, environments) for each track, creates semantic embeddings, and uses vector similarity search combined with LLM intelligence to generate playlists from natural language mood descriptions.

Do I need an API key?

Yes, but only one! Google Gemini is the default provider for both AI and embeddings. You can get a free API key at Google AI Studio. Alternative providers (OpenAI, Anthropic, local embeddings) are optional.

How much does it cost to run?

Google Gemini (default):

• Embedding generation: ~$0.10-0.30 for 10,000 tracks (one-time)
• Tag generation: ~$0.20-0.50 for 10,000 tracks (one-time)
• Playlist creation: ~$0.01 per playlist (ongoing)

Alternatives:

• Local embeddings are completely free (no API key needed)
• OpenAI and Anthropic have similar costs

How long does initial sync take?

• Metadata sync: 5-15 minutes for 10,000 tracks
• Tag generation: 30-60 minutes for 10,000 tracks
• Embedding generation: 15-30 minutes for 10,000 tracks

Total: ~1-2 hours for a large library. You can interrupt and resume at any time.

Can I use this without internet?

Partially. After initial sync and tag/embedding generation, you can:

• ✅ Browse your database offline
• ✅ Use local embeddings (install with pip install "plexmix[local]")
• ✅ Run audio analysis locally (with Essentia installed)
• ✅ Generate playlists with local LLM (install with pip install "plexmix[local]")
• ✅ Generate tags with local LLM
• ❌ Use cloud AI providers (requires API key + internet)

What's the difference between tags, environments, and instruments?

• Tags (3-5): Mood and vibe descriptors like "energetic", "melancholic", "upbeat", "chill"
• Environments (1-3): Best contexts for listening like "work", "study", "workout", "party"
• Instruments (1-3): Most prominent instruments like "piano", "guitar", "saxophone", "drums"

All three are automatically generated by AI and improve playlist quality.

Why am I getting "0 candidate tracks"?

This usually means:

1. No embeddings generated: Run plexmix embeddings generate
2. Database out of sync: Run plexmix doctor to fix
3. Filters too restrictive: Remove some filters and try again
4. Empty library: Ensure plexmix sync completed successfully

Can I use multiple Plex libraries?

Not yet. Currently PlexMix supports one music library at a time. Multi-library support is on the roadmap.

Does this modify my Plex server?

Only when creating playlists. PlexMix:

• ✅ Reads metadata from Plex (read-only)
• ✅ Creates playlists in Plex (if enabled with --create-in-plex)
• ❌ Does NOT modify tracks, albums, or artists
• ❌ Does NOT delete anything from Plex

What happens if I delete tracks from Plex?

Run plexmix sync to update your local database. The incremental sync will:

• Detect deleted tracks from Plex
• Remove them from the database
• Clean up orphaned embeddings
• Update the vector index

Or use plexmix doctor to clean up orphaned data.

Can I backup my database?

Yes! Your database is stored at ~/.plexmix/plexmix.db. Simply copy this file and the ~/.plexmix/embeddings.index file to backup all your data, tags, and embeddings.

How do I update PlexMix?

pip install --upgrade plexmix

After updating, run plexmix sync --no-embeddings to apply any database migrations.

Can I contribute?

Absolutely! See CONTRIBUTING.md for guidelines. We welcome bug reports, feature requests, and pull requests.

Roadmap

• Docker support
• Audio feature analysis integration (Essentia)
• Playlist templates (5 built-in presets + user-created)
• Smart shuffle and ordering (similarity, random, alternating artists, energy curve)
• Export/import playlists (M3U, JSON) — CLI and UI
• Keyboard shortcuts and mobile-responsive UI
• Provider auto-discovery (Ollama, OpenAI-compatible endpoints)
• Incremental FAISS index updates
• Multi-library support
• PWA support for mobile

Contributing

Contributions welcome! Please read CONTRIBUTING.md for guidelines.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the GNU Affero General Public License v3.0 - see LICENSE for details.

Acknowledgments

• Built with Typer and Rich
• Plex integration via python-plexapi
• Vector search powered by FAISS
• Audio analysis powered by Essentia
• AI providers: Google, OpenAI, Anthropic, Cohere

---

Made with ❤️ for music lovers