166 lines
7.0 KiB
Markdown
166 lines
7.0 KiB
Markdown
# 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 |