renamer/README.md

Renamer - Media File Renamer and Metadata Editor

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

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
4. Press y to confirm or n to cancel
5. 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