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.