A terminal-based (TUI) application for scanning directories, viewing media file details, and renaming files based on extracted metadata. Built with Python and Textual.

Features

Recursive directory scanning for video files
Tree view navigation with keyboard and mouse support
Detailed metadata extraction from multiple sources (MediaInfo, filename parsing, embedded metadata)
Intelligent file renaming with proposed names based on metadata
Color-coded information display
Command-based interface with hotkeys
Extensible extractor and formatter system
Support for video, audio, and subtitle track information
Confirmation dialogs for file operations

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

Commands

q: Quit the application
o: Open directory selection dialog
s: Rescan current directory
f: Refresh metadata for selected file
r: Rename selected file with proposed name
p: Toggle tree expansion (expand/collapse all)
h: Show help screen

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

Select a media file in the tree
Press r to initiate rename
Review the proposed new name
Press y to confirm or n to cancel
The file will be renamed and the tree updated automatically

Debugging

Formatter Logging

The application includes detailed logging for formatter operations that can be enabled for debugging purposes.

To enable formatter logging:

FORMATTER_LOG=1 renamer /path/to/directory

This will create a formatter.log file in the current directory containing:

Formatter call sequences and ordering
Input/output values for each formatter
Caller information (file and line number)
Any errors during formatting

Useful for troubleshooting metadata display issues or formatter problems.

Architecture

The application uses a modular architecture with separate extractors and formatters:

Extractors

MediaInfoExtractor: Extracts detailed track information using PyMediaInfo
FilenameExtractor: Parses metadata from filenames
MetadataExtractor: Extracts embedded metadata using Mutagen
FileInfoExtractor: Provides basic file information

Formatters

MediaFormatter: Formats extracted data for display
ProposedNameFormatter: Generates intelligent rename suggestions
TrackFormatter: Formats video/audio/subtitle track information
SizeFormatter: Formats file sizes
DateFormatter: Formats timestamps
DurationFormatter: Formats time durations
ResolutionFormatter: Formats video resolutions
TextFormatter: Text styling utilities

Screens

OpenScreen: Directory selection dialog
HelpScreen: Application help and key bindings
RenameConfirmScreen: File rename confirmation dialog

Setup Development Environment

# Install in development mode
uv sync

# Run directly (development)
uv run python main.py

# Or run installed version
renamer

Running Without Rebuilding (Development)

# Run directly from source (no installation needed)
uv run python main.py

# Or run with specific directory
uv run python main.py /path/to/directory

Uninstall

uv tool uninstall renamer

Supported Video Formats

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

Dependencies

textual: TUI framework
pymediainfo: Detailed media track information
mutagen: Embedded metadata extraction
python-magic: MIME type detection
langcodes: Language code handling

README.md

Renamer - Media File Renamer and Metadata Editor