plex-o-matic 0.3.2

An intelligent media file organization tool for Plex

Plex-o-matic

An intelligent media file organization tool for Plex that helps automate the process of renaming and structuring media files for optimal Plex compatibility.

New to Plex-o-matic?

Check out our comprehensive Getting Started Guide for step-by-step instructions on installation, configuration, and your first media organization workflow.

Features

• Media File Management:

  • Automated media file detection and scanning
  • Recursive directory traversal
  • Configurable file extensions and ignore patterns
  • Multi-episode file detection

• Smart Naming System:

  • Automated detection of TV shows and movies
  • Plex-compatible naming conventions
  • Pattern-based filename parsing
  • Standardized output format
  • Multi-episode file detection and handling
  • Special episode detection (OVAs, specials, movies)
  • Season pack organization
  • Anthology show support with intelligent title matching
  • Directory structure inference for incomplete metadata
  • Configurable title vs. episode number priority

• API Integration:

  • TVDB API client for TV show metadata
  • TMDB API client for movie and TV metadata
  • AniDB API client for anime metadata
  • TVMaze API client for comprehensive TV show data
  • Local LLM integration with Ollama and Deepseek
  • Metadata-enhanced filename analysis
  • AI-powered filename suggestions

• Metadata Management:

  • Unified interface for all metadata sources
  • Intelligent filename matching to metadata
  • Confidence-based result ranking
  • Multi-source aggregation
  • Efficient metadata caching
  • Flexible ID format with source prefixes
  • Episode-specific metadata fetching
  • Special episode and multi-episode support
  • Metadata-driven filename generation

• Template System:

  • Customizable templates for TV shows, movies, and anime
  • Support for special episodes and different media types
  • Template visualization and preview functionality
  • Default templates for common naming conventions
  • Multi-episode formatting support

• Robust Backup System:

  • SQLite database integration for operation tracking
  • File checksum verification
  • Safe rename operations with backup/restore capability
  • Operation history with rollback support

• User-Friendly CLI:

  • Preview system for verifying changes before applying
  • Template management commands
  • Dry-run options for testing
  • Verbose output mode for detailed information
  • Intuitive command structure

• Flexible Configuration:

  • JSON-based configuration system
  • Environment variable support
  • Customizable settings for file types and naming
  • Interactive configuration wizard

Python Compatibility

Plex-o-matic is compatible with Python 3.8-3.11. When using Python 3.8, the typing_extensions package is required. This dependency is automatically installed if you install the package via pip.

Installation

From Source

1. Clone the repository:

git clone https://github.com/DouglasMacKrell/plex-o-matic.git
cd plex-o-matic

2. Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

pip install -e .

From PyPI (Coming Soon)

pip install plex-o-matic

Configuration

The first time you run Plex-o-matic, it will create a default configuration file at ~/.plexomatic/config.json. You can edit this file directly or use the CLI's options to override settings.

Key configuration options:

{
    "db_path": "~/.plexomatic/plexomatic.db",
    "log_level": "INFO",
    "allowed_extensions": [".mp4", ".mkv", ".avi", ".mov", ".m4v"],
    "ignore_patterns": ["sample", "trailer", "extra"],
    "recursive_scan": true,
    "backup_enabled": true,
    "api": {
        "tvdb": {
            "api_key": "",
            "auto_retry": true
        },
        "tmdb": {
            "api_key": ""
        },
        "llm": {
            "model_name": "deepseek-r1:8b",
            "base_url": "http://localhost:11434"
        }
    },
    "episode_handling": {
        "anthology_mode": false,
        "title_match_priority": 0.8,
        "infer_from_directory": true,
        "match_threshold": 0.7
    }
}

You can also override the configuration file location:

export PLEXOMATIC_CONFIG_PATH="/path/to/your/config.json"

Basic Usage

Plex-o-matic provides a simple workflow for organizing your media files:

# Configure your API keys and settings
plexomatic configure

# Scan a directory for media files
plexomatic scan --path /path/to/media

# Preview what changes would be made
plexomatic preview

# Apply the changes
plexomatic apply

# If needed, rollback the changes
plexomatic rollback

Command Options

Here are some common options that can be used with the commands:

# Scan non-recursively
plexomatic scan --path /path/to/media --no-recursive

# Scan specific file types
plexomatic scan --path /path/to/media --extensions .mp4,.mkv

# Get detailed output
plexomatic scan --path /path/to/media --verbose

# Preview all changes
plexomatic preview --path /path/to/media --verbose

# Dry run to see what would happen without making changes
plexomatic apply --dry-run

# List all available templates
plexomatic templates list

# Show a specific template
plexomatic templates show --type TV_SHOW

# Preview a template with sample data
plexomatic templates show --type MOVIE --preview

For more detailed usage instructions, refer to the documentation and the Getting Started Guide.

Development

Setting Up Development Environment

1. Create a development environment:

python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

2. Run tests:

pytest

3. Check code quality:

black .
ruff check .
mypy .

Project Structure

• plexomatic/: Main package
  • api/: API integrations
    • tvdb_client.py: TVDB API client
    • tmdb_client.py: TMDB API client
    • anidb_client.py: AniDB API client
    • tvmaze_client.py: TVMaze API client
    • llm_client.py: Local LLM client
  • core/: Core functionality
    • file_scanner.py: Media file detection
    • backup_system.py: Backup and rollback functionality
    • models.py: Database models
  • utils/: Utility functions
    • template_formatter.py: Template formatting
    • template_registry.py: Template registration
    • name_parser.py: Filename parsing
    • preview_system.py: Preview generation
  • config/: Configuration management
  • cli.py: Command-line interface

Documentation

Comprehensive documentation is available in the docs directory:

• Getting Started Guide
• CLI Documentation
• Configuration System
• File Utilities
  • Template System
• Episode Handling
• Metadata System
• Metadata-Episode Integration
• Backend Architecture
  • MediaType System
• Database Schema
• API Integration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgements

TheTVDB

This product uses the TVDB API but is not endorsed or certified by TheTVDB.com or its affiliates.

License

This project is licensed under the GPL-2.0 License - see the LICENSE file for details.