MovieMapper/PROJECT_OVERVIEW.md

MovieMapper Project Overview

Project Description

MovieMapper is a desktop application designed for organizing and managing movie and TV show collections. It provides a user-friendly interface for browsing media files, searching TV shows using TheTVDB API, and managing file metadata including durations and quality information.

Architecture

Main Components

1. Electron-based Desktop Application - Cross-platform desktop application using Electron
2. Main Process (main.js) - Handles application lifecycle, IPC communication, and API interactions
3. Renderer Process (renderer.js) - Manages the user interface and user interactions
4. File Utilities (utils/fileUtils.js) - Handles file scanning, metadata extraction, and media processing
5. Frontend Interface (index.html) - HTML structure with CSS styling

Core Features

1. Directory Browsing and Media Scanning

• Directory Selection: Users can select any directory containing media files
• Recursive Scanning: Automatically scans subdirectories for media files
• Media File Detection: Identifies media files based on supported extensions (.mp4, .mkv, .avi, .mov, .flv, .webm)
• File Metadata Extraction:
  • Video duration in mm:ss format
  • Video quality (4K, 1080p, 720p, etc.)
  • Frame rate information
  • File size and modification date

2. TV Show Search and Management

• TheTVDB API Integration: Search and retrieve TV show information
• Show Details: View show information including:
  • Series name
  • Status
  • First aired date
  • Overview/plot summary
  • Image/artwork
• Season Management: Browse seasons with episode counts
• Episode Information: View episode details including:
  • Episode names
  • Episode numbers
  • Runtime information
  • Air dates

3. File Management

• File Renaming: Click on file names to rename them directly in the interface (changes persist to actual file system)
• File Tagging: Mark files as extras or with commentary tags
• File Untagging: Click on already tagged files to remove the tag
• File Organization: Move files to "extras" folder for better organization
• Problematic File Handling: Identifies and flags files that cause issues during metadata extraction

4. Technical Features

• Electron Framework: Cross-platform desktop application
• FFmpeg Integration: For video metadata extraction (duration, quality, frame rate)
• API Error Handling: Robust error handling for API calls and file operations
• IPC Communication: Inter-process communication between main and renderer processes
• Environment Configuration: API keys and configuration loaded from .env file

Technical Implementation

Main Process (main.js)

• IPC Handlers:
  • Directory selection and scanning
  • File renaming
  • TVDB API integration (search, show details, season episodes)
  • File system operations (moving files to extras)
  • Debugging utilities
• Electron Integration: Window management, application lifecycle
• API Authentication: Handles TVDB v4 API authentication with bearer tokens

Renderer Process (renderer.js)

• UI Management: Handles all user interface interactions
• Event Handling: Click events, input handling, form submissions
• File Display: Renders file lists with metadata
• Search Functionality: Debounced search with API integration
• Editing Support: Makes file names editable with save functionality
• Tagging System: Visual indicators for tagged files

File Utilities (utils/fileUtils.js)

• Directory Scanning: Recursively scans directories for media files
• Metadata Extraction:
  • extractFileDuration(): Gets video duration using FFmpeg
  • extractVideoQuality(): Determines video quality and frame rate
  • extractFileMetadata(): Comprehensive metadata extraction
• Error Handling: Graceful handling of permission errors and file issues

API Integration

TheTVDB v4 API

• Authentication: Uses bearer token authentication
• Endpoints:
  • Search: https://api4.thetvdb.com/v4/search
  • Show Details: https://api4.thetvdb.com/v4/series/{id}/extended
  • Episodes: https://api4.thetvdb.com/v4/series/{id}/episodes
• Configuration: API key loaded from environment variables

User Interface

Layout

• Sidebar:
  • Directory selection controls
  • TV show search input
  • Search results display
  • Show details and seasons display
• Main Content Area:
  • File listing with metadata
  • File renaming capability
  • File tagging indicators

Features

• Responsive Design: Clean, organized interface
• Visual Feedback:
  • File renaming with editing support
  • Tagging indicators with visual effects
  • Problematic file highlighting
• Search Integration: Real-time search with debouncing
• Episode Display: Organized season and episode information

Dependencies

Core Dependencies

• Electron: Desktop application framework
• fluent-ffmpeg: Video metadata extraction
• axios: HTTP client for API requests
• dotenv: Environment variable management

Development Dependencies

• package.json: Project metadata and dependencies
• package-lock.json: Exact dependency versions

Installation and Setup

Prerequisites

1. Node.js installed
2. FFmpeg installed (required for video metadata extraction)
3. TheTVDB API key (included in .env file)

Setup Process

1. Clone the repository
2. Install dependencies: npm install
3. Run the application: npm start or electron .

Usage Workflow

1. Select Directory: Click "Select Directory" to choose a folder containing media files
2. Scan Files: Application automatically scans the directory and displays media files with metadata
3. Browse Files: View files with duration, quality, and frame rate information
4. Rename Files: Click on any file name to rename it
5. Search Shows: Use the search functionality to find TV shows and their details
6. View Seasons: Click on seasons to see episode information
7. Organize Files: Use tagging and moving to extras functionality for better organization

Error Handling and Debugging

• File System Errors: Graceful handling of permission errors and missing files
• API Errors: Comprehensive error handling for TVDB API calls
• Metadata Extraction: Fallbacks when FFmpeg fails to extract information
• Debug Tools: Built-in debugging utilities for problematic files

Future Enhancements

• Enhanced file matching algorithms for better episode identification
• Database storage for persistent show and file information
• Additional tagging and categorization features
• Export functionality for organized collections
• Advanced search and filtering options