sha/renamer
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Update documentation and versioning for v0.6.0; enhance AI assistant reference

Browse Source
This commit is contained in:
sHa
2025-12-31 00:21:01 +00:00
parent 6121311444
commit 3fbf45083f
7 changed files with 741 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

97
AI_AGENT.md
View File

@@ -4,44 +4,67 @@
This is a Python Terminal User Interface (TUI) application for managing media files. It uses the Textual library to provide a curses-like interface in the terminal. The app allows users to scan directories for video files, display them in a hierarchical tree view, view detailed metadata information including video, audio, and subtitle tracks, and rename files based on intelligent metadata extraction. This is a Python Terminal User Interface (TUI) application for managing media files. It uses the Textual library to provide a curses-like interface in the terminal. The app allows users to scan directories for video files, display them in a hierarchical tree view, view detailed metadata information including video, audio, and subtitle tracks, and rename files based on intelligent metadata extraction.
**Current Version**: 0.5.10
Key features: Key features:
- Recursive directory scanning - Recursive directory scanning with tree navigation
- Dual-mode display: Technical (codec/track details) and Catalog (TMDB metadata with posters)
- Tree-based file navigation with expand/collapse functionality - Tree-based file navigation with expand/collapse functionality
- Detailed metadata extraction from multiple sources - Multi-source metadata extraction (MediaInfo, filename parsing, embedded tags, TMDB API)
- Intelligent file renaming with proposed names - Intelligent file renaming with proposed names and confirmation
- Settings management with persistent configuration
- Advanced caching system with TTL (6h extractors, 6h TMDB, 30d posters)
- Terminal poster display using rich-pixels
- Color-coded information display - Color-coded information display
- Keyboard and mouse navigation - Keyboard and mouse navigation
- Multiple UI screens (main app, directory selection, help, rename confirmation) - Multiple UI screens (main app, directory selection, help, rename confirmation, settings)
- Extensible extractor and formatter architecture - Extensible extractor and formatter architecture
- Loading indicators and error handling - Loading indicators and comprehensive error handling
## Technology Stack ## Technology Stack
- Python 3.11+ - Python 3.11+
- Textual (TUI framework) - Textual ≥6.11.0 (TUI framework)
- PyMediaInfo (detailed track information) - PyMediaInfo ≥6.0.0 (detailed track information)
- Mutagen (embedded metadata) - Mutagen ≥1.47.0 (embedded metadata)
- Python-Magic (MIME type detection) - Python-Magic ≥0.4.27 (MIME type detection)
- Langcodes (language code handling) - Langcodes ≥3.5.1 (language code handling)
- UV (package manager) - Requests ≥2.31.0 (HTTP client for TMDB API)
- Rich-Pixels ≥1.0.0 (terminal image display)
- Pytest ≥7.0.0 (testing framework)
- UV (package manager and build tool)
## Code Structure ## Code Structure
- `main.py`: Main application entry point with argument parsing - `renamer/main.py`: Main application entry point with argument parsing
- `pyproject.toml`: Project configuration and dependencies (version 0.2.0) - `pyproject.toml`: Project configuration and dependencies (version 0.5.10)
- `README.md`: User documentation - `README.md`: User documentation
- `DEVELOP.md`: Developer guide with debugging info
- `INSTALL.md`: Installation instructions
- `CLAUDE.md`: Comprehensive AI assistant reference guide
- `ToDo.md`: Development task tracking - `ToDo.md`: Development task tracking
- `AI_AGENT.md`: This file - `AI_AGENT.md`: This file (AI agent instructions)
- `renamer/`: Main package - `renamer/`: Main package
- `app.py`: Main Textual application class with tree management and file operations - `app.py`: Main Textual application class with tree management and file operations
- `extractor.py`: MediaExtractor class coordinating multiple extractors - `settings.py`: Settings management with JSON storage
- `cache.py`: File-based caching system with TTL support
- `secrets.py`: API keys and secrets (TMDB)
- `constants.py`: Application constants (media types, sources, resolutions, special editions)
- `screens.py`: Additional UI screens (OpenScreen, HelpScreen, RenameConfirmScreen, SettingsScreen)
- `bump.py`: Version bump utility
- `release.py`: Release automation script
- `extractors/`: Individual extractor classes - `extractors/`: Individual extractor classes
- `extractor.py`: MediaExtractor class coordinating all extractors
- `mediainfo_extractor.py`: PyMediaInfo-based extraction - `mediainfo_extractor.py`: PyMediaInfo-based extraction
- `filename_extractor.py`: Filename parsing - `filename_extractor.py`: Filename parsing with regex patterns
- `metadata_extractor.py`: Mutagen-based metadata - `metadata_extractor.py`: Mutagen-based embedded metadata
- `fileinfo_extractor.py`: Basic file information - `fileinfo_extractor.py`: Basic file information
- `tmdb_extractor.py`: The Movie Database API integration
- `default_extractor.py`: Fallback extractor
- `formatters/`: Data formatting classes - `formatters/`: Data formatting classes
- `formatter.py`: Base formatter interface
- `media_formatter.py`: Main formatter coordinating display - `media_formatter.py`: Main formatter coordinating display
- `catalog_formatter.py`: Catalog mode formatting with TMDB data
- `proposed_name_formatter.py`: Generates rename suggestions - `proposed_name_formatter.py`: Generates rename suggestions
- `track_formatter.py`: Track information formatting - `track_formatter.py`: Track information formatting
- `size_formatter.py`: File size formatting - `size_formatter.py`: File size formatting
@@ -52,9 +75,17 @@ Key features:
- `extension_formatter.py`: File extension formatting - `extension_formatter.py`: File extension formatting
- `helper_formatter.py`: Helper formatting utilities - `helper_formatter.py`: Helper formatting utilities
- `special_info_formatter.py`: Special edition information - `special_info_formatter.py`: Special edition information
- `constants.py`: Application constants (supported media types) - `decorators/`: Utility decorators
- `screens.py`: Additional UI screens (OpenScreen, HelpScreen, RenameConfirmScreen) - `caching.py`: Caching decorator for automatic method caching
- `test/`: Unit tests for extractors - `test/`: Unit tests for extractors
- `test_filename_extractor.py`: Filename parsing tests
- `test_mediainfo_extractor.py`: MediaInfo extraction tests
- `test_mediainfo_frame_class.py`: Frame class detection tests
- `test_fileinfo_extractor.py`: File info tests
- `test_metadata_extractor.py`: Metadata extraction tests
- `test_filename_detection.py`: Filename pattern detection tests
- `filenames.txt`, `test_filenames.txt`: Sample test data
- `test_cases.json`, `test_mediainfo_frame_class.json`: Test fixtures
## Instructions for AI Agents ## Instructions for AI Agents
@@ -113,14 +144,26 @@ The app uses multiple screens for different operations:
- `HelpScreen`: Comprehensive help with key bindings - `HelpScreen`: Comprehensive help with key bindings
- `RenameConfirmScreen`: File rename confirmation with error handling - `RenameConfirmScreen`: File rename confirmation with error handling
### Completed Major Features
- ✅ Settings management with JSON configuration
- ✅ Mode toggle (technical/catalog)
- ✅ Caching system with TTL support
- ✅ TMDB integration for catalog data
- ✅ Poster display in terminal
- ✅ Settings UI screen
### Future Enhancements ### Future Enhancements
- Metadata editing capabilities - Metadata editing capabilities
- Batch rename operations - Batch rename operations
- Configuration file support
- Plugin system for custom extractors/formatters - Plugin system for custom extractors/formatters
- Advanced search and filtering - Advanced search and filtering
- Undo/redo functionality - Undo/redo functionality
- Blue highlighting for changed parts in proposed filename
- Exclude dev commands from distributed package
- Full genre name expansion (currently shows codes)
- Optimized poster quality and display
### Testing ### Testing
@@ -141,4 +184,16 @@ The app uses multiple screens for different operations:
- Update ToDo.md when completing tasks - Update ToDo.md when completing tasks
- Update version numbers appropriately - Update version numbers appropriately
This document should be updated as the project evolves. ## Important Files for AI Assistants
For comprehensive project information, AI assistants should refer to:
1. **CLAUDE.md**: Complete AI assistant reference guide (most comprehensive)
2. **AI_AGENT.md**: This file (concise instructions)
3. **DEVELOP.md**: Developer setup and debugging
4. **ToDo.md**: Current task list and completed items
5. **README.md**: User-facing documentation
This document should be updated as the project evolves.
---
**Last Updated**: 2025-12-31

441
CLAUDE.md Normal file
View File

@@ -0,0 +1,441 @@
# CLAUDE.md - AI Assistant Reference Guide
This document provides comprehensive project information for AI assistants (like Claude) working on the Renamer project.
## Project Overview
**Renamer** is a sophisticated Terminal User Interface (TUI) application for managing, viewing metadata, and renaming media files. Built with Python and the Textual framework, it provides an interactive, curses-like interface for media collection management.
### Current Version
- **Version**: 0.5.10
- **Python**: 3.11+
- **Status**: Active development with media catalog mode features
## Project Purpose
Renamer serves two primary use cases:
1. **Technical Mode**: Detailed technical metadata viewing (video tracks, audio streams, codecs, bitrates)
2. **Catalog Mode**: Media library catalog view with TMDB integration (posters, ratings, descriptions, genres)
## Architecture Overview
### Core Components
#### Main Application (`renamer/app.py`)
- Main `RenamerApp` class inheriting from Textual's `App`
- Manages TUI layout with split view: file tree (left) and details panel (right)
- Handles keyboard/mouse navigation and user commands
- Coordinates file operations and metadata extraction
- Implements efficient tree updates for file renaming
#### Entry Point (`renamer/main.py`)
- Argument parsing for directory selection
- Application initialization and launch
#### Constants (`renamer/constants.py`)
Defines comprehensive dictionaries:
- `MEDIA_TYPES`: Supported video formats (mkv, avi, mov, mp4, etc.)
- `SOURCE_DICT`: Video source types (WEB-DL, BDRip, BluRay, etc.)
- `FRAME_CLASSES`: Resolution classifications (480p-8K)
- `MOVIE_DB_DICT`: Database identifiers (TMDB, IMDB, Trakt, TVDB)
- `SPECIAL_EDITIONS`: Edition types (Director's Cut, Extended, etc.)
### Extractor System (`renamer/extractors/`)
Modular architecture for gathering metadata from multiple sources:
#### Core Extractors
1. **MediaInfoExtractor** (`mediainfo_extractor.py`)
- Uses PyMediaInfo library
- Extracts detailed track information (video, audio, subtitle)
- Provides codec, bitrate, frame rate, resolution data
2. **FilenameExtractor** (`filename_extractor.py`)
- Parses metadata from filename patterns
- Detects year, resolution, source, codecs, edition info
- Uses regex patterns to extract structured data
3. **MetadataExtractor** (`metadata_extractor.py`)
- Reads embedded metadata using Mutagen
- Extracts tags, container format info
4. **FileInfoExtractor** (`fileinfo_extractor.py`)
- Basic file information (size, dates, permissions)
- MIME type detection via python-magic
5. **TMDBExtractor** (`tmdb_extractor.py`)
- The Movie Database API integration
- Fetches title, year, ratings, overview, genres, poster
- Supports movie and TV show data
6. **DefaultExtractor** (`default_extractor.py`)
- Fallback extractor providing minimal data
#### Extractor Coordinator (`extractor.py`)
- `MediaExtractor` class orchestrates all extractors
- Provides unified `get()` interface for data retrieval
- Caching support via decorators
### Formatter System (`renamer/formatters/`)
Transforms raw extracted data into formatted display strings:
#### Specialized Formatters
1. **MediaFormatter** (`media_formatter.py`)
- Main formatter coordinating all format operations
- Mode-aware (technical vs catalog)
- Applies color coding and styling
2. **CatalogFormatter** (`catalog_formatter.py`)
- Formats catalog mode display
- Renders TMDB data, ratings, genres, overview
- Terminal image display for posters (rich-pixels)
3. **TrackFormatter** (`track_formatter.py`)
- Video/audio/subtitle track formatting
- Color-coded track information
4. **ProposedNameFormatter** (`proposed_name_formatter.py`)
- Generates intelligent rename suggestions
- Pattern: `Title (Year) [Resolution Source Edition].ext`
- Sanitizes filenames (removes invalid characters)
5. **Utility Formatters**
- `SizeFormatter`: Human-readable file sizes
- `DateFormatter`: Timestamp formatting
- `DurationFormatter`: Duration in HH:MM:SS
- `ResolutionFormatter`: Resolution display
- `TextFormatter`: Text styling utilities
- `ExtensionFormatter`: File extension handling
- `SpecialInfoFormatter`: Edition/source formatting
- `HelperFormatter`: General formatting helpers
### Settings & Caching
#### Settings System (`renamer/settings.py`)
- JSON configuration stored in `~/.config/renamer/config.json`
- Configurable options:
- `mode`: "technical" or "catalog"
- `cache_ttl_extractors`: 21600s (6 hours)
- `cache_ttl_tmdb`: 21600s (6 hours)
- `cache_ttl_posters`: 2592000s (30 days)
- Automatic save/load with defaults
#### Cache System (`renamer/cache.py`)
- File-based cache with TTL support
- Location: `~/.cache/renamer/`
- Subdirectory organization (tmdb/, posters/, extractors/, general/)
- Supports JSON and pickle serialization
- In-memory cache for performance
- Image caching for TMDB posters
- Automatic expiration and cleanup
#### Caching Decorators (`renamer/decorators/caching.py`)
- `@cached` decorator for automatic method caching
- Integrates with Settings for TTL configuration
### UI Screens (`renamer/screens.py`)
Additional UI screens for user interaction:
1. **OpenScreen**: Directory selection dialog with validation
2. **HelpScreen**: Comprehensive help with key bindings
3. **RenameConfirmScreen**: File rename confirmation with error handling
4. **SettingsScreen**: Settings configuration interface
### Development Tools
#### Version Management (`renamer/bump.py`)
- `bump-version` command
- Auto-increments patch version in `pyproject.toml`
#### Release Automation (`renamer/release.py`)
- `release` command
- Runs: version bump → dependency sync → package build
## Key Features
### Current Features (v0.5.10)
- Recursive directory scanning for video files
- Tree view with expand/collapse navigation
- Dual-mode display (technical/catalog)
- Detailed metadata extraction from multiple sources
- Intelligent file renaming with preview
- TMDB integration with poster display
- Settings configuration UI
- Persistent caching with TTL
- Loading indicators and error handling
- Confirmation dialogs for file operations
- Color-coded information display
- Keyboard and mouse navigation
### Keyboard Commands
- `q`: Quit application
- `o`: Open directory
- `s`: Scan/rescan directory
- `f`: Refresh metadata for selected file
- `r`: Rename file with proposed name
- `p`: Toggle tree expansion
- `h`: Show help screen
- `^p`: Open command palette
- Settings menu via action bar
## Technology Stack
### Core Dependencies
- **textual** (≥6.11.0): TUI framework
- **pymediainfo** (≥6.0.0): Media track analysis
- **mutagen** (≥1.47.0): Embedded metadata
- **python-magic** (≥0.4.27): MIME detection
- **langcodes** (≥3.5.1): Language code handling
- **requests** (≥2.31.0): HTTP for TMDB API
- **rich-pixels** (≥1.0.0): Terminal image display
- **pytest** (≥7.0.0): Testing framework
### System Requirements
- Python 3.11 or higher
- UV package manager (recommended)
- MediaInfo library (system dependency for pymediainfo)
## Development Workflow
### Setup
```bash
# Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
# Clone and sync
cd /path/to/renamer
uv sync
# Run from source
uv run python renamer/main.py [directory]
```
### Development Commands
```bash
uv run renamer # Run installed version
uv run pytest # Run tests
uv run bump-version # Increment version
uv run release # Build release (bump + sync + build)
uv build # Build wheel/tarball
uv tool install . # Install as global tool
```
### Debugging
```bash
# Enable formatter logging
FORMATTER_LOG=1 uv run renamer /path/to/directory
# Creates formatter.log with detailed call traces
```
### Testing
- Test files in `renamer/test/`
- Sample filenames in `test/filenames.txt` and `test/test_filenames.txt`
- Test cases in `test/test_cases.json`
- Run with: `uv run pytest`
## Code Style & Standards
### Python Standards
- Type hints encouraged
- PEP 8 style guidelines
- Descriptive variable/function names
- Docstrings for classes and functions
- Pathlib for file operations
- Proper exception handling
### Architecture Patterns
- Extractor pattern: Each extractor focuses on one data source
- Formatter pattern: Formatters handle display logic, extractors handle data
- Separation of concerns: Data extraction → formatting → display
- Dependency injection: Extractors and formatters are modular
- Configuration management: Settings class for all config
### Best Practices
- Avoid over-engineering (keep solutions simple)
- Only add features when explicitly requested
- Validate at system boundaries only (user input, external APIs)
- Don't add unnecessary error handling for internal code
- Trust framework guarantees
- Delete unused code completely (no backwards-compat hacks)
## File Operations
### Directory Scanning
- Recursive search for supported video formats
- File tree representation with hierarchical structure
- Efficient tree updates on file operations
### File Renaming
1. Select file in tree
2. Press `r` to initiate rename
3. Review proposed name (shows current vs proposed)
4. Confirm with `y` or cancel with `n`
5. Tree updates in-place without full reload
### Metadata Caching
- First extraction cached for 6 hours
- TMDB data cached for 6 hours
- Posters cached for 30 days
- Force refresh with `f` command
- Cache invalidated on file rename
## API Integration
### TMDB API
- API key stored in `renamer/secrets.py`
- Search endpoint for movie lookup by title/year
- Image base URL for poster downloads
- Handles rate limiting and errors gracefully
- Falls back to filename data if API unavailable
## Project Files
### Documentation
- `README.md`: User-facing documentation
- `AI_AGENT.md`: AI agent instructions (legacy)
- `DEVELOP.md`: Developer guide
- `INSTALL.md`: Installation instructions
- `ToDo.md`: Task tracking
- `CLAUDE.md`: This file (AI assistant reference)
### Configuration
- `pyproject.toml`: Project metadata, dependencies, build config
- `uv.lock`: Locked dependencies
### Build Artifacts
- `dist/`: Built wheels and tarballs
- `build/`: Build intermediates
- `renamer.egg-info/`: Package metadata
## Known Issues & Limitations
### Current Limitations
- TMDB API requires internet connection
- Poster display requires terminal with image support
- Some special characters in filenames need sanitization
- Large directories may have initial scan delay
### Future Enhancements (See ToDo.md)
- Metadata editing capabilities
- Batch rename operations
- Advanced search and filtering
- Undo/redo functionality
- Plugin system for custom extractors/formatters
- Full genre name expansion (currently shows codes)
- Improved poster quality/display optimization
## Contributing Guidelines
### Making Changes
1. Read existing code and understand architecture
2. Check `ToDo.md` for pending tasks
3. Implement features incrementally
4. Test with real media files
5. Ensure backward compatibility
6. Update documentation
7. Update tests as needed
8. Run `uv run release` before committing
### Commit Standards
- Clear, descriptive commit messages
- Focus on "why" not "what"
- One logical change per commit
- Reference related issues/tasks
### Code Review Checklist
- [ ] Follows PEP 8 style
- [ ] Type hints added where appropriate
- [ ] No unnecessary complexity
- [ ] Tests pass (`uv run pytest`)
- [ ] Documentation updated
- [ ] No security vulnerabilities (XSS, injection, etc.)
- [ ] Efficient resource usage (no memory leaks)
## Security Considerations
- Input sanitization for filenames (see `ProposedNameFormatter`)
- No shell command injection risks
- Safe file operations (pathlib, proper error handling)
- TMDB API key should not be committed (stored in `secrets.py`)
- Cache directory permissions should be user-only
## Performance Notes
- In-memory cache reduces repeated extraction overhead
- File cache persists across sessions
- Tree updates optimized for rename operations
- TMDB requests throttled to respect API limits
- Large directory scans use async/await patterns
## Special Notes for AI Assistants
### When Adding Features
1. **Always read relevant files first** - Never modify code you haven't read
2. **Check ToDo.md** - See if feature is already planned
3. **Understand existing patterns** - Follow established architecture
4. **Test with real files** - Use actual media files for testing
5. **Update documentation** - Keep docs in sync with code
### When Debugging
1. **Enable formatter logging** - Use `FORMATTER_LOG=1` for detailed traces
2. **Check cache state** - Clear cache if stale data suspected
3. **Verify file permissions** - Ensure read/write access
4. **Test with sample filenames** - Use test fixtures first
### When Refactoring
1. **Maintain backward compatibility** - Unless explicitly breaking change
2. **Update tests** - Reflect refactored code
3. **Check all formatters** - Formatting is centralized
4. **Verify extractor chain** - Ensure data flow intact
### Common Pitfalls to Avoid
- Don't create new files unless absolutely necessary (edit existing)
- Don't add features beyond what's requested
- Don't over-engineer solutions
- Don't skip testing with real files
- Don't forget to update version number for releases
- Don't commit secrets or API keys
- Don't use deprecated Textual APIs
## Project History
### Evolution
- Started as simple file renamer
- Added metadata extraction (MediaInfo, Mutagen)
- Expanded to TUI with Textual framework
- Added filename parsing intelligence
- Integrated TMDB for catalog mode
- Added settings and caching system
- Implemented poster display with rich-pixels
- Added dual-mode interface (technical/catalog)
### Version Milestones
- 0.2.x: Initial TUI with basic metadata
- 0.3.x: Enhanced extractors and formatters
- 0.4.x: Added TMDB integration
- 0.5.x: Settings, caching, catalog mode, poster display
## Resources
### External Documentation
- [Textual Documentation](https://textual.textualize.io/)
- [PyMediaInfo Documentation](https://pymediainfo.readthedocs.io/)
- [Mutagen Documentation](https://mutagen.readthedocs.io/)
- [TMDB API Documentation](https://developers.themoviedb.org/3)
- [UV Documentation](https://docs.astral.sh/uv/)
### Internal Documentation
- Main README: User guide and quick start
- DEVELOP.md: Developer setup and debugging
- INSTALL.md: Installation methods
- AI_AGENT.md: Legacy AI instructions (historical)
- ToDo.md: Current task list
---
**Last Updated**: 2025-12-31
**For AI Assistant**: Claude (Anthropic)
**Project Maintainer**: sha
**Repository**: `/home/sha/bin/renamer`

123
DEVELOP.md
View File

@@ -2,6 +2,8 @@
This guide contains information for developers working on the Renamer project. This guide contains information for developers working on the Renamer project.
**Current Version**: 0.5.10
## Development Setup ## Development Setup
### Prerequisites ### Prerequisites
@@ -67,43 +69,85 @@ Enable detailed logging for formatter operations:
FORMATTER_LOG=1 uv run renamer /path/to/directory FORMATTER_LOG=1 uv run renamer /path/to/directory
``` ```
This creates `formatter.log` with: This creates `formatter.log` in the current directory with:
- Formatter call sequences and ordering - Formatter call sequences and ordering
- Input/output values for each formatter - Input/output values for each formatter
- Caller information (file and line number) - Caller information (file and line number)
- Any errors during formatting - Any errors during formatting
- Timestamp for each operation
### Cache Inspection
Cache is stored in `~/.cache/renamer/` with subdirectories:
- `extractors/`: Extractor results cache
- `tmdb/`: TMDB API response cache
- `posters/`: Downloaded poster images
- `general/`: General purpose cache
To clear cache:
```bash
rm -rf ~/.cache/renamer/
```
### Settings Location
Settings are stored in `~/.config/renamer/config.json`:
```json
{
"mode": "technical",
"cache_ttl_extractors": 21600,
"cache_ttl_tmdb": 21600,
"cache_ttl_posters": 2592000
}
```
## Architecture ## Architecture
The application uses a modular architecture: The application uses a modular architecture with clear separation of concerns:
### Core Application (`renamer/`)
- **app.py**: Main RenamerApp class (Textual App), tree management, file operations
- **main.py**: Entry point with argument parsing
- **constants.py**: Comprehensive constants (media types, sources, resolutions, editions)
- **settings.py**: Settings management with JSON persistence (`~/.config/renamer/`)
- **cache.py**: File-based caching system with TTL support (`~/.cache/renamer/`)
- **secrets.py**: API keys and secrets (TMDB)
### Extractors (`renamer/extractors/`) ### Extractors (`renamer/extractors/`)
- **MediaInfoExtractor**: Extracts detailed track information using PyMediaInfo Data extraction from multiple sources:
- **FilenameExtractor**: Parses metadata from filenames - **extractor.py**: MediaExtractor coordinator class
- **MetadataExtractor**: Extracts embedded metadata using Mutagen - **mediainfo_extractor.py**: PyMediaInfo for detailed track information
- **FileInfoExtractor**: Provides basic file information - **filename_extractor.py**: Regex-based filename parsing
- **DefaultExtractor**: Fallback extractor - **metadata_extractor.py**: Mutagen for embedded metadata
- **MediaExtractor**: Main extractor coordinating all others - **fileinfo_extractor.py**: Basic file information (size, dates, MIME)
- **tmdb_extractor.py**: The Movie Database API integration
- **default_extractor.py**: Fallback extractor
### Formatters (`renamer/formatters/`) ### Formatters (`renamer/formatters/`)
- **MediaFormatter**: Formats extracted data for display Display formatting and rendering:
- **ProposedNameFormatter**: Generates intelligent rename suggestions - **formatter.py**: Base formatter interface
- **TrackFormatter**: Formats video/audio/subtitle track information - **media_formatter.py**: Main formatter coordinating all format operations
- **SizeFormatter**: Formats file sizes - **catalog_formatter.py**: Catalog mode display (TMDB data, posters)
- **DateFormatter**: Formats timestamps - **proposed_name_formatter.py**: Intelligent rename suggestions
- **DurationFormatter**: Formats time durations - **track_formatter.py**: Video/audio/subtitle track formatting
- **ResolutionFormatter**: Formats video resolutions - **size_formatter.py**: Human-readable file sizes
- **TextFormatter**: Text styling utilities - **date_formatter.py**: Timestamp formatting
- **duration_formatter.py**: Duration in HH:MM:SS format
- **resolution_formatter.py**: Resolution display
- **extension_formatter.py**: File extension handling
- **special_info_formatter.py**: Edition/source formatting
- **text_formatter.py**: Text styling utilities
- **helper_formatter.py**: General formatting helpers
### Screens (`renamer/screens.py`) ### Screens (`renamer/screens.py`)
- **OpenScreen**: Directory selection dialog UI screens for user interaction:
- **HelpScreen**: Application help and key bindings - **OpenScreen**: Directory selection with validation
- **RenameConfirmScreen**: File rename confirmation dialog - **HelpScreen**: Comprehensive help with key bindings
- **RenameConfirmScreen**: File rename confirmation with preview
- **SettingsScreen**: Settings configuration UI
### Main Components ### Utilities
- **app.py**: Main TUI application - **decorators/caching.py**: Caching decorator for automatic method caching
- **main.py**: Entry point - **bump.py**: Version bump utility script
- **constants.py**: Application constants - **release.py**: Release automation (bump + sync + build)
## Testing ## Testing
@@ -133,9 +177,18 @@ uv tool uninstall renamer
## Code Style ## Code Style
The project uses standard Python formatting. Consider using tools like: The project follows Python best practices:
- **PEP 8**: Standard Python style guide
- **Type Hints**: Encouraged where appropriate
- **Docstrings**: For all classes and public methods
- **Descriptive Naming**: Clear variable and function names
- **Pathlib**: For all file operations
- **Error Handling**: Appropriate exception handling at boundaries
Consider using tools like:
- `ruff` for linting and formatting - `ruff` for linting and formatting
- `mypy` for type checking (if added) - `mypy` for type checking
- `black` for consistent formatting
## Contributing ## Contributing
@@ -146,4 +199,22 @@ The project uses standard Python formatting. Consider using tools like:
5. Run the release process: `uv run release` 5. Run the release process: `uv run release`
6. Submit a pull request 6. Submit a pull request
For more information, see the main [README.md](../README.md). ## Additional Documentation
For comprehensive project information:
- **[README.md](README.md)**: User guide and features
- **[CLAUDE.md](CLAUDE.md)**: Complete AI assistant reference
- **[AI_AGENT.md](AI_AGENT.md)**: AI agent instructions
- **[INSTALL.md](INSTALL.md)**: Installation methods
- **[ToDo.md](ToDo.md)**: Task list and priorities
## Project Resources
- **Cache Directory**: `~/.cache/renamer/`
- **Config Directory**: `~/.config/renamer/`
- **Test Files**: `renamer/test/`
- **Build Output**: `dist/` and `build/`
---
**Last Updated**: 2025-12-31

65
README.md
View File

@@ -1,18 +1,23 @@
# Renamer - Media File Renamer and Metadata Editor # Renamer - Media File Renamer and Metadata Viewer
A terminal-based (TUI) application for scanning directories, viewing media file details, and renaming files based on extracted metadata. Built with Python and Textual. 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 ## Features
- Recursive directory scanning for video files ### Core Capabilities
- Tree view navigation with keyboard and mouse support - **Dual Display Modes**: Switch between Technical (codec/track details) and Catalog (TMDB metadata with posters)
- Detailed metadata extraction from multiple sources (MediaInfo, filename parsing, embedded metadata) - **Recursive Directory Scanning**: Finds all video files in nested directories
- Intelligent file renaming with proposed names based on metadata - **Tree View Navigation**: Keyboard and mouse support with expand/collapse
- Color-coded information display - **Multi-Source Metadata**: Combines MediaInfo, filename parsing, embedded tags, and TMDB API
- Command-based interface with hotkeys - **Intelligent Renaming**: Proposes standardized names based on extracted metadata
- Extensible extractor and formatter system - **Persistent Settings**: Configurable mode and cache TTLs saved to `~/.config/renamer/`
- Support for video, audio, and subtitle track information - **Advanced Caching**: File-based cache with TTL (6h extractors, 6h TMDB, 30d posters)
- Confirmation dialogs for file operations - **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 ## Installation
@@ -48,14 +53,16 @@ renamer
renamer /path/to/media/directory renamer /path/to/media/directory
``` ```
### Commands ### Keyboard Commands
- **q**: Quit the application - **q**: Quit the application
- **o**: Open directory selection dialog - **o**: Open directory selection dialog
- **s**: Rescan current directory - **s**: Scan/rescan current directory
- **f**: Refresh metadata for selected file - **f**: Force refresh metadata for selected file (bypass cache)
- **r**: Rename selected file with proposed name - **r**: Rename selected file with proposed name
- **p**: Toggle tree expansion (expand/collapse all) - **p**: Toggle tree expansion (expand/collapse all)
- **h**: Show help screen - **h**: Show help screen
- **^p**: Open command palette (settings, mode toggle)
- **Settings**: Access via action bar (top-right corner)
### Navigation ### Navigation
- Use arrow keys to navigate the file tree - Use arrow keys to navigate the file tree
@@ -67,9 +74,14 @@ renamer /path/to/media/directory
### File Renaming ### File Renaming
1. Select a media file in the tree 1. Select a media file in the tree
2. Press **r** to initiate rename 2. Press **r** to initiate rename
3. Review the proposed new name 3. Review the proposed new name in the confirmation dialog
4. Press **y** to confirm or **n** to cancel 4. Press **y** to confirm or **n** to cancel
5. The file will be renamed and the tree updated automatically 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 ## Development
@@ -88,8 +100,19 @@ For development setup, architecture details, debugging information, and contribu
- .ogv - .ogv
## Dependencies ## Dependencies
- textual: TUI framework - **textual** ≥6.11.0: TUI framework
- pymediainfo: Detailed media track information - **pymediainfo** ≥6.0.0: Detailed media track information
- mutagen: Embedded metadata extraction - **mutagen** ≥1.47.0: Embedded metadata extraction
- python-magic: MIME type detection - **python-magic** ≥0.4.27: MIME type detection
- langcodes: Language code handling - **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

88
ToDo.md
View File

@@ -1,6 +1,8 @@
Project: Media File Renamer and Metadata Editor (Python TUI with Textual) Project: Media File Renamer and Metadata Viewer (Python TUI with Textual)
TODO Steps: **Current Version**: 0.5.10
## TODO Steps:
1. ✅ Set up Python project structure with UV package manager 1. ✅ Set up Python project structure with UV package manager
2. ✅ Install dependencies: textual, mutagen, pymediainfo, python-magic, pathlib for file handling 2. ✅ Install dependencies: textual, mutagen, pymediainfo, python-magic, pathlib for file handling
3. ✅ Implement recursive directory scanning for video files (*.mkv, *.avi, *.mov, *.mp4, *.wmv, *.flv, *.webm, etc.) 3. ✅ Implement recursive directory scanning for video files (*.mkv, *.avi, *.mov, *.mp4, *.wmv, *.flv, *.webm, etc.)
@@ -24,10 +26,11 @@ TODO Steps:
21. ✅ Add error handling for file operations and metadata extraction 21. ✅ Add error handling for file operations and metadata extraction
22. 🔄 Implement blue highlighting for changed parts in proposed filename display (show differences between current and proposed names) 22. 🔄 Implement blue highlighting for changed parts in proposed filename display (show differences between current and proposed names)
23. 🔄 Implement build script to exclude dev commands (bump-version, release) from distributed package 23. 🔄 Implement build script to exclude dev commands (bump-version, release) from distributed package
24. Implement metadata editing capabilities (future enhancement) 24. 📋 Implement metadata editing capabilities (future enhancement)
25. Add batch rename operations (future enhancement) 25. 📋 Add batch rename operations (future enhancement)
26. Add configuration file support (future enhancement) 26. 📋 Add plugin system for custom extractors/formatters (future enhancement)
27. Add plugin system for custom extractors/formatters (future enhancement) 27. 📋 Add advanced search and filtering capabilities (future enhancement)
28. 📋 Implement undo/redo functionality for file operations (future enhancement)
--- ---
@@ -60,9 +63,74 @@ TODO Steps:
### Phase 5: Poster Handling and Display ### Phase 5: Poster Handling and Display
15. ✅ Add poster caching (images in cache dir with 1-month TTL) 15. ✅ Add poster caching (images in cache dir with 1-month TTL)
16. ✅ Implement terminal image display (research rich-pixels or alternatives, add poster_display.py) 16. ✅ Implement terminal image display (using rich-pixels library)
### Phase 6: Polish and Documentation
17. ✅ Create comprehensive CLAUDE.md for AI assistants
18. ✅ Update all markdown documentation files
19. ✅ Ensure version consistency across all files
### Additional TODOs from Plan ### Additional TODOs from Plan
- Retrieve full movie details from TMDB (future) - 📋 Retrieve full movie details from TMDB (currently basic data only)
- Expand genres to full names instead of codes (future) - 📋 Expand genres to full names instead of codes (currently shows genre IDs)
- Optimize poster quality and display (future) - 📋 Optimize poster quality and display (improve image rendering)
- 📋 Add TV show support (currently movie-focused)
- 📋 Implement blue highlighting for filename differences
- 📋 Build script to exclude dev commands from distribution
---
## Recently Completed (v0.5.x)
### Version 0.5.10
- Complete media catalog mode implementation
- TMDB integration with poster display
- Settings system with persistent JSON storage
- Advanced caching with TTL support
- Dual-mode display (technical/catalog)
- Settings UI screen
### Version 0.4.x
- Enhanced extractor system
- TMDB extractor foundation
- Improved formatter architecture
### Version 0.3.x
- Expanded metadata extraction
- Multiple formatter types
- Special edition detection
### Version 0.2.x
- Initial TUI implementation
- Basic metadata extraction
- File tree navigation
- Rename functionality
---
## Development Priorities
### High Priority
1. 🔄 Blue highlighting for filename differences (UX improvement)
2. 🔄 Build script for clean distribution packages
3. 📋 Genre ID to name expansion (TMDB lookup)
### Medium Priority
1. 📋 Batch rename operations
2. 📋 Advanced search/filtering
3. 📋 TV show support
### Low Priority (Future)
1. 📋 Metadata editing
2. 📋 Plugin system
3. 📋 Undo/redo functionality
4. 📋 Configuration profiles
---
**Legend:**
- ✅ Completed
- 🔄 In Progress / Partially Complete
- 📋 Planned / Future Enhancement
**Last Updated**: 2025-12-31

2
pyproject.toml
View File

@@ -1,6 +1,6 @@
[project] [project]
name = "renamer" name = "renamer"
version = "0.5.10" version = "0.6.0"
description = "Terminal-based media file renamer and metadata viewer" description = "Terminal-based media file renamer and metadata viewer"
readme = "README.md" readme = "README.md"
requires-python = ">=3.11" requires-python = ">=3.11"

8
renamer/settings.py
View File

@@ -14,7 +14,7 @@ class Settings:
"cache_ttl_posters": 2592000, # 30 days in seconds "cache_ttl_posters": 2592000, # 30 days in seconds
} }
def __init__(self, config_dir: Path = None): def __init__(self, config_dir: Path | None = None):
if config_dir is None: if config_dir is None:
config_dir = Path.home() / ".config" / "renamer" config_dir = Path.home() / ".config" / "renamer"
self.config_dir = config_dir self.config_dir = config_dir
@@ -26,7 +26,7 @@ class Settings:
"""Load settings from file, using defaults if file doesn't exist.""" """Load settings from file, using defaults if file doesn't exist."""
if self.config_file.exists(): if self.config_file.exists():
try: try:
with open(self.config_file, 'r') as f: with open(self.config_file, "r") as f:
data = json.load(f) data = json.load(f)
# Validate and merge with defaults # Validate and merge with defaults
for key, default_value in self.DEFAULTS.items(): for key, default_value in self.DEFAULTS.items():
@@ -46,7 +46,7 @@ class Settings:
"""Save current settings to file.""" """Save current settings to file."""
try: try:
self.config_dir.mkdir(parents=True, exist_ok=True) self.config_dir.mkdir(parents=True, exist_ok=True)
with open(self.config_file, 'w') as f: with open(self.config_file, "w") as f:
json.dump(self._settings, f, indent=2) json.dump(self._settings, f, indent=2)
except IOError as e: except IOError as e:
print(f"Error: Could not save settings: {e}") print(f"Error: Could not save settings: {e}")
@@ -69,4 +69,4 @@ class Settings:
def get_all(self) -> Dict[str, Any]: def get_all(self) -> Dict[str, Any]:
"""Get all current settings.""" """Get all current settings."""
return self._settings.copy() return self._settings.copy()