Renamer - Media File Renamer and Metadata Viewer

A powerful terminal-based (TUI) application for managing media collections. Scan directories, view detailed metadata, browse TMDB catalog information with posters, and intelligently rename files. Built with Python and Textual.

Version: 0.5.10

Features

Core Capabilities

• Dual Display Modes: Switch between Technical (codec/track details) and Catalog (TMDB metadata with posters)
• Recursive Directory Scanning: Finds all video files in nested directories
• Tree View Navigation: Keyboard and mouse support with expand/collapse
• Multi-Source Metadata: Combines MediaInfo, filename parsing, embedded tags, and TMDB API
• Intelligent Renaming: Proposes standardized names based on extracted metadata
• Persistent Settings: Configurable mode and cache TTLs saved to ~/.config/renamer/
• Advanced Caching: File-based cache with TTL (6h extractors, 6h TMDB, 30d posters)
• Terminal Poster Display: View movie posters in your terminal using rich-pixels
• Color-Coded Display: Visual highlighting for different data types
• Confirmation Dialogs: Safe file operations with preview and confirmation
• Extensible Architecture: Modular extractor and formatter system for easy extension

Installation

Prerequisites

• Python 3.11+
• UV package manager

Install UV (if not already installed)

curl -LsSf https://astral.sh/uv/install.sh | sh

Install the Application

# Clone or download the project
cd /path/to/renamer

# Install dependencies and build
uv sync

# Install as a global tool
uv tool install .

Usage

Running the App

# Scan current directory
renamer

# Scan specific directory
renamer /path/to/media/directory

Keyboard Commands

• q: Quit the application
• o: Open directory selection dialog
• s: Scan/rescan current directory
• f: Force refresh metadata for selected file (bypass cache)
• r: Rename selected file with proposed name
• p: Toggle tree expansion (expand/collapse all)
• h: Show help screen
• ^p: Open command palette (settings, mode toggle)
• Settings: Access via action bar (top-right corner)

Navigation

• Use arrow keys to navigate the file tree
• Right arrow: Expand directory
• Left arrow: Collapse directory or go to parent
• Mouse clicks supported
• Select a video file to view its details in the right panel

File Renaming

1. Select a media file in the tree
2. Press r to initiate rename
3. Review the proposed new name in the confirmation dialog
4. Press y to confirm or n to cancel
5. The file will be renamed and the tree updated automatically (cache invalidated)

Display Modes

• Technical Mode: Shows codec details, bitrates, track information, resolutions
• Catalog Mode: Shows TMDB data including title, year, rating, overview, genres, and poster
• Toggle between modes via Settings menu or command palette (^p)

Development

For development setup, architecture details, debugging information, and contribution guidelines, see DEVELOP.md.

Supported Video Formats

• .mkv
• .avi
• .mov
• .mp4
• .wmv
• .flv
• .webm
• .m4v
• .3gp
• .ogv

Dependencies

• textual ≥6.11.0: TUI framework
• pymediainfo ≥6.0.0: Detailed media track information
• mutagen ≥1.47.0: Embedded metadata extraction
• python-magic ≥0.4.27: MIME type detection
• langcodes ≥3.5.1: Language code handling
• requests ≥2.31.0: HTTP client for TMDB API
• rich-pixels ≥1.0.0: Terminal image display
• pytest ≥7.0.0: Testing framework

System Requirements

• Python: 3.11 or higher
• MediaInfo Library: System dependency for pymediainfo
  • Ubuntu/Debian: sudo apt install libmediainfo-dev
  • Fedora/CentOS: sudo dnf install libmediainfo-devel
  • Arch Linux: sudo pacman -S libmediainfo
  • macOS/Windows: Automatically handled by pymediainfo