christt105/mnamer-telegram repository overview

⁠mnamer-telegram

A Telegram bot to automate the organization of your media library using the powerful mnamer⁠ tool.

⁠Features

• Watch Folder Monitoring: Automatically detects new video files in your configured download directory.
• Automatic Organization: Uses mnamer to rename and move files to your library (Movies/TV Shows).
• Interactive Telegram Interface:
  • Receive notifications when files are processed.
  • Approve Moves: One-click confirmation to move files.
  • Manual Correction: Reply with tmdb <id> or tvdb <id> if the detection is wrong.

⁠Setup & Deployment

The recommended way to run this bot is via Docker Compose.

⁠Prerequisites

• Docker and Docker Compose installed.
• A Telegram Bot Token (create your bot with @BotFather⁠).
• Your Telegram User ID (from @username_to_id_bot⁠).

⁠Obtaining Telegram API Credentials

To get your TELEGRAM_API_ID and TELEGRAM_API_HASH:

1. Log in to your Telegram account at my.telegram.org⁠.
2. Go to API development tools.
3. Fill out the form (you can use any dummy data for URL/Description).
4. Click Create application.
5. Copy the App api_id and App api_hash values.

For more details, see the official guide⁠.

⁠Configuration

1. Clone the repository.
2. Create a .env file in the root directory (you can copy .env.example⁠ as a starting point):

⁠Environment Variables

1. Review docker-compose.yml (an example file is included in the repository):

   Performance Tip: Map a single volume (e.g., /mnt/data:/media) containing both your downloads and library folders. This allows the bot to move files atomically (without copying) when directories are on the same volume.

   services:
     bot-mnamer:
       image: christt105/mnamer-telegram:latest
       restart: unless-stopped
       env_file: .env
       volumes:
         - ./appdata:/data            # Database location
         - /mnt/data:/media           # Single volume for all media
   

   Copy

   In this example, your host /mnt/data should contain downloads, movies, and shows folders.

⁠Running

Start the bot container:

docker compose up -d

View logs:

docker compose logs -f

⁠⚠️ Known Limitations & Docker Compatibility

The real-time folder monitoring (FileSystemWatcher) is primarily designed and tested for Linux hosts.

If you are running Docker on Windows or macOS, host file events may not propagate correctly into the container. Use the /search command to scan manually, or check this link for more information:

• File System Watch issues on Docker mounts (Docker Forums)⁠

⁠mnamer formatting

mnamer-telegram uses mnamer format strings for MOVIE_FORMAT, EPISODES_FORMAT, MOVIE_DIRECTORY, and EPISODE_DIRECTORY. You can customize these values in your .env file.

For format details and examples, see:

• https://github.com/jkwill87/mnamer/wiki/Formatting⁠

⁠Usage

1. Automatic: The bot watches /downloads (mapped path). When a video file is detected, it will message you on Telegram.
2. Scan: Send /search to the bot to scan the watch folder for existing files.
3. Corrections: Reply to any message with tmdb <id> or tvdb <id> to force a match.

⁠Contributions

Refactors, features, and pull requests are welcome!

⁠Support the Project

If you find this bot useful, please consider starring the repository! ⭐

⁠Attributions

This project heavily relies on and gratefully acknowledges:

• mnamer⁠: The core media organization tool.
• TheMovieDB (TMDB)⁠: For movie metadata.
• TheTVDB⁠: For TV show metadata.