# 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
- **Video Preview**: Click the 🎬 icon next to any file to preview it in a centered modal window
- **MKV File Support**: MKV files show a warning and provide option to open in default media player
- **Warning Sign Display**: Files with issues are indicated with a warning sign (⚠️) in the UI but this does not affect the actual file name

### 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