plexfin-compare/README.md

Jellyfin-Plex Library Checker

A comprehensive tool to compare and analyze media libraries between Plex, Jellyfin, and your filesystem. Identifies missing content, mismatches, and provides detailed analysis to help maintain consistency across your media servers.

Features

• 🎬 Movie Library Comparison - Compare movies across Plex, Jellyfin, and filesystem
• 📺 TV Series Library Comparison - Compare TV shows with episode counts
• 🔍 Detailed Analysis - Identify patterns in missing content (codecs, resolution, naming, etc.)
• 🚫 .plexignore Detection - Automatically checks for exclusion files
• 📊 Comprehensive Reports - JSON and human-readable reports
• 🔧 Multiple Path Support - Handle libraries across multiple directories
• 🎯 Smart Matching - Aggressive normalization handles title variations, years, tags, and language differences

The Problem This Solves

When running both Plex and Jellyfin on the same media library, you might notice:

• Some movies show in Jellyfin but not in Plex
• Inconsistent episode counts between servers
• Difficulty tracking down which files aren't being scanned

This tool helps you quickly identify and diagnose these issues by:

• Comparing what each server sees vs. what's actually on disk
• Analyzing codec, resolution, and metadata issues
• Detecting .plexignore files or other exclusions
• Finding orphaned entries in your databases

Setup

Option 1: Using Nix (Recommended)

If you have Nix with Flakes enabled:

nix develop

This will automatically:

• Set up a Python environment
• Create a virtual environment
• Install all dependencies from requirements.txt

Option 2: Using pip

1. Install dependencies:

pip install -r requirements.txt

Configuration

Create a .env file in the project root (use config.example.txt as a template):

# Plex Configuration
PLEX_URL=http://localhost:32400
PLEX_TOKEN=your_plex_token_here

# Jellyfin Configuration
JELLYFIN_URL=http://localhost:8096
JELLYFIN_API_KEY=your_jellyfin_api_key_here
JELLYFIN_USER_ID=your_jellyfin_user_id_here

# Filesystem Configuration
MOVIES_PATH=/path/to/your/movies/directory
SERIES_PATH=/path/to/your/tv/series/directory
# Optional: Additional series paths
SERIES_PATH_2=/path/to/backup/series

Usage

For Movies

1. Compare movie libraries:

python compare_movies.py
# Or with Nix:
nix run .#compare-movies

2. Analyze missing movies:

python analyze_movies.py
# Or with Nix:
nix run .#analyze-movies

The movie analyzer will report:

• File extensions and naming patterns
• Low resolution or unusual codecs
• Missing color metadata
• .plexignore file detection
• Recommendations for fixing issues

For TV Series

1. Compare series libraries:

python compare_series.py
# Or with Nix:
nix run .#compare-series

2. Analyze missing series:

python analyze_series.py
# Or with Nix:
nix run .#analyze-series

The series analyzer will report:

• Episode counts (including empty directories)
• Naming patterns and special characters
• Title mismatches between servers
• .plexignore file detection

Getting API Credentials

Plex Token

1. Open Plex Web App in your browser
2. Open Developer Tools (F12)
3. Go to Network tab
4. Click on any request to your Plex server
5. Look for X-Plex-Token in the request headers
6. Copy that token value

Jellyfin API Key

1. Open Jellyfin Dashboard
2. Go to Dashboard → API Keys
3. Create a new API key
4. Copy the API key

Jellyfin User ID

1. Open Jellyfin Dashboard
2. Go to Dashboard → Users
3. Click on your user account
4. Look at the URL - it will contain something like /Users/{userId}
5. Copy the UUID part (format: a1b2c3d4-5678-90ab-cdef-1234567890ab)

How It Works

Matching Logic

The tool uses multiple strategies to match content across systems:

1. Title Normalization - Removes punctuation, years, articles, and special characters
2. Path Matching - Compares filesystem paths to handle title variations
3. Flexible Comparison - Handles:
   • Different romanizations (e.g., "Haikyu!!" vs "Haikyuu!!")
   • Language variations (e.g., "La familia P. Luche" vs "The Plush Family")
   • Tag removal (e.g., {imdb-tt123456}, [tvdbid-12345])
   • Year differences in titles

Output Files

• movies_comparison_report.json - Detailed movie comparison data
• series_comparison_report.json - Detailed TV series comparison data

Common Issues Found

Movies

• Old codecs (mpeg2, mpeg4/XviD) - Plex may skip these
• Low resolution (< 720p) - May be filtered as samples
• Missing/invalid metadata - Causes scanner issues
• .plexignore exclusions - Files explicitly ignored

TV Series

• Empty directories (0 episodes) - Plex correctly skips these
• Title mismatches - Different names between servers
• Multiple library paths - Content spread across locations

Example Output

📊 SUMMARY:
   Movies missing from Plex (found in filesystem): 12
   Movies missing from Plex (found in Jellyfin): 12
   Movies in Plex but not in filesystem: 0

⚠️  Found .plexignore at: /srv/pool/multimedia/media/Movies/.plexignore
   → Check if these movies are listed in it!

🎯 LIKELY CAUSES:
   • ALL missing movies are visible in Jellyfin
   • Low resolution files (< 720p) might be filtered out by Plex
   • Mixed SD/HD color metadata confuses Plex's codec detection
   • Unusual/old codecs (mpeg2video, mpeg4) not well supported

Troubleshooting

"No movies found"

• Verify MOVIES_PATH is correct and accessible
• Check file permissions

"Authentication failed"

• Verify your Plex token is correct
• Check Jellyfin API key and User ID

"Series reported as missing but I can see them in Plex"

• This is usually due to title variations
• The tool uses path matching as a fallback
• Check the JSON report for path details

Contributing

Issues and pull requests are welcome! This tool was created to solve real media server management problems.

License

MIT License - feel free to use and modify as needed.

Acknowledgments

Built with:

• plexapi - Plex API client
• requests - HTTP library
• python-dotenv - Environment management