Vladimir Zagainov
e13557059c
All checks were successful
continuous-integration/drone/push Build is passing
110 lines
8.7 KiB
Markdown
110 lines
8.7 KiB
Markdown
# Yandex.Music Downloader Bot
|
||
|
||
[](https://drone.mrixs.me/Mrixs/yamusic-bot?branch=dev) [](LICENSE)
|
||
|
||
Удобный и быстрый Telegram-бот для получения аудиофайлов из сервиса Yandex.Music. Работает в inline-режиме, позволяя отправлять музыку в любой чат. Поддерживает поиск, а также ссылки на треки, альбомы и исполнителей.
|
||
|
||
## 🚀 Основные возможности
|
||
|
||
* **Inline-режим:** Используйте бота в любом чате, просто упомянув его `@username`.
|
||
* **Поддержка ссылок:** Распознает и обрабатывает ссылки на треки, альбомы и страницы исполнителей.
|
||
* **Поиск:** Если введенный текст не является ссылкой, бот выполнит поиск треков по этому тексту.
|
||
* **Метаданные:** Автоматически встраивает в аудиофайлы ID3-теги (название, исполнитель, альбом, год) и обложку.
|
||
* **Кэширование:** Мгновенная отправка уже обработанных треков благодаря системе кэширования на базе SQLite и приватного Telegram-канала.
|
||
* **Администрирование:** Предоставляет набор команд для администраторов для мониторинга и управления ботом.
|
||
|
||
## ⚙️ Конфигурация
|
||
|
||
Бот настраивается с помощью переменных окружения.
|
||
|
||
| Переменная | Описание | Пример | Обязательно |
|
||
| ------------------------- | ------------------------------------------------------ | ----------------------------- | ----------- |
|
||
| `TELEGRAM_BOT_TOKEN` | Токен, полученный от @BotFather. | `12345:ABC-DEF` | **Да** |
|
||
| `TELEGRAM_ADMIN_IDS` | Список Telegram ID администраторов через запятую. | `1234567,9876543` | **Да** |
|
||
| `TELEGRAM_CACHE_CHAT_ID` | ID приватного канала/чата для хранения файлов. | `-100123456789` | **Да** |
|
||
| `YANDEX_MUSIC_TOKEN` | OAuth-токен для доступа к Yandex.Music API. | `y0_...` | **Да** |
|
||
| `DATABASE_PATH` | Путь к файлу базы данных SQLite. | `/data/bot.db` | Нет (`/data/bot.db`) |
|
||
| `LOG_LEVEL` | Уровень логирования (`debug`, `info`, `warn`, `error`). | `info` | Нет (`info`) |
|
||
| `PROCESSOR_WORKERS` | Количество воркеров для обработки треков. | `4` | Нет (`4`) |
|
||
| `YANDEX_API_RATE_LIMIT` | Запросов в секунду к Yandex API. | `5` | Нет (`5`) |
|
||
|
||
## ▶️ Запуск
|
||
|
||
### С помощью Docker 🐳
|
||
|
||
Рекомендуемый способ запуска. Убедитесь, что у вас установлен Docker.
|
||
|
||
1. Создайте директорию для хранения базы данных: `mkdir -p ./data`
|
||
2. Запустите контейнер:
|
||
|
||
```bash
|
||
docker run -d --name yamusic-bot \
|
||
-v $(pwd)/data:/data \
|
||
-e TELEGRAM_BOT_TOKEN="ВАШ_ТОКЕН" \
|
||
-e TELEGRAM_ADMIN_IDS="ВАШ_ID,ID_ДРУГА" \
|
||
-e TELEGRAM_CACHE_CHAT_ID="-100..." \
|
||
-e YANDEX_MUSIC_TOKEN="y0_..." \
|
||
--restart always \
|
||
gitea.mrixs.me/mrixs/yamusic-bot:dev
|
||
```
|
||
*Примечание: Используйте тег `:latest` для стабильной версии из ветки `master` или `:dev` для последней сборки из ветки `dev`.*
|
||
|
||
### С помощью Docker Compose
|
||
|
||
1. Создайте файл `docker-compose.yml`:
|
||
```yaml
|
||
version: '3.8'
|
||
services:
|
||
bot:
|
||
image: gitea.mrixs.me/mrixs/yamusic-bot:dev
|
||
container_name: yamusic-bot
|
||
restart: always
|
||
volumes:
|
||
- ./data:/data
|
||
environment:
|
||
- TELEGRAM_BOT_TOKEN=
|
||
- TELEGRAM_ADMIN_IDS=
|
||
- TELEGRAM_CACHE_CHAT_ID=
|
||
- YANDEX_MUSIC_TOKEN=
|
||
- LOG_LEVEL=info
|
||
```
|
||
2. Заполните переменные окружения в файле или создайте рядом `.env` файл.
|
||
3. Запустите: `docker-compose up -d`
|
||
|
||
## 🕹️ Использование
|
||
|
||
### Для пользователей
|
||
Начните вводить в любом чате `@bot_username`, а затем вставьте ссылку или напишите поисковый запрос.
|
||
|
||
- **Ссылка на трек:** `@bot_username https://music.yandex.ru/album/123/track/456`
|
||
- **Ссылка на альбом:** `@bot_username https://music.yandex.ru/album/123`
|
||
- **Поиск:** `@bot_username Rammstein - Sonne`
|
||
|
||
### Для администраторов
|
||
Отправьте команду в личные сообщения боту.
|
||
|
||
- `/help` — Показать список команд.
|
||
- `/stats` — Показать статистику работы бота.
|
||
- `/find <yandex_track_id>` — Найти трек в кэше по ID.
|
||
- `/warm <URL>` — "Прогреть" кэш для альбома или исполнителя.
|
||
|
||
## 🗺️ План разработки (Dev Roadmap)
|
||
|
||
| Статус | Задача | Комментарий |
|
||
| :----: | -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
|
||
| ✅ | Базовый CI/CD пайплайн (lint, test) | Настроен в `.drone.yml`. |
|
||
| ✅ | Основная логика обработки URL (трек, альбом, артист) | Реализовано в `internal/bot/handler.go`. |
|
||
| ✅ | Система кэширования (SQLite + Telegram) | Реализовано в `internal/storage` и `internal/processor`. |
|
||
| ✅ | Базовая структура проекта и конфигурация | Вся структура соответствует ТЗ. |
|
||
| ✅ | Административные команды `/help`, `/stats`, `/find` | Основной функционал реализован в `internal/admin/handler.go`. |
|
||
| ✅ | Публикация Docker-образов в CI/CD | Шаги `build-and-publish-*` активны в `.drone.yml` для `master` и `dev`. |
|
||
| ⏳ | Расширение тестового покрытия | Есть тесты для `storage`, но нужны для `processor`, `bot`, `admin`. |
|
||
| ⏳ | Финализация документации | Этот `README.md` является частью задачи. |
|
||
| ❌ | Реализация логики команды `/warm` | Существует только заглушка, фоновая обработка не реализована. |
|
||
| ❌ | Ограничение частоты запросов (Rate Limiting) к Yandex API | Требуется внедрение `rate.Limiter`. |
|
||
| ❌ | Поддержка текстового поиска и коротких URL | Задача из нового ТЗ, требуется реализация в `handler` и `yamusic client`. |
|
||
|
||
## 📄 Лицензия
|
||
|
||
Проект распространяется под лицензией MIT. См. файл `LICENSE` для получения дополнительной информации.
|