gonamer

README

GoNamer

GoNamer is a powerful media file renaming tool that uses the TMDB API to automatically organize and rename your movie and TV show files based on accurate metadata.

Features

• 🎬 Automatic movie and TV show recognition
• 🔍 Smart title detection with fuzzy matching
• 📺 Episode and season number detection
• 🎯 TMDB API integration for accurate metadata
• 🔄 Concurrent processing for better performance
• 💾 Integrated caching system
• 📝 Customizable naming patterns
• 🚀 Dry-run mode for safe testing
• 🌐 Multi-language support
• 🔒 Safe renaming with conflict prevention

Installation

Using Go

go install github.com/nouuu/gonamer/cmd@latest

From Source

git clone https://github.com/nouuu/gonamer.git
cd gonamer
make install

Package Managers

Coming soon:

• Homebrew
• APT
• RPM
• AUR

Quick Start

1. Set your TMDB API key:

export TMDB_API_KEY=your_api_key

1. Run GoNamer:

gonamer /path/to/media

Configuration

GoNamer can be configured using environment variables or a configuration file (coming soon):

TMDB_API_KEY=your_key       # Required
MEDIA_PATH=./              # Path to scan
RECURSIVE=true            # Scan subdirectories
INCLUDE_NOT_FOUND=false  # Include unmatched files
DRY_RUN=true            # Test without renaming
MOVIE_PATTERN="{name} - {year}{extension}"
TVSHOW_PATTERN="{name} - {season}x{episode}{extension}"
TYPE=movie             # movie or tvshow
MAX_RESULTS=5         # Max suggestions per file
QUICK_MODE=false     # Skip confirmation

Usage Examples

Movies

# Scan movies with default pattern
gonamer /path/to/movies

# Custom pattern with dry run
DRY_RUN=true MOVIE_PATTERN="{name} ({year}){extension}" gonamer /movies

TV Shows

# Scan TV shows
TYPE=tvshow gonamer /path/to/shows

# Custom episode pattern
TVSHOW_PATTERN="{name} - S{season}E{episode} - {episode_title}{extension}" gonamer /shows

Development

Prerequisites

• Go 1.22 or higher
• Make
• TMDB API key

Building

make build

Testing

make test

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Roadmap 🗺️

✅ Completed Features

• Basic CLI interface
• TMDB API integration
• Movie renaming support
• TV show renaming support
• Environment-based configuration
• Cache system with Ristretto
• Concurrent file processing
• Custom naming patterns
• Interactive mode
• Dry-run support

🚀 Current Focus

• Prepare for Github with CI implementation
  • Setup GitHub Actions workflows
  • Implement comprehensive testing
  • Add security checks
  • Configure automated releases
• Migrate from .env to config.yml file
  • Design YAML configuration structure
  • Implement configs file loading
  • Add validation layer
• Enhance CLI with Cobra framework
  • Migrate to Cobra commands
  • Add command documentation
  • Implement config path override
• Improve TV Show Processing
  • Implement folder-based processing
  • Add season folder structure support
  • Improve episode detection

🔮 Future Improvements

• Enhanced User Experience

  • Better suggestion selection UI
  • Progress bars for batch operations
  • Preview mode with detailed changes
  • Summary report after operations

• Advanced File Management

  • Cache for previously processed files
  • Handling of subtitle files
  • Support for multi-episode files
  • Automatic creation of season folders

• Pattern System Enhancement

  • Visual pattern builder
  • More naming variables (quality, audio, etc.)
  • Per-folder pattern configuration
  • Pattern validation and testing

• API Integration

  • Support for additional APIs (IMDB, TVMaze)
  • Automatic API failover
  • Better metadata matching
  • Extended language support

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with love using Go
• Powered by TMDB API
• Inspired by the need for better media organization

---

Made with ❤️ by nouuu