Jellyfin Playlist Manager

A high-performance, lightweight, and modular playlist management toolkit for Jellyfin Music Server (192.168.0.125:8096).

Designed to replace monolithic scripts and heavy AI tools with an ultra-fast local SQLite database cache and global shared playlist creation.

---

🚀 Key Features

• Local SQLite Cache & Instant Search: Syncs your entire Jellyfin music collection locally in a single bulk request. Queries run in sub-milliseconds (~1.8ms across 100k+ tracks) via SQLite indexes and FTS5 (Full-Text Search) without hammering the Jellyfin API.
• YouTube & YouTube Music Playlist Importer: Extracts track and artist metadata using flat metadata scraping (zero audio downloading) with yt-dlp.
• Multi-Tier Fuzzy Matcher: Matches imported songs against your local library through exact matching, token overlap, and FTS5 similarity ranking.
• Studio vs. Live Prioritization: Automatically detects live recordings ((Live at ...), Unplugged, etc.) and prioritizes original studio album versions.
• Global Public Playlists: Publishes shared playlists (IsPublic: true) directly into Jellyfin using official REST API item GUIDs.
• Zero Heavy Dependencies: Clean architecture, standard library core, with lightweight yt-dlp for YouTube parsing.

---

📁 Project Structure

jellyfin-playlist-manager/
├── cli.py                  # CLI commands (ping, sync, stats, search, artists, create-playlist, list-playlists)
├── main.py                 # Main entry point alias
├── config.example.json     # Configuration template (JSON)
├── requirements.txt        # Python dependencies (yt-dlp)
├── core/
│   ├── __init__.py
│   ├── config.py           # Config loader (JSON / YAML / Environment variables)
│   ├── db.py               # SQLite schema, transactions, FTS5 search, metrics
│   ├── jellyfin_api.py     # Resilient Jellyfin REST API client (sync & playlist publishing)
│   ├── matcher.py          # 4-tier fuzzy track matching engine
│   ├── models.py           # Data models (Track, PlaylistItem, ImportedPlaylist, MatchResult)
│   ├── normalizer.py       # Title/Artist/Album normalization & live detection
│   ├── playlist_manager.py # High-level import & publish coordinator
│   └── importers/
│       ├── __init__.py     # Importers registry
│       ├── base.py         # Abstract BaseImporter interface
│       └── youtube.py      # YouTube & YouTube Music playlist importer
└── tests/
    ├── __init__.py
    ├── test_cache.py       # Unit tests for DB, normalizer, and FTS5 search
    └── test_matcher.py     # Unit tests for matching engine & YouTube parser

---

⚙️ Configuration

1. Copy config.example.json to config.json:

   cp config.example.json config.json
   

2. Edit config.json with your Jellyfin server details:

   {
     "jellyfin": {
       "server_url": "http://192.168.0.125:8096",
       "api_key": "YOUR_JELLYFIN_API_KEY",
       "user_id": "YOUR_JELLYFIN_USER_ID"
     },
     "database": {
       "path": "data/music_cache.db"
     },
     "sync": {
       "batch_size": 1000,
       "request_timeout": 30
     }
   }
   

You can also configure via environment variables: JELLYFIN_SERVER_URL, JELLYFIN_API_KEY, JELLYFIN_USER_ID, JELLYFIN_DB_PATH.

---

📖 CLI Usage

1. Test Jellyfin Connection

python cli.py ping

2. Synchronize Music Library to Local SQLite

Pulls all audio items from Jellyfin and updates data/music_cache.db:

python cli.py sync

3. Create Global Public Playlist from YouTube / YouTube Music

Imports a playlist, runs multi-tier matching against your 100k+ local library in ~2 seconds, and creates a public Jellyfin playlist:

# Create playlist directly from YouTube Music link
python cli.py create-playlist "https://music.youtube.com/playlist?list=RDCLAK5uy_mRkN4u_vp9wj0JZuVOyJyjUACfjZG_3gI"

# Custom playlist name with auto-confirm
python cli.py create-playlist "https://music.youtube.com/playlist?list=..." --name "My Nu Metal Hits" -y

# Preview matches without modifying Jellyfin (Dry Run)
python cli.py create-playlist "https://music.youtube.com/playlist?list=..." --dry-run --show-missing

# Verbose mode showing matched item IDs and diagnostic scores
python cli.py create-playlist "https://music.youtube.com/playlist?list=..." -v

4. List Existing Playlists

python cli.py list-playlists

5. Search Local Music Cache

# Fast full-text search (~1.8ms)
python cli.py search "Comfortably Numb"

# Strict cleaned title + artist match
python cli.py search "In The End" --artist "Linkin Park" --exact

# Verbose search (shows Jellyfin GUIDs and filesystem paths)
python cli.py search "Bohemian Rhapsody" -v

6. View Library Statistics

python cli.py stats
python cli.py artists --limit 20

---

🧪 Running Unit Tests

python -m unittest discover tests