Skip to content

README.md

Latest commit

 

History

History
265 lines (180 loc) · 20.8 KB

README.md

File metadata and controls

265 lines (180 loc) · 20.8 KB

CI codecov Go Report Card License

Telegram Media Server — это Telegram-бот, который принимает ссылки на стриминговое видео или торрент-файлы, загружает их и раздает во внутренней сети через DLNA-сервер (например, minidlna).
Telegram Media Server is a Telegram bot that accepts links to streaming videos or torrent files, downloads them, and distributes them on the internal network via a DLNA server (e.g., minidlna).

Особенности / Features

  • Прием ссылок / Receiving links: Поддерживает все видео-ссылки, совместимые с утилитой yt-dlp. Supports all video links compatible with the yt-dlp utility.
  • Загрузка контента / Content Download: Загружает видео и торрент-файлы с отслеживанием прогресса. Downloads videos and torrent files while tracking progress.
  • Раздача во внутренней сети / Distribution in internal network: Раздает контент через DLNA-сервер. Distributes content via a DLNA server.
  • Управление загрузками / Download Management: Позволяет просматривать и управлять загрузками через команды бота. Allows viewing and managing downloads via bot commands.
  • Авторизация пользователей / User Authorization: Доступ защищен паролями. Access is password-protected.

OpenClaw skill

An OpenClaw skill for managing TMS downloads via the REST API (add by URL/magnet/torrent, list, delete, search) lives in openclaw-skill-tms/. Install from ClawHub: clawhub install tms, or copy the openclaw-skill-tms folder into your agent's skills directory. See openclaw-skill-tms/README.md for setup (TMS_API_URL, TMS_API_KEY) and usage.

