Multi-Purpose Telegram Bot
A versatile multilingual modular Telegram bot with multiple features.
Features
Bot Management
- 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
File Management
- Download files from URLs using aria2
- Download / upload Telegram files
- Upload files as documents or media
- Rename Telegram files
Audio Processing
- 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
Video Processing
- 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
Web Interactions
- 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 audio/video, playlists, subtitles)
Text, Document, and Audio Processing
- OCR (Optical Character Recognition) using Tesseract and Google
- PDF processing: text extraction, compression, page extraction, cropping, splitting, and merging
- Transcription
Utility Functions
- Execute shell commands
- View Telegram messages as JSON
- Generate MD5 hashes of Telegram files
- Create direct download links (planned)
- Instant Preview of web articles
Usage
- 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
.
Setup
Before setting up the bot:
- Create a
.env
and fill in the required information as defined in [mise.toml] env section:
API_ID="1234567"
API_HASH="0123456789abcdef0123456789abcdef"
BOT_TOKEN="1234567890:abcdefghijklmnopqrstuvwxyz0123456789"
BOT_ADMINS='123456,123456,123456'
Using Docker (Recommended)
- Make sure you have Docker and Docker Compose installed.
- Clone this repository.
- Run the following command in the project directory:
docker compose up --build -d
Without Docker
- Ensure you have Python 3.12+ and pip v19+ or poetry installed.
- Clone the repository.
- Install dependencies:
- Using poetry:
poetry install
- Using pip:
pip install .
- Install system dependencies:
- FFmpeg
- aria2
- Any other system-level dependencies (refer to the Dockerfile for a complete list)
- Run the bot:
python3 -m src
Acknowledgements
Libraries, Tools, etc
Resources
Development
This project uses several tools to streamline the development process:
mise
We use mise for managing project-level dependencies and environment variables. mise helps
ensure consistent development environments across different machines.
To get started with mise:
- Install mise by following the instructions on the official website.
- Run
mise install
in the project root to set up the development environment.
Poetry
Poetry is used for dependency management and packaging. It provides a clean,
version-controlled way to manage project dependencies.
To set up the project with Poetry:
- Install Poetry by following the instructions on the official website.
- Run
poetry install
to install project dependencies.
Jurigged for Live Reload
We use Jurigged for live code reloading during development. This allows you to
see changes in your code immediately without manually restarting the application.
To use Jurigged:
- Make sure you have installed the project dependencies using Poetry, including dev
dependencies poetry install --with dev
.
- Run the bot with Jurigged:
poetry run jurigged -v -m src
Internationalization (i18n)
- We use Plate library 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.