A versatile multilingual modular Telegram bot with multiple features.

• User and permission management
• Plugin system with enable/disable functionality
• Task management and cancellation
• Help command for instructions
• Bot restart and update functionality
• Broadcast messages to all users

• Download files from URLs using aria2
• Download / upload Telegram files
• Upload files as documents or media
• Rename Telegram files
• Create and extract zip archives
• List archive contents

• Convert audio to voice messages
• Convert between audio formats
• Compress audio files
• Cut, split, and merge audio files
• Increase audio volume
• Set title and artist metadata
• Remove silence from audio

• Remove audio from videos
• Display video information
• Compress videos
• Encode videos to x265 format
• Extract video thumbnails
• Scale and resize videos
• Cut, split, and merge videos
• Extract subtitles from videos
• Replace audio in videos
• Convert videos to different formats
• Create a video from audio, and photo or subtitles

• Search and retrieve Quran ayahs and Sunnah Hadiths
• Search web using DuckDuckGo
• Search Wikipedia in multiple languages
• YouTube (and all sites supported by ytdlp) interactions (download full/segment from audio/video, playlists, subtitles)

• OCR (Optical Character Recognition) using Tesseract and Gemini
• PDF processing: text extraction, compression, page extraction, cropping, splitting, and merging
• Transcription (Wit/Whisper/Vosk + Gemini)
• Custom Gemini prompt on a replied file

• Execute shell commands
• View Telegram messages as JSON
• Generate MD5 hashes of Telegram files
• Create direct download links (planned)
• Instant Preview of web articles
• Readability extraction for web pages

• Start the bot by sending /start in private or adding it to a group.
• Use /help to get a list of available commands and their usage.
• For file conversions, simply send a file to the bot and follow the prompts.
• Use inline queries for web searches by typing @your_bot_username followed by your search query. You can list all inline command using @your_bot_username help.

Before setting up the bot:

1. Create a .env and fill in the required information as defined in mise.toml:

   API_ID="1234567"
   API_HASH="0123456789abcdef0123456789abcdef"
   BOT_TOKEN="1234567890:abcdefghijklmnopqrstuvwxyz0123456789"
   BOT_ADMINS='123456,123456,123456'
   # Optional (AI/Gemini)
   LLM_GEMINI_KEY="..."
   # Optional (Whisper via Groq)
   GROQ_API_KEY="..."
   # Optional (tafrigh wit)
   WIT_CLIENT_ACCESS_TOKENS="..."

1. Make sure you have Docker and Docker Compose installed.
2. Clone this repository.
3. Run the following command in the project directory:

docker compose up --build -d

1. Install system dependencies:
   • FFmpeg
   • aria2
   • Any other system-level dependencies (refer to the Dockerfile for a complete list)
2. Install tools + Python (recommended, Python 3.13+):
   • mise install
3. Install Python dependencies:
   • uv sync --dev
4. Run the bot:

uv run -m src

• Telethon Library
• FFmpeg
• aria2
• yt-dlp
• orjson
• regex
• search-engine-parser
• Vosk
• PyMuPDF
• OCRmyPDF
• tafrigh
• tahweel
• Plate

• Quran.com
• Sunnah.one
• Exchange Rate API

This project uses several tools to streamline the development process:

mise is used for managing project-level dependencies and environment variables. mise helps ensure consistent development environments across different machines.

To get started with mise:

1. Install mise by following the instructions on the official website.
2. Run mise install in the project root to set up the development environment.

UV is used for dependency management and packaging. It provides a clean, version-controlled way to manage project dependencies.

To set up the project with UV:

1. Install UV by following the instructions on the official website.
2. Run uv sync to install project dependencies.

Jurigged is used for live code reloading during development. This allows you to see changes in your code immediately without manually restarting the application.

To use Jurigged:

1. Make sure you have installed the project dependencies using UV, including dev dependencies uv sync --dev.
2. Run the bot with Jurigged:

uv run jurigged -v -m src

• Plate library is used to translate the bot's messages.
• Translations are stored as JSON files in the src/i18n/locales directory, the default locale is en_US.
• To add a new language, create a new JSON file in the src/i18n/locales directory, with the corresponding language code, and translate the messages to that language.
• Set the BOT_LANGUAGE environment variable to the desired language code.