Skip to content

About

An advanced telegram bot to make media group/album from individual files

Resources

Stars

2 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

📸 Album Maker Bot

An intelligent, asynchronous Telegram bot that seamlessly aggregates individual photos, videos, animations, and documents into unified media albums.

Python 3.10+ Kurigram Docker License: MIT


Album Maker Bot Banner

🌟 Overview

Forwarding or sending dozens of photos and videos to Telegram chats individually creates spam and cluttered conversation histories. Album Maker Bot solves this by operating as an automated media aggregator.

Simply drop your photos, videos, GIFs, or document media into the bot chat. The bot queues them per user, listens for an inactivity cooldown or volume threshold, automatically formats them into standard Telegram Media Groups (up to 10 items per album), and dispatches them with rate-limit protection.


✨ Features

  • ⚡ Automated Inactivity Cooldown: Starts a countdown timer (AUTO_SEND_DELAY) upon receiving media. If no further items arrive, the album automatically sends.
  • 🎯 Threshold Trigger: Instantly dispatches an album once the queue reaches the configured limit (AUTO_SEND_THRESHOLD, default & max: 10).
  • 🔄 Unlimited Queue & Auto-Chunking: Have 30 items? The bot slices queues exceeding 10 items into consecutive batches of 10, draining the queue without data loss.
  • 🛡️ FloodWait & Rate-Limit Shielding: Sleeps 1.5 seconds between multi-batch chunks to prevent Telegram API FloodWait bans.
  • 🔒 Per-User Concurrency Locks: Uses asyncio.Lock per user to guarantee that concurrent uploads and timer triggers never interleave or corrupt batches.
  • 🧠 Smart Single-Item Fallback: If only a single photo or video is sent, the bot gracefully switches to send_photo / send_video to prevent Telegram API album errors.
  • 🏷️ First-Item Caption Preservation: The caption of your first uploaded item is seamlessly assigned as the album's primary caption.
  • 📦 Broad Format Support:
    • 🖼️ Photos (JPEG, PNG, WEBP)
    • 🎥 Videos (MP4, MKV, MOV)
    • 🎞️ Animations & GIFs
    • 📄 Documents with image/* and video/* MIME types

🏗️ Architecture & Workflow

flowchart TD
    A([User Sends Media]) --> B{Supported Type?}
    B -- No --> C[Send Warning: Unsupported Document]
    B -- Yes --> D[Add Item to User Queue]
    
    D --> E{Queue Count >= Threshold?}
    E -- Yes --> F[Trigger send_album_for_user]
    E -- No --> G[Start / Reset Inactivity Timer]
    
    G -->|Timer Expires| F
    
    subgraph Dispatch [Queue Drainage Engine]
        F --> H[Acquire Per-User asyncio.Lock]
        H --> I{Items in Queue?}
        I -- Single Item --> J[Send single Photo / Video]
        I -- 2 to 10 Items --> K[Send Media Group Album]
        I -- > 10 Items --> L[Slice First 10 Items -> Send Album]
        L --> M[Wait 1.5s Flood Delay]
        M --> I
        J --> N[Release Lock & Clear Queue]
        K --> N
    end
Loading

🕹️ Bot Commands

Command Description
/start Displays the bot introduction banner, configured parameters, and guide.
/send_album Manually flushes and sends the current pending queue immediately.
/status Returns the number of media items currently buffered in your queue.
/cancel Clears your active media queue and aborts any active countdown timer.

⚙️ Configuration

Settings are managed in config.py and can be overridden using environment variables:

Variable Type Default Description
API_ID int 123456 Your Telegram API ID from my.telegram.org.
API_HASH str "your_api_hash" Your Telegram API Hash from my.telegram.org.
BOT_TOKEN str None Bot token generated by @BotFather.
AUTO_SEND_THRESHOLD int 10 Media count threshold before auto-sending (Telegram hard limit: 10).
AUTO_SEND_DELAY float 3.0 Seconds of inactivity before auto-dispatching the album.

🚀 Deployment Guide

Option 1: Docker Compose (Recommended)

  1. Clone the repository:

    git clone https://github.com/prono69/Album-Maker-Bot.git
    cd Album-Maker-Bot
  2. Configure your credentials: Edit config.py or create a .env file with your credentials:

    BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrsTUVwxyz
    API_ID=1234567
    API_HASH=your_telegram_api_hash
    AUTO_SEND_THRESHOLD=10
    AUTO_SEND_DELAY=3.0
  3. Start the container:

    docker compose up -d --build
  4. Monitor logs:

    docker compose logs -f

Option 2: Local / Virtual Environment

  1. Clone & enter directory:

    git clone https://github.com/prono69/Album-Maker-Bot.git
    cd Album-Maker-Bot
  2. Create and activate a virtual environment:

    python3 -m venv venv
    source venv/bin/activate  # On Windows: venv\Scripts\activate
  3. Install dependencies:

    pip install -r requirements.txt
  4. Set configuration: Set environment variables or update config.py:

    export BOT_TOKEN="your_bot_token_here"
    export API_ID=123456
    export API_HASH="your_api_hash"
  5. Run the bot:

    python album_bot_auto.py

Option 3: Systemd Service (Linux VPS)

To keep the bot running persistently in the background:

  1. Create a service file:

    sudo nano /etc/systemd/system/album-bot.service
  2. Paste the following configuration:

    [Unit]
    Description=Telegram Album Maker Bot
    After=network.target
    
    [Service]
    Type=simple
    User=root
    WorkingDirectory=/path/to/Album-Maker-Bot
    ExecStart=/path/to/Album-Maker-Bot/venv/bin/python album_bot_auto.py
    Restart=always
    RestartSec=5
    Environment=BOT_TOKEN=your_token_here
    Environment=AUTO_SEND_THRESHOLD=10
    Environment=AUTO_SEND_DELAY=3.0
    
    [Install]
    WantedBy=multi-user.target
  3. Enable and start:

    sudo systemctl daemon-reload
    sudo systemctl enable album-bot
    sudo systemctl start album-bot

📂 Project Structure

Album-Maker-Bot/
├── album_bot_auto.py     # Main bot logic, event handlers & queue manager
├── config.py             # Configuration loader, constants & logger setup
├── Dockerfile            # Container build definition (Python 3.11-slim)
├── docker-compose.yml    # Docker Compose service definition
├── requirements.txt      # Project dependencies (kurigram, pytgcrypto)
├── .gitignore            # Git ignore specification
└── README.md             # Project documentation

🤝 Contributing

Contributions, issues, and feature requests are welcome!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

Distributed under the MIT License. See LICENSE for more information.


Built with ❤️ by prono69 and powered by Kurigram

About

An advanced telegram bot to make media group/album from individual files

Resources

Stars

2 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages