{"id":48619725,"url":"https://github.com/christt105/mnamer-telegram","last_synced_at":"2026-06-14T11:00:33.111Z","repository":{"id":346899812,"uuid":"1071613997","full_name":"christt105/mnamer-telegram","owner":"christt105","description":"Telegram bot that automates media library organization using mnamer with interactive approval workflows.","archived":false,"fork":false,"pushed_at":"2026-03-27T20:11:26.000Z","size":341,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-09T03:35:14.254Z","etag":null,"topics":["rename","telegram","telegrambot"],"latest_commit_sha":null,"homepage":"https://hub.docker.com/r/christt105/mnamer-telegram","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/christt105.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"christt105","patreon":null,"open_collective":null,"ko_fi":"christt105","tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2025-10-07T15:23:54.000Z","updated_at":"2026-03-28T15:18:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/christt105/mnamer-telegram","commit_stats":null,"previous_names":["christt105/mnamer-telegram"],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/christt105/mnamer-telegram","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christt105%2Fmnamer-telegram","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christt105%2Fmnamer-telegram/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christt105%2Fmnamer-telegram/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christt105%2Fmnamer-telegram/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/christt105","download_url":"https://codeload.github.com/christt105/mnamer-telegram/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/christt105%2Fmnamer-telegram/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34318525,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["rename","telegram","telegrambot"],"created_at":"2026-04-09T03:03:35.191Z","updated_at":"2026-06-14T11:00:33.100Z","avatar_url":"https://github.com/christt105.png","language":"C#","funding_links":["https://github.com/sponsors/christt105","https://ko-fi.com/christt105"],"categories":[],"sub_categories":[],"readme":"# mnamer-telegram\n\n[![Docker Image Version (latest semver)](https://img.shields.io/docker/v/christt105/mnamer-telegram?label=Docker)](https://hub.docker.com/r/christt105/mnamer-telegram)\n[![GitHub stars](https://img.shields.io/github/stars/christt105/mnamer-telegram?style=social)](https://github.com/christt105/mnamer-telegram)\n\n- **GitHub Repository**: [https://github.com/christt105/mnamer-telegram](https://github.com/christt105/mnamer-telegram)\n- **Docker Image**: [christt105/mnamer-telegram](https://hub.docker.com/r/christt105/mnamer-telegram)\n\nA Telegram bot to automate the organization of your media library using the powerful [mnamer](https://github.com/jkwill87/mnamer) tool.\n\n![Screenshot Start](./docs/HelpAndStartCommand.png)\n\n\u003e [!WARNING]  \n\u003e **Disclaimer:** This tool handles file movements and renaming. I am **not responsible for any data loss** or files being moved to incorrect locations. It is highly recommended to perform a test with dummy files or a backup before running it on your primary library.\n\n\u003e [!IMPORTANT]  \n\u003e **Configuration Complexity:** Setting up Docker volumes and environment variables correctly can be complex depending on your OS and permissions. If you encounter any issues or have questions, please **open an issue** in this repository.\n\n## Features\n\n- **Watch Folder Monitoring**: Automatically detects new video files in your configured download directory.\n- **Automatic Organization**: Uses `mnamer` to rename and move files to your library (Movies/TV Shows).\n- **Batch Scanning**: `/search` scans the whole watch folder, groups what it finds (all episodes of a series together, all movies together), and lets you move everything — or one group — with a single tap.\n- **Interactive Telegram Interface**: \n    - Receive notifications when files are processed.\n    - **Approve Moves**: One-click confirmation to move files.\n    - **Manual Correction**: Reply with `tmdb \u003cid\u003e` or `tvdb \u003cid\u003e` if the detection is wrong.\n\n![Screenshot Scan](./docs/ExampleRename.png)\n\n## Setup \u0026 Deployment\n\nThe recommended way to run this bot is via **Docker Compose**.\n\n### Prerequisites\n\n- **Docker** and **Docker Compose** installed.\n- A **Telegram Bot Token** (create your bot with [@BotFather](https://t.me/BotFather)).\n- Your **Telegram User ID** (from [@username_to_id_bot](https://t.me/username_to_id_bot)).\n\n### Obtaining Telegram API Credentials\n\nTo get your `TELEGRAM_API_ID` and `TELEGRAM_API_HASH`:\n\n1.  Log in to your Telegram account at [my.telegram.org](https://my.telegram.org).\n2.  Go to **API development tools**.\n3.  Fill out the form (you can use any dummy data for URL/Description).\n4.  Click **Create application**.\n5.  Copy the `App api_id` and `App api_hash` values.\n\n*For more details, see the [official guide](https://core.telegram.org/api/obtaining_api_id).*\n\n### Configuration\n\n1.  **Clone the repository**.\n2.  **Create a `.env` file** in the root directory (you can copy [`.env.example`](.env.example) as a starting point):\n\n## Environment Variables\n\n| Variable | Description | Default value |\n|---|---|---|\n| TELEGRAM_API_ID | Telegram API ID | n/a |\n| TELEGRAM_API_HASH | Telegram API Hash | n/a |\n| TELEGRAM_BOT_TOKEN | Bot token | n/a |\n| TELEGRAM_AUTH_USER_ID | Authorized user ID | n/a |\n| WATCH_DIR | Watch folder for scanning | `/data/watch` (in code) |\n| MOVIES_DIR | Movies output folder | `/data/movies` (in code) |\n| SHOWS_DIR | Shows output folder | `/data/shows` (in code) |\n| MOVIE_FORMAT | Movie filename format string for mnamer | `{name} ({year}){extension}` |\n| EPISODES_FORMAT | Episode filename format string for mnamer | `{series} S{season:02}E{episode:02}{extension}` |\n| MOVIE_DIRECTORY | Movie output directory template (relative to `MOVIES_DIR`) | `{name} ({year}) [tmdbid-{id_tmdb}]` |\n| EPISODE_DIRECTORY | Episode output directory template (relative to `SHOWS_DIR`) | `{series} [tvdbid-{id_tvdb}]/Season {season:02}` |\n| LANGUAGE | mnamer/movie language code | `en` |\n| PUID | User ID for file permissions | `1000` |\n| PGID | Group ID for file permissions | `1000` |\n\n3.  **Review `docker-compose.yml`** (an example file is included in the repository):\n    \n    \u003e **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.\n\n    ```yaml\n    services:\n      bot-mnamer:\n        image: christt105/mnamer-telegram:latest\n        restart: unless-stopped\n        env_file: .env\n        volumes:\n          - ./appdata:/data            # Database location\n          - /mnt/data:/media           # Single volume for all media\n    ```\n    *In this example, your host `/mnt/data` should contain `downloads`, `movies`, and `shows` folders.*\n\n### Running\n\n\u003e [!WARNING]  \n\u003e **If you run the container as a non-root user (using `PUID` and `PGID`):** Ensure the mapped directories (like `./appdata` and your media folders) already exist on your host system **before** starting the container. If Docker creates them automatically, they will be owned by `root`, causing the bot to silently fail due to database permission errors. The bot will **not** send an error message to Telegram in this case; you will only see `SQLite Error 14` or permission denied errors if you check the container logs.\n\n1. **Create the data directory** (and ensure it has correct permissions for your PUID/PGID):\n\n```bash\nmkdir -p ./appdata\n```\n\n2. **Start the bot container:**\n\n```bash\ndocker compose up -d\n```\n\nView logs:\n\n```bash\ndocker compose logs -f\n```\n\n## ⚠️ Known Limitations \u0026 Docker Compatibility\n\nThe real-time folder monitoring (`FileSystemWatcher`) is primarily designed and tested for **Linux hosts**.\n\nIf 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:\n\n- [File System Watch issues on Docker mounts (Docker Forums)](https://forums.docker.com/t/file-system-watch-does-not-work-with-mounted-volumes/12038/18)\n\n\n## mnamer formatting\n\n`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.\n\nFor format details and examples, see:\n\n- https://github.com/jkwill87/mnamer/wiki/Formatting\n\n## Usage\n\n1.  **Automatic**: The bot watches `/downloads` (mapped path). When a video file is detected, it will message you on Telegram.\n2.  **Scan \u0026 batch move**: Send `/search` to scan the watch folder. The bot identifies every file, groups episodes by series and movies together, and replies with a summary. From there you can:\n    - **✅ Move all** — move everything that was identified in one tap.\n    - **Per-group move** — move just one series or all movies (shown when there is more than one group).\n    - **❌ Dismiss** — close the scan without moving anything.\n    Files that can't be identified are sent individually so you can correct them.\n3.  **Corrections**: Reply to any message with `tmdb \u003cid\u003e` or `tvdb \u003cid\u003e` to force a match.\n\n## Contributions\n\nRefactors, features, and pull requests are welcome!\n\n### Support the Project\n\nIf you find this bot useful, please consider starring the repository! ⭐\n\n[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/christt105)\n\n## Attributions\n\nThis project heavily relies on and gratefully acknowledges:\n\n- **[mnamer](https://github.com/jkwill87/mnamer)**: The core media organization tool.\n- **[TheMovieDB (TMDB)](https://www.themoviedb.org/)**: For movie metadata.\n- **[TheTVDB](https://thetvdb.com/)**: For TV show metadata.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristt105%2Fmnamer-telegram","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchristt105%2Fmnamer-telegram","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchristt105%2Fmnamer-telegram/lists"}