TGD

Языки: Русский | English

Мощный загрузчик медиафайлов из Telegram каналов и групп, оптимизированный для работы с большим количеством файлов.

Основные возможности

Умный менеджер закачек и высокая скорость загрузки:
- Раздельные очереди для «тяжёлых» и «лёгких» файлов.
- Тяжёлые файлы (по умолчанию > 100 МБ) скачиваются через FastTelethonhelper с использованием нескольких параллельных соединений.
- Лёгкие файлы скачиваются параллельно в несколько потоков, не дожидаясь завершения тяжёлых закачек.
Устойчивость: Автоматические повторные попытки при сбоях, обработка таймаутов и поддержка 2FA (двухфакторной аутентификации).
Режим демона (Daemon / WebUI):
- Автономный запуск в фоновом режиме на NAS / серверах с веб-интерфейсом (http://localhost:8080).
- Управление списками каналов и тем: интерактивный запуск («Старт») и безопасная мягкая отмена («Стоп»).
- Soft-Stop: отмена моментально прекращает взятие новых файлов из очереди Telegram, давая текущим активным загрузкам завершиться без повреждений.
- Отображение текущей скорости в MB/s, прогресса и количества файлов через Server-Sent Events (SSE) в реальном времени.
Поддержка прокси (MTProto/SOCKS5/HTTP): Встроенная возможность пропускать трафик через прокси для обхода блокировок. Поддерживаются официальные ссылки Telegram (tg://proxy?...), включая FakeTLS MTProxy (секреты, начинающиеся с ee).
Прогресс-бары: Наглядное отображение процесса загрузки для каждого файла с помощью tqdm в консоли.

Установка

Вы можете использовать скомпилированную версию для Windows (не требует установки Python) или запускать скрипт из исходников.

Вариант 1: Для Windows (Простой способ)

Перейдите в раздел Releases и скачайте последнюю версию tgd.exe.
Поместите файл в удобную для вас папку.
Запустите tgd.exe. Программа создаст конфигурацию (.env), которую необходимо отредактировать (раздел Настройка).

Вариант 2: Для Linux / NAS / Запуска из исходников

Требования: Python 3.9 или новее (рекомендуется Python 3.11+).

Склонируйте репозиторий:

git clone https://github.com/tatarinovs/tgd.git
cd tgd

Установите зависимости:
```
pip install -r requirements.txt
```
Для проверки целостности медиафайлов (verify.py) установите дополнительные библиотеки:
```
pip install Pillow av
```
Запуск осуществляется через вызов исходных файлов из папки src:
```
python src/tgd.py
python src/verify.py
```

Note

Далее в примерах команд используется tgd. На Windows это означает запуск tgd.exe, а при работе из исходников — python src/tgd.py.

Настройка

Создайте файл .env в корневой директории проекта или в папке программы и добавьте туда свои данные от Telegram API:

APP_API_ID=ваш_api_id
APP_API_HASH=ваш_api_hash
PHONE_NUMBER=+79991234567

# Дополнительные параметры (опционально):
# DEFAULT_DOWNLOAD_DIR=downloads # Папка для сохранения файлов по умолчанию
# PROXY=socks5://192.168.1.10:10808
# PROXY=tg://proxy?server=192.168.1.10&port=443&secret=...
# TIMEOUT=3600
# TIMEOUT_PER_MB=6       # Доп. секунды таймаута на каждый МБ файла (0 — единый TIMEOUT)
# RETRIES=3
# WORKERS=6              # Количество потоков для легких файлов
# HEAVY_WORKERS=1        # Количество потоков для тяжелых файлов
# HEAVY_THRESHOLD=100    # Порог "тяжелого" файла в МБ
# QUEUE_SIZE=50          # Максимальная длина очереди файлов (глубина предзагрузки)
# TOPIC_SUBDIR=1         # Каждая тема форума — в свою подпапку
# INCREMENTAL=0          # Качать только сообщения новее прошлого успешного запуска
# WEBUI_USER=admin       # Логин веб-интерфейса (см. раздел про демона)
# WEBUI_PASS=            # Пароль веб-интерфейса

Tip

INCREMENTAL=1 резко ускоряет повторные прогоны больших каналов, но помните: файл, удалённый с диска вручную или через tgv --delete, заново скачан не будет — демон запоминает ID последнего обработанного сообщения.

Как получить API ID и Hash:

Перейдите на сайт my.telegram.org.
Авторизуйтесь под своим номером телефона (код придет в само приложение Telegram).
Перейдите в раздел "API development tools".
Создайте новое приложение (заполните App title и Short name любыми значениями, например MyDownloader).
После нажатия "Create application" вы увидите App api_id и App api_hash.
Скопируйте их и вставьте в соответствующие поля в файле .env.

Important

Никогда не передавайте ваш api_hash третьим лицам. Это секретный ключ вашего приложения.

Режим демона (Daemon Mode & WebUI)

TGD умеет работать как круглосуточный фоновый сервис на домашнем сервере или NAS (Synology, QNAP, Raspberry Pi, Linux, OpenWrt, Windows).

Запуск демона

# Запуск веб-сервера на локальном адресе (127.0.0.1:8080)
tgd --daemon

# Запуск с доступом по локальной сети / извне (0.0.0.0:8080)
tgd --daemon --addr 0.0.0.0:8080

# Запуск с указанием конкретной папки для сохранения данных и сессий
tgd --daemon --addr 0.0.0.0:8080 --data /var/lib/tgd

После запуска откройте браузер по адресу http://<IP_СЕРВЕРА>:8080.

Warning

По умолчанию веб-интерфейс работает без авторизации. Если --addr смотрит не в 127.0.0.1, задайте в .env:

WEBUI_USER=admin
WEBUI_PASS=длинный_пароль

Тогда включается HTTP Basic-авторизация; без неё демон при старте пишет предупреждение в лог. Basic-авторизация передаёт пароль в открытом виде, поэтому для доступа из интернета всё равно используйте VPN или Reverse Proxy с HTTPS. Запросы с чужих сайтов (CSRF) блокируются проверкой заголовка Origin.

Возможности WebUI:

Управление задачами: Добавление каналов/групп/тем через ссылки https://t.me/..., @username или ID.
Старт / Стоп:
- Старт: Запуск скачивания выбранного канала или темы.
- Стоп: Мягкая остановка. Прекращает взятие новых файлов из очереди Telegram и корректно докачивает текущие активные файлы, не повреждая их.
Живое отслеживание (SSE): Скорость закачки в MB/s, количество новых и существовавших файлов обновляются в WebUI без перезагрузки страницы.
Устойчивость: Сохранение списка групп и их статусов в groups.json. При перезапуске демона незавершенные задачи авто-восстанавливаются в статус «Прервано».

Настройка автозапуска на Linux / NAS

1. Вариант через systemd (рекомендуется)

Создайте файл /etc/systemd/system/tgd.service:

[Unit]
Description=TGD Telegram Downloader Daemon
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/tgd
ExecStart=/opt/tgd/venv/bin/python src/tgd.py --daemon --addr 0.0.0.0:8080
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Включите и запустите сервис:

sudo systemctl daemon-reload
sudo systemctl enable --now tgd

2. Вариант через nohup (простой запуск)

nohup python src/tgd.py --daemon --addr 0.0.0.0:8080 > tgd.log 2>&1 &

Консольное использование (CLI)

Запустите скрипт через терминал для разового скачивания:

tgd [GROUP_ID] [OUTPUT_DIR]
# или из исходников:
python src/tgd.py [GROUP_ID] [OUTPUT_DIR]

Параметры:

group_id: ID группы или канала: число, ссылка (https://t.me/...) или @username.
output_dir: Путь к папке, куда будут сохраняться файлы.

Дополнительные опции (имеют приоритет над `.env`):

Опция	По умолчанию	Описание
`-d`, `--daemon`	`False`	Запустить в режиме фонового демона с WebUI
`--addr`	`127.0.0.1:8080`	Адрес и порт веб-сервера (в режиме `-d`)
`--data`	—	Путь к папке данных (`groups.json`, `tg_session`)
`--env`	`.env`	Путь к файлу `.env`
`--timeout`	`3600`	Тайм-аут загрузки одного файла (сек)
`--retries`	`3`	Количество попыток при сбое
`--workers`	`6`	Потоков для лёгких файлов
`--heavy-workers`	`1`	Потоков для тяжёлых файлов
`--heavy-threshold`	`100`	Порог «тяжёлого» файла (МБ)
`--queue-size`	`50`	Максимальная длина очереди файлов (глубина предзагрузки)
`--proxy`	—	Прокси-сервер (SOCKS5/HTTP/MTProto)
`--topic`	—	Название или ID темы (форум/супергруппа)

Tip

Если в канале очень много тяжёлых файлов, увеличьте --queue-size (например, до 500), чтобы лёгкие воркеры не простаивали.

Примеры использования CLI

Обычный канал или чат

tgd -1001234567890 downloads/my_channel

Конкретный раздел (тема) в супергруппе/форуме

Вы можете указать как название темы (скрипт найдет её автоматически), так и её ID:

# По названию темы (например, "Фотографии")
tgd -1001234567890 downloads/photos --topic "Фотографии"

# По ID темы (например, 42)
tgd -1001234567890 downloads/photos --topic 42

Tip

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

Проверка целостности файлов

Для массовой проверки скачанных файлов (не битые ли они и открываются ли) предусмотрен скрипт verify.py.

tgv [ПАПКА_С_ФАЙЛАМИ]
# или из исходников:
python src/verify.py [ПАПКА_С_ФАЙЛАМИ]

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

Проверка структуры изображений (.jpg, .png, .webp, .jpeg).
Проверка видеофайлов (.mp4, .mov, .mkv, .avi, .webm) через библиотеку PyAV.
Рекурсивный поиск файлов во всех поддиректориях.
Интерактивный ввод параметров, если они не указаны при запуске.
Автоматическое удаление битых файлов с помощью флага --delete.

Пример:

tgv downloads/my_channel --delete

Name		Name	Last commit message	Last commit date
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
README_en.md		README_en.md
file_version_info.txt		file_version_info.txt
icon.ico		icon.ico
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
tgd.spec		tgd.spec
verify.spec		verify.spec
verify_file_version_info.txt		verify_file_version_info.txt
verify_icon.ico		verify_icon.ico

Navigation Menu

Repository files navigation

TGD

Основные возможности

Установка

Вариант 1: Для Windows (Простой способ)

Вариант 2: Для Linux / NAS / Запуска из исходников

Настройка

Как получить API ID и Hash:

Режим демона (Daemon Mode & WebUI)

Запуск демона

Возможности WebUI:

Настройка автозапуска на Linux / NAS

1. Вариант через systemd (рекомендуется)

2. Вариант через nohup (простой запуск)

Консольное использование (CLI)

Параметры:

Дополнительные опции (имеют приоритет над `.env`):

Примеры использования CLI

Обычный канал или чат

Конкретный раздел (тема) в супергруппе/форуме

Проверка целостности файлов

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

Пример:

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

TGD

Основные возможности

Установка

Вариант 1: Для Windows (Простой способ)

Вариант 2: Для Linux / NAS / Запуска из исходников

Настройка

Как получить API ID и Hash:

Режим демона (Daemon Mode & WebUI)

Запуск демона

Возможности WebUI:

Настройка автозапуска на Linux / NAS

1. Вариант через systemd (рекомендуется)

2. Вариант через nohup (простой запуск)

Консольное использование (CLI)

Параметры:

Дополнительные опции (имеют приоритет над .env):

Примеры использования CLI

Обычный канал или чат

Конкретный раздел (тема) в супергруппе/форуме

Проверка целостности файлов

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

Пример:

About

Topics

Resources

Stars

Watchers

Forks

Releases

Contributors

Languages

Дополнительные опции (имеют приоритет над `.env`):