TeleLoader Bot

Мощный и безопасный Telegram‑бот для скачивания видео/аудио/субтитров с YouTube и YouTube Shorts — с выбором качества, переводами (ru/en), рейт‑лимитером, облачным бэкапом (S3) и готовой Docker‑упаковкой. Основан на

✨ Возможности

• Принимает ссылки YouTube/Shorts → присылает видео (1080p/720p/480p), аудио (M4A/MP3) или субтитры (SRT).
• Inline‑клавиатура выбора качества/режима.
• Рейт‑лимитер и параллелизм (без перегрузки железа).
• Эфемерный кэш токенов для callback‑кнопок (устраняет
  Button_data_invalid
  ).
• Фолбэк при больших файлах: загрузка в S3 и отдача ссылки.
• i18n (ru/en), /settings, /privacy, /stats (только для администратора).
• Готовые Dockerfile и docker-compose.yml с предустановленным
  ffmpeg
  .

🚀 Быстрый старт

Вариант 1 — Docker (рекомендовано)

1. Скопируйте переменные окружения:

2. Откройте

   .env
   и укажите токен бота от @BotFather:

3. Запустите:

4. Напишите боту

   /start
   в Telegram.

В контейнере

ffmpeg

уже установлен, ничего дополнительно ставить не нужно.

Вариант 2 — Локальный запуск

Windows

Linux/macOS

Требуется установленный

ffmpeg

(или укажите путь в

.env

через

FFMPEG_LOCATION

).

⚙️ Переменные окружения (

.env

)

Пример минимального ``:

🧠 Команды бота

• /start
  — приветствие, краткая инструкция.
• /help
  — все возможности бота.
• /settings
  — язык, качество по умолчанию, режим «как документ».
• /privacy
  — политика данных (что и как хранится).
• /stats
  — статистика (только для
  ADMIN_USER_ID
  ).

Юзер‑флоу: отправляете ссылку → бот показывает кнопки

🏗 Архитектура и дерево проекта

Слои:

• Transport/UI: Telegram (
  python-telegram-bot
  v20)
• App:
  app/bot.py
  (хэндлеры, i18n, рейт‑лимит, конкурентность)
• Services:
  downloader.py
  (yt‑dlp),
  transcode.py
  (ffmpeg),
  storage.py
  (размер/S3)
• Persistence:
  models.py
  (SQLAlchemy, SQLite по умолчанию)
• Config:
  config.py
  (+dotenv)
• UI helpers:
  keyboards.py
  ,
  texts.py
• Glue:
  run.py

Дерево:

.
├─ run.py
├─ requirements.txt
├─ Dockerfile
├─ docker-compose.yml
├─ LICENSE
├─ README.md
├─ .gitignore
├─ .env.example
├─ scripts/
│  ├─ install_ffmpeg.ps1
│  └─ install_ffmpeg.sh
└─ app/
   ├─ __init__.py
   ├─ bot.py
   ├─ cache.py
   ├─ config.py
   ├─ downloader.py
   ├─ ffmpeg_guard.py
   ├─ keyboards.py
   ├─ models.py
   ├─ security.py
   ├─ storage.py
   ├─ texts.py
   └─ transcode.py

Схема БД:

• user_settings(user_id PK, lang, default_quality, send_as_document)
• downloads(id PK, url, quality, filepath, size, created_at)

🧩 Технические детали

• yt-dlp
  скачивает раздельные поток/аудио и соединяет через
  ffmpeg
  → без
  ffmpeg
  будут ошибки merge.
• Для длинных URL в callback‑кнопках используется эфемерный токен (22 символа) + кэш в памяти (TTL), чтобы не превышать лимит
  64 bytes
  на
  callback_data
  .
• Параллельные скачивания ограничены
  asyncio.Semaphore
  .
• Рейт‑лимитер (token‑bucket) защищает от спама.
• Очистка временных файлов — после каждой операции.

🐳 Docker

Файлы:

• Dockerfile
  — базовый образ Python +
  ffmpeg
  (через
  apt-get
  ).
• docker-compose.yml
  — быстрый запуск с примонтированными
  tmp/
  и
  cache.sqlite
  .

Запуск:

Остановка:

Логи:

🌐 Webhook‑режим (опционально)

1. В

   .env
   включите:

2. Прокиньте 443→8080 через обратный прокси (nginx/caddy/traefik) с валидным TLS.

3. Перезапустите сервис.

По умолчанию используется polling — он надёжнее для локальной разработки и простого деплоя.

☁️ S3 (большие файлы)

Заполните

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

• Секреты только в ``/переменных окружения. Никогда не коммитьте токены.
• Рекомендовано периодически ротировать токен в @BotFather.
• URL валидируются (только YouTube/Shorts).
• Ограничение частоты и параллелизма защищают от DoS‑подобной нагрузки.
• В ответах пользователю минимум технических деталей при ошибках (без утечек).

🧪 Тестирование и отладка

• Локально:
  python run.py
  и общайтесь с ботом в Telegram.
• Проверьте:
  /start
  ,
  /help
  ,
  /settings
  ,
  /privacy
  ,
  /stats
  (для ADMIN_USER_ID), не‑YouTube ссылку (ожидаем отказ), частые запросы (должен сработать рейт‑лимит).

🩺 Устранение неполадок

• `` — слишком длинный
  callback_data
  . В этом проекте решено через краткие токены и кэш.
• `` — установите
  ffmpeg
  (см. скрипты в
  scripts/
  ) или укажите
  FFMPEG_LOCATION
  в
  .env
  .
• `` — установите зависимости в активное venv:
  python -m pip install -r requirements.txt
  .
• **Смешение API **
  ** vs **
  — используйте
  python-telegram-bot==20.5
  и Python 3.12/3.11. На 3.13 рекомендуем ставить свежие колёса (
  pip
  с
  --no-cache-dir
  ) или временно использовать 3.12.

📦 Совместимость

• Рекомендованный Python: 3.12 (поддерживается 3.11).
• Python 3.13: возможны нюансы при установке некоторых зависимостей; если столкнётесь — используйте Docker или 3.12.

🗺 План развития

• Очередь задач + прогресс‑индикаторы.
• История загрузок для пользователя.
• Автодетект музыки/подкастов, нормализация аудио.
• Доп. источники (TikTok/Reels) — при соблюдении правил платформ.

📄 Лицензия

MIT — см. файл

🙋 Поддержка

Создавайте Issue в репозитории — приложите логи запуска, версию Python, ОС и шаги воспроизведения.