AI-Powered Movie File Organizer with TMDB Integration

Version: 0.1
Author: Pablo Murad (runawaydevil)
Repository: https://github.com/runawaydevil/organizer-movies.git

Organize your movie collection automatically using AI and The Movie Database (TMDB) API. This tool analyzes movie filenames, identifies movies using AI and TMDB, creates properly named folders, and generates comprehensive PDF reports.

Movie Organizer v0.1 - Clean, intuitive interface for organizing your movie collection

• AI-Powered: Uses OpenAI GPT models to analyze movie filenames
• TMDB Integration: Enhances accuracy with The Movie Database API
• Hybrid Mode: Combines AI + TMDB for best results
• Smart Fallback: Works with AI-only if TMDB is unavailable

• Automatic Folder Creation: Creates folders in format "Movie Title (Year)"
• Intelligent Folder Management:
  • Single movie: Renames existing folder
  • Multiple movies: Creates individual folders for each
• Media Server Compatible: Works with Plex, Jellyfin, Emby, Kodi
• Network Support: Handles network drives and mapped drives

• Manual Search: Search TMDB manually for difficult movies
• Metadata Editing: Edit movie information before organizing
• PDF Reports: Automatic generation of organized movies report
• Duplicate Prevention: Tracks organized movies to avoid reprocessing
• Cache System: Caches TMDB results for better performance

• Modern GUI: Clean, intuitive interface built with tkinter
• Real-time Progress: Live progress updates during processing
• Confidence Indicators: Shows analysis confidence levels
• Network Detection: Automatically detects and handles network paths
• Settings Panel: Easy configuration of all options

• Python 3.8+ (Required)
• OpenAI API Key (Required - for AI movie identification)
• TMDB API Key & Bearer Token (Optional but recommended - for enhanced accuracy)

1. Clone the repository:

   git clone https://github.com/runawaydevil/organizer-movies.git
   cd organizer-movies

2. Install dependencies:

   pip install -r requirements.txt

3. Run the application:

   Windows/Linux (GUI):

   python main.py

   Linux (CLI):

   python services/cli_organizer.py

1. Get API Keys:

   • OpenAI: Visit OpenAI API (Required)
   • TMDB: Visit TMDB API (Optional)

2. Configure in GUI:

   • Open Settings (File → Settings or Ctrl+,)
   • Enter your OpenAI API key (required)
   • Optionally enter TMDB credentials for better accuracy
   • Keys are encrypted and stored securely locally

3. Start Organizing:

   • Select your movie folder
   • Review AI-identified movies
   • Click "Process Files" to organize

python main.py

python services/cli_organizer.py

1. Configure API Keys - Set up OpenAI (required) and TMDB (optional) APIs
2. Select Movie Folder - Choose folder containing your movie files
3. AI Analysis - Let AI identify your movies automatically
4. Review & Organize - Check results and organize with one click
5. PDF Report - Get automatic reports of organized movies

• API Setup Guide - Configure OpenAI and TMDB APIs
• CLI Usage Guide - Command line interface
• Troubleshooting - Common issues and solutions
• Developer Setup - Development environment
• Contributing - How to contribute
• Changelog - Version history

movie-organizer/
├── main.py                    # GUI entry point
├── cli.py                     # CLI entry point  
├── version.py                 # Version management
├── models/                    # Data models
├── services/                  # Core services
├── docs/                      # Documentation
├── scripts/                   # Build and utility scripts
├── Images/                    # Screenshots and assets
└── README.md                  # This file

• Download latest release from GitHub Releases
• Windows: Use installer or portable version
• Linux/macOS: Run from source

# Build release package
python scripts/build_release.py

# Create Git tag
python scripts/create_git_tag.py

See Release Instructions for details.

• 🔐 Encrypted API Keys: AES-256 encryption for secure local storage
• 🏠 Local Processing: All analysis done on your machine
• 🚫 No Telemetry: Zero data collection or tracking
• 🔒 Secure Communication: Only movie titles sent to APIs

We welcome contributions! Please see our Contributing Guide for details.

• 📖 Documentation: Check the docs/ folder
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions
• 🔧 Troubleshooting: Common Issues Guide

Free & Open Source Software

This project is completely free and licensed under the MIT License. You can:

✅ Use it for personal or commercial purposes
✅ Copy and distribute it freely
✅ Modify and create derivative works
✅ Sell software that includes this code

Only requirement: Give credit to Pablo Murad (runawaydevil) as the original author.

See the LICENSE file for complete details.

• OpenAI for GPT API and AI capabilities
• The Movie Database (TMDB) for comprehensive movie metadata
• ReportLab for PDF generation capabilities
• Cryptography library for secure API key storage
• All contributors and users who help improve this project

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Repository: https://github.com/runawaydevil/organizer-movies.git

Movie Organizer v0.1
Made with ❤️ by Pablo Murad (runawaydevil)
Organize your movie collection like a pro! 🎬