Add initial project files for Jellyfin-Plex Library Checker
- Create .editorconfig for consistent coding styles. - Add .envrc for direnv integration. - Include .gitignore to exclude environment and build files. - Implement compare_movies.py and analyze_movies.py for movie library comparison and analysis. - Implement compare_series.py and analyze_series.py for TV series library comparison and analysis. - Add configuration example in config.example.txt. - Create README.md with project overview, setup instructions, and usage examples. - Add LICENSE file for MIT License. - Include flake.nix and flake.lock for Nix-based development environment. - Add USAGE.md for quick start guide and common commands.
This commit is contained in:
Danilo Reyes
219
README.md
Normal file
219
README.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Configuration
|
||||
|
||||
Create a `.env` file in the project root (use `config.example.txt` as a template):
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
```bash
|
||||
python compare_movies.py
|
||||
# Or with Nix:
|
||||
nix run .#compare-movies
|
||||
```
|
||||
|
||||
**2. Analyze missing movies:**
|
||||
```bash
|
||||
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:**
|
||||
```bash
|
||||
python compare_series.py
|
||||
# Or with Nix:
|
||||
nix run .#compare-series
|
||||
```
|
||||
|
||||
**2. Analyze missing series:**
|
||||
```bash
|
||||
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](https://github.com/pkkid/python-plexapi) - Plex API client
|
||||
- [requests](https://docs.python-requests.org/) - HTTP library
|
||||
- [python-dotenv](https://github.com/theskumar/python-dotenv) - Environment management
|
||||
Reference in New Issue
Block a user