Telegram Bot для извлечения аудио и субтитров с YouTube

Этот проект представляет собой Telegram-бота, написанного на Python (3.11), который позволяет пользователям извлекать аудиодорожки и субтитры из видео на YouTube. Бот реализует два ключевых функционала:

• Извлечение аудиодорожки (минимальное качество)
• Получение субтитров целиком (без выбора таймкодов)

Быстрый старт (локально в Docker, polling)

• Подготовьте файл .env с токеном:
  • Скопируйте пример: cp .env.example .env
  • Установите TELEGRAM_TOKEN=...
• Запустите: docker compose up --build
• Проверка здоровья: curl http://localhost:43123/healthz (бот работает в polling, порт только для health).

Альтернатива без Docker (локально):

• python3.11 -m venv venv && source venv/bin/activate && pip install -r requirements.txt
• LOCAL_POLLING=1 TELEGRAM_TOKEN=... python -m bot.main

Функционал

1. Извлечение аудиодорожки

При выборе этой функции:

• Пользователь отправляет ссылку или ID видео.
• Бот проверяет корректность ссылки с помощью регулярного выражения.
• Если поступает только ID видео, бот преобразует его в полный URL.
• Функция download_audio_from_youtube сначала пытается загрузить аудиодорожку через библиотеку yt-dlp и извлекает аудио в формате MP3 с низким качеством (64 kbps). Если это не удаётся, используется запасной вариант через pytube.
• После загрузки бот проверяет размер файла; если аудиофайл превышает 50 МБ, пользователь получит уведомление о невозможности его отправки из-за ограничений Telegram API.
• Если размер файла приемлем, аудиофайл отправляется пользователю:
  • Сначала как аудио-сообщение.
  • Затем как документ для возможности загрузки.
• После успешной отправки файла он удаляется из локальной файловой системы.

2. Получение субтитров (целиком)

При выборе функции получения субтитров:

• Пользователь отправляет ссылку или ID видео.
• Бот проверяет корректность ссылки/ID.
• С помощью библиотеки youtube_transcript_api бот извлекает транскрипцию (субтитры) для указанного видео целиком (без выбора интервала). При неудаче предпринимается попытка получить субтитры через pytube, а затем при необходимости используется запасной метод через yt-dlp (скачивание VTT и преобразование в обычный текст).
• Текст субтитров сохраняется во временный файл и отправляется пользователю как документ.
• Имя файла совпадает с названием видео (безопасно очищено), с расширением .txt.
• После отправки временный файл удаляется.

3. Диалог с пользователем

Бот реализует удобное меню с выбором функций:

• После команды /start пользователю показывается клавиатура с кнопками для выбора между извлечением аудио (🎵 Аудио) и получением субтитров (📄 Субтитры).
• После выполнения одной из функций пользователь получает приглашение выбрать новую задачу.

Структура проекта

.
├── bot
│   ├── __init__.py
│   ├── main.py               # Главный файл, который инициирует бота и обрабатывает команды
│   ├── handlers
│   │   ├── __init__.py
│   │   ├── audio_handler.py  # Логика для загрузки и отправки аудиодорожек
│   │   └── subtitles_handler.py  # Логика для получения и отправки субтитров (целиком)
│   ├── states.py             # Определение состояний диалога
│   └── utils
│       ├── __init__.py
│       ├── helpers.py        # Вспомогательные функции (в т.ч. безопасные имена файлов)
│       └── youtube_downloader.py  # Функции для загрузки аудио, длительности и заголовка видео
├── docker-compose.yml        # Файл для запуска контейнера с ботом
├── Dockerfile                # Файл для сборки Docker образа
├── downloads                 # Локальная директория для временного хранения файлов (смонтирована в контейнер)
├── requirements.txt          # Список зависимостей Python
└── README.md                 # Этот файл

Установка и запуск

Локальный запуск

1. Клонирование репозитория:

   git clone <repository-url>
   cd give-me-back-my-y2b

2. Создание виртуального окружения (опционально, но рекомендуется):

   python3.11 -m venv venv
   source venv/bin/activate

3. Установка зависимостей:

   pip install --no-cache-dir -r requirements.txt

4. Настройка переменных окружения: Создайте файл .env в корне проекта и добавьте:

   TELEGRAM_TOKEN=your_telegram_bot_token_here

5. Запуск бота:

   python -m bot.main

Запуск через Docker

1. Запуск контейнера с помощью Docker Compose:

   docker compose up --build

   Порт 43123 открыт для health-проверок: curl http://localhost:43123/healthz. Каталог downloads примонтирован внутрь контейнера.

Технологии и библиотеки

• Python 3.11
• python-telegram-bot — для взаимодействия с Telegram API.
• yt-dlp — основная библиотека для загрузки видео и аудио с YouTube.
• pytube — резервный инструмент для получения аудио и субтитров.
• youtube_transcript_api — для получения субтитров.
• Docker — для создания контейнеризированного окружения.

Логи и обработка ошибок

• Логирование осуществляется с помощью стандартного модуля logging для отслеживания процесса загрузки, ошибок и отправки файлов.
• Реализован глобальный обработчик ошибок, который уведомляет пользователя в случае возникновения проблем.

Разработка и вклад

• Внесите свои предложения или исправления через Issues и Pull Requests.
• Соблюдайте PEP-8 для написания чистого и читаемого кода.

Лицензия

Проект распространяется под лицензией MIT. Подробнее см. файл LICENSE.

Контакты

Если у вас возникли вопросы или предложения, можете связаться с разработчиком через Telegram: @mysunismine.

---

Данный README содержит подробное описание функционала и процессов, реализованных в проекте Telegram Bot для извлечения аудио и субтитров с YouTube.