Integration requirements: the skill uses the TMS REST API (enabled by default; see .env.example — TMS_API_ENABLED, TMS_API_KEY). To have OpenClaw notified when a download completes, fails, or is stopped, configure the webhook in TMS:

  • TMS side (in .env): set TMS_WEBHOOK_URL to the OpenClaw gateway hooks endpoint (e.g. http://127.0.0.1:18789/hooks/tms). Set TMS_WEBHOOK_TOKEN to the same value as hooks.token in your OpenClaw config — TMS sends it as Authorization: Bearer <token>. Generate a token with openssl rand -hex 32 if needed.
  • OpenClaw side: enable gateway hooks and add a hook mapping for tms pointing to the path you used in TMS_WEBHOOK_URL (e.g. /hooks/tms), and set hooks.token to the same value as TMS_WEBHOOK_TOKEN.

TMS will POST JSON { id, title, status, error?, event_id } to the webhook on completion/failure/stopped. Full webhook details: openclaw-skill-tms/README.md.

REST API и Swagger / REST API and Swagger

REST API включён по умолчанию. Без TMS_API_KEY принимаются только запросы с localhost; с ключом — доступ по сети с авторизацией. Документация доступна по адресам ниже (базовый URL — TMS_API_LISTEN, по умолчанию 127.0.0.1:8080). Ссылки работают при запущенном сервере.
REST API is enabled by default. Without TMS_API_KEY, only localhost requests are accepted; with a key set, remote access with authentication is allowed. Documentation is available at the URLs below (base URL is TMS_API_LISTEN, default 127.0.0.1:8080). Links work when the server is running.

Маршруты документации при пустом TMS_API_KEY доступны только с localhost.
Documentation routes without API key are available only from localhost.

Зависимости / Dependencies

Для установки с помощью sudo make install необходимы следующие зависимости:
To build and install Telegram Media Server using sudo make install, the following dependencies are required:

  • Go: Необходим для сборки бота. Required for building the bot.
  • yt-dlp: Необходим для загрузки потокового видео. Required for downloading streaming videos.
  • aria2: Необходим для загрузки торрент-файлов (если не используется qBittorrent). Required for downloading torrents (unless qBittorrent is used).
  • qbittorrent-nox (опционально / optional): альтернатива aria2 для торрентов; при заданном QBITTORRENT_URL бот использует Web API. Установщик может настроить systemd и порт 8081. Alternative to aria2 for torrents; when QBITTORRENT_URL is set the bot uses Web API. The installer can set up systemd and port 8081.
  • minidlna (опционально / optional): Необходим для раздачи через DLNA. Required for DLNA distribution.
  • prowlarr (опционально / optional): Необходим для поиска торрентов. Required for searching torrents.

Примечание: Если вы не планируете использовать DLNA, minidlna не требуется.
Note: If you don't plan to use DLNA, minidlna is not required.

Установите зависимости с помощью пакетного менеджера вашей системы перед началом.
Install these dependencies using your system's package manager before proceeding.

Установка / Installation

Поддерживаются Arch Linux и Ubuntu/Debian. Установщик запросит обязательные параметры (токен бота, каталог загрузок, пароль админа). По выбору в меню: qBittorrent (пакетный менеджер, systemd, порт 8081), Prowlarr (на Arch — AUR через yay/paru, на Ubuntu — apt-репозиторий; порт 9696, API key подставляется автоматически), minidlna (DLNA). Индексеры в Prowlarr добавляются вручную в веб-интерфейсе.
Supported distros: Arch Linux and Ubuntu/Debian. The installer prompts for required settings, and optionally installs qBittorrent (package manager, systemd, port 8081), Prowlarr (on Arch: AUR via yay/paru; on Ubuntu: apt repo; port 9696, API key written to .env), and minidlna (DLNA). Add indexers in Prowlarr’s web UI manually.

git clone https://github.com/NikitaDmitryuk/telegram-media-server.git
cd telegram-media-server
sudo make install

Установка и настройка minidlna / Installing and configuring minidlna

Установщик может установить и настроить minidlna (media_dir = MOVIE_PATH, порт 8200). Если вы ставите вручную или через Docker:
The installer can install and configure minidlna (media_dir = MOVIE_PATH, port 8200). For manual or Docker setup:

  1. Установите minidlna / Install minidlna (например: apt install minidlna или pacman -S minidlna).

  2. Настройте minidlna / Configure minidlna: отредактируйте /etc/minidlna.conf — укажите в media_dir=V,... тот же путь, что и MOVIE_PATH в .env.
    Edit /etc/minidlna.conf: set media_dir=V,/path/to/dir to match MOVIE_PATH in .env.

  3. Запустите minidlna / Start minidlna: systemctl enable --now minidlna.

Обновление yt-dlp / Keeping yt-dlp up to date

Приложение само обновляет yt-dlp при старте и затем по расписанию (по умолчанию раз в 3 часа). Отключить или изменить интервал можно в .env — см. .env.example.
The application updates yt-dlp on start and then on a schedule (default: every 3 hours). To disable or change the interval, use .env — see .env.example.

Рекомендуется ставить yt-dlp с релизов или через pip install yt-dlp — версии из репозитория ОС часто не поддерживают самообновление.
Prefer installing yt-dlp from releases or via pip install yt-dlp; OS package versions often do not support self-update.

Конфигурация / Configuration

Файл конфигурации — .env:
The configuration file is .env:

  • При использовании sudo make install: находится в /etc/telegram-media-server/.env.
  • When using sudo make install: located at /etc/telegram-media-server/.env.
  • При использовании Docker Compose: находится в корне проекта.
  • When using Docker Compose: located in the project root.

Настройка параметров / Parameter Configuration:

Все доступные параметры конфигурации подробно описаны в файле .env.example.
All available configuration parameters are thoroughly documented in the .env.example file.

Создайте файл .env на основе .env.example и настройте необходимые параметры.
Create a .env file based on .env.example and configure the required parameters.

Docker и сеть: по умолчанию в docker-compose.yml порт API проброшен на хост (8080:8080), приложение слушает 0.0.0.0:8080 — Swagger и API доступны по http://localhost:8080 на Mac, Windows и Linux. На macOS/Windows режим network_mode: host в Docker Desktop не даёт доступа к портам контейнера с хоста, поэтому используется проброс портов. На Linux при необходимости лучшего приёма пиров для торрентов можно включить network_mode: host в docker-compose.yml (тогда порт 8080 будет доступен на хосте без явного маппинга).
Docker and network: by default, the API port is published to the host (8080:8080) and the app listens on 0.0.0.0:8080, so Swagger is at http://localhost:8080 on Mac, Windows, and Linux. On macOS/Windows, network_mode: host in Docker Desktop does not expose container ports to the host, so port mapping is used. On Linux, you can enable network_mode: host in docker-compose.yml for better torrent peer acceptance (port 8080 will then be available on the host without explicit mapping).

Docker + qBittorrent (локальная связка): в docker-compose.yml добавлен сервис qbittorrent (Web UI на порту 8081). TMS подключается по QBITTORRENT_URL=http://qbittorrent:8081. Конфиг с логином admin и паролем adminadmin подмонтирован из docker/qbittorrent.conf — в .env укажите MOVIE_PATH=/app/media и при необходимости QBITTORRENT_USERNAME=admin, QBITTORRENT_PASSWORD=adminadmin.
Docker + qBittorrent (local testing): the compose file includes a qbittorrent service (Web UI on port 8081). TMS connects via QBITTORRENT_URL=http://qbittorrent:8081. A config with login admin and password adminadmin is mounted from docker/qbittorrent.conf; set MOVIE_PATH=/app/media in .env and optionally QBITTORRENT_USERNAME=admin, QBITTORRENT_PASSWORD=adminadmin.

qBittorrent: при использовании qbittorrent-nox задайте в .env QBITTORRENT_URL (например http://localhost:8081). Чтобы не конфликтовать с API (порт 8080), запускайте qBittorrent с QBT_WEBUI_PORT=8081. Установщик настраивает systemd и порт за вас.
qBittorrent: when using qbittorrent-nox set QBITTORRENT_URL in .env (e.g. http://localhost:8081). Run with QBT_WEBUI_PORT=8081 to avoid conflict with the API (port 8080). The installer configures systemd and port for you.

Совместимость с ТВ: если видео не воспроизводится — VIDEO_COMPATIBILITY_MODE=true. Файлы при необходимости пройдут remux. Опции: VIDEO_TV_H264_LEVEL=4.0/4.1, VIDEO_REJECT_INCOMPATIBLE=true — отклонять несовместимое видео.
TV compatibility: if video won't play on your TV, set VIDEO_COMPATIBILITY_MODE=true. Files may be remuxed. Options: VIDEO_TV_H264_LEVEL=4.0/4.1, VIDEO_REJECT_INCOMPATIBLE=true — reject incompatible video.

Использование / Usage

Авторизация / Authorization

Для начала работы авторизуйтесь:
To start using the bot, log in:

/login <password>
  • Используйте ADMIN_PASSWORD для входа как администратор. Use ADMIN_PASSWORD to log in as an admin.
  • Используйте REGULAR_PASSWORD для входа как обычный пользователь. Use REGULAR_PASSWORD to log in as a regular user.

Ролевая система / Role System

Роль / Role Авторизация / Authorization Доступ / Access
Администратор / Admin Через ADMIN_PASSWORD. Authorized with ADMIN_PASSWORD. Полный доступ, включая команду /temp. Full access, including the /temp command.
Обычный пользователь / Regular User Через REGULAR_PASSWORD. Authorized with REGULAR_PASSWORD. Доступ ко всем функциям, кроме /temp. Access to all features except /temp.
Временный пользователь / Temporary User Через временный пароль от /temp. Authorized with a temporary password from /temp. Только добавление ссылок для загрузки. Can only add links for download.

Доступные команды / Available commands

Команда / Command Описание / Description
/start Приветственное сообщение. Welcome message.
/login <password> Авторизация. User authorization.
/ls Список текущих загрузок. List of current downloads.
/rm <id> Удаление загрузки по ID из /ls. Delete a download by ID from /ls.
/rm all Удаление всех загрузок. Delete all downloads.
/temp <1d | 3h | 30m> Генерация временного пароля (только для админа). Generate a temporary password (admin only).

Управление загрузками / Managing downloads

После авторизации отправляйте ссылки на видео или торренты. Бот поддерживает все ссылки, обрабатываемые yt-dlp.
After authorization, send video or torrent links. The bot supports all links processed by yt-dlp.

Примеры управления:
Examples of management:

  • /ls — показывает статус загрузок. Shows download status.
  • /rm 1 — удаляет загрузку с ID 1. Deletes download with ID 1.

Скриншоты:
Screenshots:

Управление видео Управление загрузками

Примеры поддерживаемых ссылок / Examples of supported links

Бот поддерживает все сервисы, совместимые с yt-dlp, включая:
The bot supports all services compatible with yt-dlp, including:

  • YouTube
  • VK
  • RuTube
  • И многие другие / And many others

Полный список см. в документации yt-dlp.
See the full list in the yt-dlp documentation.

Интеграция с Prowlarr / Prowlarr Integration

Prowlarr — это менеджер торрент-индексаторов, который позволяет искать торрент-файлы по множеству источников. Telegram Media Server поддерживает интеграцию с Prowlarr для поиска и скачивания торрентов прямо из Telegram. Prowlarr is a torrent indexer manager that allows searching torrent files from multiple sources. Telegram Media Server supports integration with Prowlarr for searching and downloading torrents directly from Telegram.

Как включить интеграцию / How to enable integration

  1. Установите и настройте Prowlarr.

    • Откройте веб-интерфейс Prowlarr: http://localhost:9696
    • Добавьте нужные торрент-трекеры через меню Indexers.

  2. Install and configure Prowlarr.

    • Open the Prowlarr web interface: http://localhost:9696
    • Add desired torrent trackers via the Indexers menu.

  3. Получите API-ключ Prowlarr.

    • В интерфейсе Prowlarr перейдите в Settings → General → Security и скопируйте API Key.

  4. Get the Prowlarr API key.

    • In the Prowlarr interface, go to Settings → General → Security and copy the API Key.

  5. Добавьте переменные в .env:

    PROWLARR_URL=http://localhost:9696
PROWLARR_API_KEY=ваш_ключ_от_prowlarr

    Если переменные не заданы, интеграция будет отключена.

  6. Add variables to .env:

    PROWLARR_URL=http://localhost:9696
PROWLARR_API_KEY=your_prowlarr_api_key

    If variables are not set, integration will be disabled.

Архитектура / Architecture

Architecture

Pre-commit hooks

Установка pre-commit hooks для автоматических проверок:

make pre-commit-install

Install pre-commit hooks for automatic checks:

make pre-commit-install