🚀 Telegram Bot Documentation

UspMusicFinder
Bot Documentation

Полнофункциональный Telegram бот для поиска, скачивания и распознавания музыки с YouTube Music

12+
Функций
3
Языка
4
Платёжные системы

Обзор проекта

Общая информация о боте и его возможностях

Параметр Значение
Название UspMusicFinder Bot
Bot Username @UspMusicFinder_bot
Bot ID 8409655187
Канал @TopMusicToday
Сервер 31.44.7.144
Язык Python 3.11+
Framework aiogram 3.15
💰

Бизнес-модель: Freemium

Free пользователи: 10 скачиваний/день. Premium: безлимит + распознавание музыки + x2 реферальные бонусы.

Функциональные возможности

Все функции бота с подробным описанием

🔍
Поиск музыки

Пользователь отправляет название песни или исполнителя, бот ищет треки через YouTube Music API и возвращает до 20 результатов с пагинацией.

🎵 Результаты поиска: "Queen"
Найдено: 20 треков

🥇 Queen
   🎤 Bohemian Rhapsody
   ⏱️ 5:55

🥈 Queen
   🎤 We Will Rock You
   ⏱️ 2:02
  • Источник: YouTube Music (через ytmusicapi)
  • Кэширование результатов: 10 минут
  • Rate limiting: 5 запросов в минуту
⬇️
Скачивание треков

Процесс скачивания трека:

1

Проверка лимитов

Проверка дневного лимита и премиум статуса пользователя

2

Загрузка через yt-dlp

Скачивание аудио с YouTube в лучшем качестве

3

Конвертация в MP3

Конвертация в MP3 формат с битрейтом 192 kbps

4

Добавление метаданных

Заполнение тегов: исполнитель, название, обложка

5

Отправка в Telegram

Отправка готового MP3 файла пользователю

⚠️

Ограничения

Макс. размер: 50 MB | Макс. длительность: 60 мин | Free лимит: 10 треков/день

🏆
Топ треков

Команда /top показывает самые популярные треки за выбранный период.

📅

Сегодня

Топ треков за текущий день

📆

Неделя

Топ за последние 7 дней

📊

Месяц

Топ за последние 30 дней

🏆

Все время

Общий топ за все время

🎵
Персональные рекомендации

Команда /recommendations генерирует персональные рекомендации на основе истории пользователя.

Алгоритм рекомендаций:

  • 1 Анализ истории скачиваний пользователя
  • 2 Определение топ-3 любимых исполнителей
  • 3 Поиск популярных треков этих исполнителей
  • 4 Фильтрация уже скачанных треков
  • 5 Дополнение глобально популярными треками
🎤
Распознавание музыки

Команда /recognize позволяет определить песню по аудиозаписи.

Поддерживаемые форматы:

🎙️

Голосовые сообщения

Запись через микрофон Telegram

🎵

Аудиофайлы

MP3, WAV и другие форматы

Видеосообщения

Круглые видео (кружки)

🎶

Напевание

Humming recognition

📊

Лимиты распознавания

Free: 5 распознаваний в день | Premium: безлимит

👥
Реферальная система

Команда /referral для приглашения друзей и получения бонусов.

Действие Награда
Друг присоединился по ссылке +5 скачиваний
Друг скачал 5 треков +10 скачиваний
Формат ссылки: https://t.me/UspMusicFinder_bot?start=ref_USER_ID
Премиум подписка

Команда /premium для покупки премиум подписки.

Тарифы Telegram Stars:

План Цена Срок
Месяц 50 ⭐ 30 дней
Квартал 120 ⭐ 90 дней
Год 360 ⭐ 365 дней

Преимущества Premium:

  • ♾️ Безлимитные скачивания
  • 🚀 Приоритет в очереди
  • 🎵 Распознавание без лимитов
  • ❤️ Безлимитное избранное
  • 🎁 x2 бонусы за рефералов
🌐
Мультиязычность

Команда /lang для смены языка интерфейса.

🇷🇺

Русский

Язык по умолчанию

🇬🇧

English

Full translation

🇺🇿

O'zbek

To'liq tarjima

Технический стек

Технологии и инструменты проекта

Технология Версия Назначение
Python 3.11+ Язык программирования
aiogram 3.15 Telegram Bot Framework
aiosqlite 0.19+ Асинхронный SQLite
yt-dlp Latest Загрузка медиа
mutagen 1.47+ Метаданные аудио
pydantic 2.0+ Валидация данных
🎵

YouTube Music

Поиск треков через ytmusicapi

🎤

AudD API

Распознавание музыки по аудио

💎

CryptoBot

Криптовалютные платежи

🛡️

Sentry

Мониторинг ошибок

🐳

Docker

Контейнеризация приложения

🔄

Docker Compose

Оркестрация сервисов

⚙️

GitHub Actions

CI/CD pipeline

🧪

pytest

Unit тестирование

aiogram>=3.15.0
aiosqlite>=0.19.0
aiohttp>=3.9.0
yt-dlp>=2024.1.0
mutagen>=1.47.0
pydantic>=2.0.0
python-dotenv>=1.0.0
aiocryptopay>=0.4.0
sentry-sdk>=1.39.0
ytmusicapi>=1.3.0

База данных

SQLite схема и структура таблиц

💾

Информация о БД

СУБД: SQLite | Библиотека: aiosqlite | Pattern: Repository

👤
users - Пользователи
CREATE TABLE users (
    id INTEGER PRIMARY KEY,        -- Telegram user ID
    username TEXT,                    -- @username
    first_name TEXT,                  -- Имя
    language TEXT DEFAULT 'ru',      -- Язык интерфейса
    is_premium INTEGER DEFAULT 0,     -- Премиум статус
    premium_until TIMESTAMP,          -- Дата окончания
    referral_code TEXT UNIQUE,        -- Реферальный код
    referred_by INTEGER,              -- Кто пригласил
    bonus_downloads INTEGER DEFAULT 0,-- Бонусы
    searches INTEGER DEFAULT 0,       -- Кол-во поисков
    downloads INTEGER DEFAULT 0,      -- Кол-во скачиваний
    created_at TIMESTAMP,
    last_seen TIMESTAMP
);
📥
downloads - История скачиваний
CREATE TABLE downloads (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    track_id TEXT NOT NULL,
    title TEXT NOT NULL,
    artist TEXT,
    duration INTEGER,
    downloaded_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    FOREIGN KEY (user_id) REFERENCES users(id)
);
❤️
favorites - Избранное
CREATE TABLE favorites (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    track_id TEXT NOT NULL,
    title TEXT NOT NULL,
    artist TEXT,
    duration INTEGER,
    added_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    UNIQUE(user_id, track_id)
);
📊
track_stats - Статистика треков
CREATE TABLE track_stats (
    track_id TEXT PRIMARY KEY,
    title TEXT NOT NULL,
    artist TEXT,
    duration INTEGER,
    download_count INTEGER DEFAULT 0,
    last_downloaded TIMESTAMP
);
💳
payments - Платежи
CREATE TABLE payments (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    user_id INTEGER NOT NULL,
    amount REAL NOT NULL,
    currency TEXT DEFAULT 'XTR',
    payment_type TEXT,          -- premium/donate
    payment_system TEXT,        -- stars/cryptobot
    status TEXT DEFAULT 'pending',
    payload TEXT,
    created_at TIMESTAMP,
    completed_at TIMESTAMP
);

Система локализации

Мультиязычная поддержка бота

# Использование в коде
from src.locales import _

# Получить перевод для пользователя
message = _("welcome", user_id=12345)

# С параметрами
message = _("downloading", user_id=12345, title="Song", artist="Artist")
Код Язык Файл
ru 🇷🇺 Русский locales/ru.py
en 🇬🇧 English locales/en.py
uz 🇺🇿 O'zbek locales/uz.py

Платежные системы

Интегрированные способы оплаты

Telegram Stars

Встроенная валюта Telegram для платежей внутри ботов. Мгновенная активация премиума.

50⭐ - месяц 120⭐ - 3 месяца 360⭐ - год
💎

CryptoBot

Криптовалютные платежи через @CryptoBot. Поддержка USDT, TON, BTC, ETH.

$2.99 - месяц $6.99 - 3 месяца $19.99 - год
💳

ЮKassa

Банковские карты через ЮKassa (Сбербанк, Тинькофф, Альфа и др.). Для пользователей из РФ.

199₽ - месяц 499₽ - 3 месяца 1499₽ - год
💰

ЮMoney

Оплата через кошелёк ЮMoney (бывший Яндекс.Деньги). Быстро и удобно.

199₽ - месяц 499₽ - 3 месяца 1499₽ - год

API для внешних ботов

Интеграция с другими Telegram ботами

🔍
/api - Поиск и отправка
/api <query> <chat_id>

# Пример:
/api Bohemian Rhapsody -1001234567890

Ищет трек и отправляет его в указанный чат.

📋
/api_search - Только поиск
/api_search <query>

# Возвращает список треков с video ID
⬇️
/api_download - Скачивание по ID
/api_download <video_id> <chat_id>

Административная панель

Команды для управления ботом

Команда Описание
/admin Главное меню админ-панели
/stats Детальная статистика бота
/users Топ пользователей по скачиваниям
/setpremium <user_id> <days> Выдать премиум пользователю
/mailing <text> Массовая рассылка всем пользователям
/post_top Опубликовать топ треков в канал

Инфраструктура

Docker, CI/CD и развертывание

# docker-compose.yml
version: '3.8'

services:
  bot:
    build: .
    container_name: uspmusic-bot
    restart: unless-stopped
    volumes:
      - ./data:/app/data
      - ./logs:/app/logs

  dashboard:
    build:
      dockerfile: Dockerfile.dashboard
    ports:
      - "8080:8080"

  redis:
    image: redis:alpine

  backup:
    image: alpine
    # Ежедневный бэкап БД
# GitHub Actions
jobs:
  lint:     # flake8, black
  test:     # pytest
  build:    # Docker build
  deploy:   # SSH deploy to server
# Создать бэкап
./scripts/backup.sh

# Восстановить из бэкапа
./scripts/restore.sh backup_20241221_120000.db.gz

Безопасность

Меры защиты и безопасности

🔐

Токены в .env

Все секреты хранятся в переменных окружения

⏱️

Rate Limiting

5 запросов в минуту на пользователя

Валидация

Проверка всех входных данных

📁

Лимиты файлов

Max 50MB, 60 минут

🧹

Автоочистка

Удаление временных файлов

📝

Логирование

Запись всех действий + Sentry