🇷🇺 Перейти на русскую версию

🎵 "SoundPlus" — Feature-Rich Telegram Music & Shazam Bot

An asynchronous, high-performance Telegram music bot built with Kurigram (Pyrogram fork), Yandex.Music API, and ShazamIO.

💼 Case Study: This project represents a complete architectural refactoring and feature overhaul of a high-load music bot for a client. Originally suffering from blocking calls and frequent crashes, the codebase was rewritten from scratch into a modular, asynchronous architecture.

---

🌟 Key Features

For Users

• 🔎 Music Search: Fast track and artist search via Yandex.Music API.
• 🎧 Audio Streaming & Downloading: High-quality MP3 downloads directly in Telegram.
• 🌊 Personal Wave ("Моя волна"): Smart recommendation engine generating personalized track lists based on user listening history and favorites.
• 🏆 Charts & New Releases: Instant access to global top charts and fresh album releases.
• 🎙️ Shazam Music Recognition: Send any video file (up to 20MB) to extract the audio stream via FFmpeg and recognize the song title using Shazam.
• ⭐️ Telegram Stars Payments: Automated Premium subscription purchase workflow using native Telegram Stars (XTR).
• 👥 Referral System: Users earn extra Premium days by inviting friends via unique referral links with CAPTCHA verification.

For Administrators

• 📊 Live Analytics: Track total users, active Premium subscribers, total plays, and pending payments.
• 📢 Broadcast Engine: Flexible broadcast messaging tool with support for media, text formatting, and custom URL inline buttons.
• 💎 Manual Subscription Management: Grant or extend Premium access to specific users by ID or @username.
• 🔴/🟢 Bot Maintenance Mode: Emergency global kill-switch to pause service for non-admin users.

---

🛠️ Architecture & Performance Highlights

• Asynchronous I/O Pipeline: Eliminated blocking operations by converting all database, filesystem, and external API requests to native async/await.
• Database Optimization (SQLite + WAL): Built on aiosqlite utilizing Write-Ahead Logging (WAL) mode, transaction blocks, and foreign key constraints for safe multi-thread reads.
• Dual-Tier Caching System:
  • User Data & FSM: Low-latency persistent Key-Value storage via diskcache (AsyncDiskCache wrapper) ensuring instant state lookups without DB queries.
  • Media Caching: Automatic file_id caching for interface animations and static assets to save server bandwidth.
• Middleware Protection: Custom anti-spam throttling middleware with configurable rate limits.

---

📐 Project Structure

YandexMusicBot/
├── background/         # Background workers (subscription expiration checkers)
├── data/
│   ├── database/       # SQLite connection wrapper, schema, and queries
│   ├── cache_manager.py# AsyncDiskCache engine and UserData models
│   └── config.py       # App configuration and environment loader
├── handlers/           # Modular event handlers (admin, music, payment, common)
├── middlewares/        # Anti-spam throttling & Maintenance status gates
├── services/           # External APIs (Yandex.Music, ShazamIO, Youtube)
├── ui/                 # Keyboards and UI templates
├── utils/              # CAPTCHA generator and media senders
├── create_database.py  # DB table schemas and indexes generator
├── main.py             # App entry point
├── .env.example
└── requirements.txt

---

🚀 Quick Start

1. Clone the repository:

   git clone https://github.com/cxvimba/YandexMusicBot.git
   cd YandexMusicBot

2. Set up virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt

3. Configure Environment: Copy .env.example to .env and insert your credentials:

   cp .env.example .env

4. Initialize Database:

   python create_database.py

5. Run the bot:

   python main.py

---

💬 Client Review

"I ran into a serious issue: my bot was under heavy load and kept failing. Since I knew @Im_DMAR worked in software development, I asked for his help. He refactored the legacy code entirely, built an anti-spam system, and added numerous new features. I recommend him to everyone — a highly experienced programmer who knows what he is doing!"
— Michael (SoundPlus Owner)