Telegram Media Server

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.

• Swagger UI (интерактивная документация): http://127.0.0.1:8080/api/v1/docs (путь path: /api/v1/docs)
  Swagger UI (interactive docs): http://127.0.0.1:8080/api/v1/docs (path: /api/v1/docs)
• OpenAPI YAML: http://127.0.0.1:8080/api/v1/openapi.yaml — спецификация для людей / human-oriented spec
• OpenAPI LLM YAML: http://127.0.0.1:8080/api/v1/openapi-llm.yaml — для LLM/инструментов / LLM/tool-oriented spec

Маршруты документации при пустом 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

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

Управление загрузками / 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

Pre-commit hooks

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

make pre-commit-install

Install pre-commit hooks for automatic checks:

make pre-commit-install