Meido

A Telegram bot to send anime directly to your inbox. This bot uses animdl for searching and downloading anime files, and stores them in MongoDB for faster subsequent access.

System Design

Features

• 🎬 Download anime episodes on demand
• 💾 Cache downloaded episodes in MongoDB for instant access
• 📱 Send videos directly to Telegram users
• 🔍 Search and download from multiple anime sources via animdl
• ⚡ Fast response times for cached content

Requirements

• Python 3.9 or higher
• MongoDB (local or remote instance)
• FFmpeg (for video conversion)
• Telegram Bot Token
• Telegram API credentials (api_id, api_hash) from my.telegram.org

Installation

1. Clone the Repository

git clone https://github.com/yourusername/Meido.git
cd Meido

2. Install Dependencies

Using pip:

pip install -r requirements.txt

Using pipenv:

pipenv install

3. Install FFmpeg

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install ffmpeg

macOS:

brew install ffmpeg

Windows: Download from FFmpeg official website and add to PATH.

4. Install animdl

pip install animdl

Or install from source:

pip install git+https://github.com/justfoolingaround/animdl.git

5. Setup MongoDB

Local Installation:

# Ubuntu/Debian
sudo apt-get install mongodb

# macOS
brew install mongodb-community

# Start MongoDB service
sudo systemctl start mongod  # Linux
brew services start mongodb-community  # macOS

Docker:

docker run -d -p 27017:27017 --name mongodb mongo:latest

Remote MongoDB: Set the MONGO_DB_URL environment variable:

export MONGO_DB_URL="mongodb://username:password@host:port/"

Configuration

1. Bot Configuration

Create bot/config/botConfig.json from the example:

cp bot/config/exampleConfig.json bot/config/botConfig.json

Edit bot/config/botConfig.json:

{
    "bot_token": "YOUR_BOT_TOKEN_FROM_BOTFATHER",
    "agent_user_id": YOUR_TELEGRAM_USER_ID
}

To get your bot token:

1. Open Telegram and search for @BotFather
2. Send /newbot and follow instructions
3. Copy the token provided

To get your user ID:

1. Search for @userinfobot on Telegram
2. Start a conversation to get your user ID

2. Uploader Service Configuration

Create uploaderService/config/agentConfig.json from the example:

cp uploaderService/config/Example_agentConfig.json uploaderService/config/agentConfig.json

Edit uploaderService/config/agentConfig.json:

{
  "entity": "session_name",
  "api_id": "YOUR_API_ID",
  "api_hash": "YOUR_API_HASH",
  "phone": "+1234567890",
  "bot_name": "@your_bot_username"
}

To get your API credentials:

1. Go to my.telegram.org
2. Log in with your phone number
3. Go to "API development tools"
4. Create a new application and copy api_id and api_hash

Important: The bot_name should be your bot's username (e.g., @myanimebot)

Usage

Starting the Bot

From the project root directory:

python bot/bot.py

Or using pipenv:

pipenv run python bot/bot.py

Bot Commands

• /start - Start the bot and see welcome message
• /help - Show help message with available commands
• /getanime <anime_name>, <season>, <episode> - Download and send anime episode

Example:

/getanime Death Note, 1, 3

This will:

1. Check if the episode exists in the database
2. If found, send it immediately
3. If not found, download it, convert to MP4, upload to Telegram, and send it to you

Project Structure

Meido/
├── bot/
│   ├── bot.py              # Main bot application
│   ├── botUtils.py         # Utility functions
│   ├── database.py         # MongoDB operations
│   └── config/
│       ├── botConfig.json  # Bot configuration (create from example)
│       └── exampleConfig.json
├── downloaderService/
│   └── main.py             # Anime download service
├── uploaderService/
│   ├── main.py             # Telegram upload service
│   └── config/
│       ├── agentConfig.json # Uploader config (create from example)
│       └── Example_agentConfig.json
├── docs/
│   ├── architechture.md    # Architecture documentation
│   └── databaseSchema.md   # Database schema
├── requirements.txt        # Python dependencies
├── Pipfile                 # Pipenv dependencies
└── README.md              # This file

How It Works

1. User Request: User sends /getanime command with anime details
2. Database Check: Bot checks MongoDB for existing file_id
3. Cache Hit: If found, bot sends video immediately using file_id
4. Cache Miss: If not found:
   • Downloads anime using animdl
   • Converts .ts to .mp4 using FFmpeg
   • Uploads to Telegram via Telethon (agent account)
   • Bot receives file_id and stores in database
   • Bot sends video to user
5. Future Requests: Subsequent requests for the same episode are instant

Troubleshooting

Bot won't start

• Config file not found: Ensure botConfig.json exists in bot/config/
• Invalid token: Verify your bot token is correct
• MongoDB connection error: Check if MongoDB is running and accessible

  # Test MongoDB connection
  mongosh

Downloads fail

• animdl not installed: Install animdl as shown in installation steps
• FFmpeg not found: Ensure FFmpeg is installed and in PATH

  ffmpeg -version  # Should show version info

Upload fails

• Telegram API error: Verify your API credentials in agentConfig.json
• Session not authorized: On first run, you'll need to enter the verification code
• File not found: Ensure the download completed successfully

Database issues

• Connection timeout: Check MongoDB is running
• Authentication error: Verify MongoDB URL if using remote instance
• Collection not found: The collection will be created automatically on first use

Environment Variables

• MONGO_DB_URL: MongoDB connection string (default: mongodb://localhost:27017/)

Example:

export MONGO_DB_URL="mongodb://user:pass@localhost:27017/"

Security Notes

• Never commit botConfig.json or agentConfig.json to version control
• These files are in .gitignore by default
• Use environment variables for sensitive data in production
• Keep your API credentials secure

Development

Code Style

The project follows PEP 8 Python style guidelines. Consider using:

• black for code formatting
• flake8 for linting
• mypy for type checking

Testing

The project includes a comprehensive test suite using pytest. To run tests:

Install test dependencies:

pip install -r requirements.txt

Run all tests:

pytest tests/ -v

Or use the test runner script:

./run_tests.sh

Run specific test files:

pytest tests/test_botUtils.py -v
pytest tests/test_database.py -v
pytest tests/test_bot_commands.py -v
pytest tests/test_integration.py -v

Run with coverage:

pytest tests/ --cov=bot --cov=downloaderService --cov=uploaderService --cov-report=html

Test Structure:

• tests/test_botUtils.py - Tests for utility functions (parsing, file operations)
• tests/test_database.py - Tests for MongoDB operations
• tests/test_bot_commands.py - Tests for bot commands (/start, /help, /getanime)
• tests/test_integration.py - Integration tests for complete workflows

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new features
5. Ensure all tests pass
6. Submit a pull request

License

See LICENSE file for details.

Status

✅ Core functionality working ✅ MongoDB integration ✅ Error handling improved ✅ Modern dependencies 🔄 Pre-caching popular anime (planned) 🔄 Subscription feature (planned) 🔄 Watch list (planned) 🔄 Recommendations (planned)

Support

If you encounter any issues or have questions:

• Open an issue on GitHub
• Check existing issues for solutions
• Review the troubleshooting section above

Acknowledgments

• animdl for anime downloading
• python-telegram-bot for Telegram bot framework
• Telethon for Telegram client library

---

Note: This bot is for educational purposes. Ensure you comply with copyright laws and terms of service when using this software.