sHa
60f32a7e8c
- Deleted the `renamer.decorators` package, including `caching.py` and `__init__.py`, to streamline the codebase. - Updated tests to reflect changes in import paths for caching decorators. - Added a comprehensive changelog to document major refactoring efforts and future plans. - Introduced an engineering guide detailing architecture, core components, and development setup.
183 lines
3.7 KiB
Markdown
183 lines
3.7 KiB
Markdown
# Renamer - Media File Renamer and Metadata Viewer
|
|
|
|
**Version**: 0.7.0-dev
|
|
|
|
A powerful Terminal User Interface (TUI) for managing media collections. View detailed metadata, browse TMDB catalog with posters, and intelligently rename files.
|
|
|
|
> **📘 For complete documentation, see [ENGINEERING_GUIDE.md](ENGINEERING_GUIDE.md)**
|
|
|
|
---
|
|
|
|
## Features
|
|
|
|
- **Dual Display Modes**: Technical (codecs/tracks) or Catalog (TMDB with posters)
|
|
- **Multi-Source Metadata**: MediaInfo, filename parsing, embedded tags, TMDB API
|
|
- **Intelligent Renaming**: Standardized names from metadata
|
|
- **Advanced Caching**: 6h extractors, 6h TMDB, 30d posters
|
|
- **Terminal Posters**: View movie posters in your terminal
|
|
- **Tree View Navigation**: Keyboard and mouse support
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
### Installation
|
|
|
|
```bash
|
|
# Install UV
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
|
|
# Install Renamer
|
|
cd /path/to/renamer
|
|
uv sync
|
|
uv tool install .
|
|
```
|
|
|
|
See [INSTALL.md](INSTALL.md) for detailed installation instructions.
|
|
|
|
### Usage
|
|
|
|
```bash
|
|
# Scan current directory
|
|
renamer
|
|
|
|
# Scan specific directory
|
|
renamer /path/to/media
|
|
```
|
|
|
|
---
|
|
|
|
## Keyboard Commands
|
|
|
|
| Key | Action |
|
|
|-----|--------|
|
|
| `q` | Quit |
|
|
| `o` | Open directory |
|
|
| `s` | Scan/rescan |
|
|
| `f` | Refresh metadata |
|
|
| `r` | Rename file |
|
|
| `m` | Toggle mode (technical/catalog) |
|
|
| `p` | Toggle tree expansion |
|
|
| `h` | Show help |
|
|
| `Ctrl+S` | Settings |
|
|
| `Ctrl+P` | Command palette |
|
|
|
|
---
|
|
|
|
## Display Modes
|
|
|
|
### Technical Mode
|
|
- Video tracks (codec, bitrate, resolution, frame rate)
|
|
- Audio tracks (codec, channels, sample rate, language)
|
|
- Subtitle tracks (format, language)
|
|
- File information (size, modification time, path)
|
|
|
|
### Catalog Mode
|
|
- TMDB title, year, rating
|
|
- Overview/description
|
|
- Genres
|
|
- Poster image (if terminal supports)
|
|
- Technical metadata
|
|
|
|
Toggle with `m` key.
|
|
|
|
---
|
|
|
|
## File Renaming
|
|
|
|
**Proposed Format**: `Title (Year) [Resolution Source Edition].ext`
|
|
|
|
**Example**: `The Matrix (1999) [1080p BluRay].mkv`
|
|
|
|
1. Press `r` on selected file
|
|
2. Review proposed name
|
|
3. Confirm with `y` or cancel with `n`
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
**Location**: `~/.config/renamer/config.json`
|
|
|
|
```json
|
|
{
|
|
"mode": "technical",
|
|
"cache_ttl_extractors": 21600,
|
|
"cache_ttl_tmdb": 21600,
|
|
"cache_ttl_posters": 2592000
|
|
}
|
|
```
|
|
|
|
Access via `Ctrl+S` or edit file directly.
|
|
|
|
---
|
|
|
|
## Requirements
|
|
|
|
- **Python**: 3.11+
|
|
- **UV**: Package manager
|
|
- **MediaInfo**: System library (for technical metadata)
|
|
- **Internet**: For TMDB catalog mode
|
|
|
|
---
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
renamer/
|
|
├── app.py # Main TUI application
|
|
├── services/ # Business logic
|
|
├── extractors/ # Metadata extraction
|
|
├── formatters/ # Display formatting
|
|
├── utils/ # Shared utilities
|
|
├── cache/ # Caching subsystem
|
|
└── constants/ # Configuration constants
|
|
```
|
|
|
|
See [ENGINEERING_GUIDE.md](ENGINEERING_GUIDE.md) for complete architecture documentation.
|
|
|
|
---
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Setup
|
|
uv sync --extra dev
|
|
|
|
# Run tests
|
|
uv run pytest
|
|
|
|
# Run from source
|
|
uv run renamer [directory]
|
|
```
|
|
|
|
See [DEVELOP.md](DEVELOP.md) for development documentation.
|
|
|
|
---
|
|
|
|
## Documentation
|
|
|
|
- **[ENGINEERING_GUIDE.md](ENGINEERING_GUIDE.md)** - Complete technical reference
|
|
- **[INSTALL.md](INSTALL.md)** - Installation instructions
|
|
- **[DEVELOP.md](DEVELOP.md)** - Development guide
|
|
- **[CHANGELOG.md](CHANGELOG.md)** - Version history
|
|
- **[CLAUDE.md](CLAUDE.md)** - AI assistant reference
|
|
|
|
---
|
|
|
|
## License
|
|
|
|
Not specified
|
|
|
|
---
|
|
|
|
## Credits
|
|
|
|
- Built with [Textual](https://textual.textualize.io/)
|
|
- Metadata from [MediaInfo](https://mediaarea.net/en/MediaInfo)
|
|
- Catalog data from [TMDB](https://www.themoviedb.org/)
|
|
|
|
---
|
|
|
|
**For complete documentation, see [ENGINEERING_GUIDE.md](ENGINEERING_GUIDE.md)**
|