The tdl from annihilatorrrr

Intro

📥 Telegram Downloader, but more than a downloader 🚀

⚠ Note: Command compatibility is not guaranteed in the early stages of development

Improvements have been made to the risk of blocking, but it still can't be completely avoided. Go to Discussion for more information.

Features

Single file start-up
Low resource usage
Take up all your bandwidth
Faster than official clients
Download files from (protected) chats
Upload files to Telegram

Preview

It reaches my proxy's speed limit, and the speed depends on whether you are a premium

Install

Go to GitHub Releases to download the latest version

(optional) Use it everywhere:

# Should run as root(Administrator)
# Linux & macOS
sudo mv tdl /usr/bin
# Windows (PowerShell)
Move-Item tdl.exe C:\Windows\System32

Install with a package manager:

# Scoop (Windows) https://scoop.sh/#/apps?s=2&d=1&o=true&p=1&q=telegram+downloader
scoop bucket add extras
scoop install telegram-downloader

Quick Start

# login with existing official desktop clients (recommended)
tdl login -n quickstart -d /path/to/Desktop-Telegram-Client
# if you set a local passcode
tdl login -n quickstart -d /path/to/Desktop-Telegram-Client -p YOUR_PASSCODE
# or login with phone & code
tdl login -n quickstart

tdl dl -n quickstart -u https://t.me/telegram/193

Usage

Get help

tdl -h

Check the version

tdl version

Basic Configs

The following command documents will not write basic configs. Please add the basic configs you need.

Each namespace represents a Telegram account

You should set the namespace when each command is executed:

tdl -n iyear
# or
export TDL_NS=iyear # recommended

(optional) Set the proxy. Only support socks now:

tdl --proxy socks5://localhost:1080
# or
export TDL_PROXY=socks5://localhost:1080 # recommended

(optional) Set ntp server host. If is empty, use system time:

tdl --ntp pool.ntp.org
# or
export TDL_NTP=pool.ntp.org # recommended

Login

When you first use tdl, you need to login to get a Telegram session

If you have official desktop clients locally, you can import existing sessions.

This may reduce the risk of blocking, but is unproven:

tdl login -d /path/to/Telegram
# if you set a local passcode
tdl login -d /path/to/Telegram -p YOUR_PASSCODE

tdl login

Download

Please do not arbitrarily set too large threads and size.

The default value of options is consistent with official clients to reduce the risk of blocking.

If you need higher speed, set higher threads and size

For details: iyear#30

Advanced Options:

Flag	Default	Desc
`-t/--threads`	4	threads for transfer one item
`-s/--size`	128*1024 Bytes	part size for transfer, max is 512KiB
`-l/--limit`	2	max number of concurrent tasks
`--template`	`{{ .DialogID }}_{{ .MessageID }}_{{ .FileName }}`	file name template

Download (protected) chat files from message urls:

tdl dl -u https://t.me/tdl/1 -u https://t.me/tdl/2

Download (protected) chat files from official desktop client exported JSON:

tdl dl -f result1.json -f result2.json

You can combine sources:

tdl dl -u https://t.me/tdl/1 -u https://t.me/tdl/2 -f result1.json -f result2.json

Download with 8 threads, 512KiB(MAX) part size, 4 concurrent tasks:

tdl dl -u https://t.me/tdl/1 -t 8 -s 524288 -l 4

Download with custom file name template:

Following the go template syntax, you can use the variables:

Var	Desc
DialogID	Telegram dialog id
MessageID	Telegram message id
MessageDate	Telegram message date(ts)
FileName	Telegram file name
FileSize	Human-readable file size, like `1GB`
DownloadDate	Download date(ts)

tdl dl -u https://t.me/tdl/1 --template "{{ .DialogID }}_{{ .MessageID }}_{{ .DownloadDate }}_{{ .FileName }}"

Full examples:

tdl dl --debug --ntp pool.ntp.org -n iyear --proxy socks5://localhost:1080 -u https://t.me/tdl/1 -u https://t.me/tdl/2 -f result1.json -f result2.json -t 8 -s 262144 -l 4

Upload

Same instructions and advanced options as Download

Upload files to Saved Messages, exclude the specified file extensions:

tdl up -p /path/to/file -p /path/to/dir -e .so -e .tmp

Upload with 8 threads, 512KiB(MAX) part size, 4 concurrent tasks:

tdl up -p /path/to/file -t 8 -s 524288 -l 4

Full examples:

tdl up --debug --ntp pool.ntp.org -n iyear --proxy socks5://localhost:1080 -p /path/to/file -p /path/to/dir -e .so -e .tmp -t 8 -s 262144 -l 4

Backup

Backup or recover your data

Backup (Default: tdl-backup-<time>.zip):

tdl backup
# or specify the backup file path
tdl backup -d /path/to/backup.zip

Recover:

tdl recover -f /path/to/backup.zip

Chat Utilities

Some useful utils

List all your chats:

tdl chat ls

Export minimal JSON for tdl download (NOT for backup):

# will export all media files in the chat.
# chat input examples: `@iyear`, `iyear`, `123456789`(chat id), `https://t.me/iyear`, `+1 123456789`

tdl chat export -c CHAT_INPUT

# specify the time period with timestamp format, default is start from 1970-01-01, end to now
tdl chat export -c CHAT_INPUT --from 1665700000 --to 1665761624
# or (timestamp is default format)
tdl chat export -c CHAT_INPUT --from 1665700000 --to 1665761624 --time

# specify with message id format, default is start from 0, end to latest message
tdl chat export -c CHAT_INPUT --from 100 --to 500 --msg

# specify the output file path, default is `tdl-export.json`
tdl chat export -c CHAT_INPUT -o /path/to/output.json

Env

Avoid typing the same flag values repeatedly every time by setting environment variables.

Note: The values of all environment variables have a lower priority than flags.

What flags mean: flags

NAME	FLAG
TDL_NS	`-n/--ns`
TDL_PROXY	`--proxy`
TDL_DEBUG	`--debug`
TDL_SIZE	`-s/--size`
TDL_THREADS	`-t/--threads`
TDL_LIMIT	`-l/--limit`
TDL_NTP	`--ntp`

Data

Your account information will be stored in the ~/.tdl directory.

Commands

Go to docs for full command docs.

Best Practice

How to minimize the risk of blocking?

Login with the official client session.
Use the default download and upload options as possible. Do not set too large threads and size.
Do not use the same account to login on multiple devices at the same time.
Don't download or upload too many files at once.
Become a Telegram premium user. 😅

FAQ

Q: Is this a form of abuse?

A: No. The download and upload speed is limited by the server side. Since the speed of official clients usually does not reach the account limit, this tool was developed to download files at the highest possible speed.

Q: Will this result in a ban?

A: I am not sure. All operations do not involve dangerous actions such as actively sending messages to other people. But it's safer to use an unused account for download and upload operations.

Q: No response after entering the command?

A: Check if you need to use a proxy (use proxy flag); Check if your system's local time is correct (use ntp flag or calibrate system time)

If that doesn't work, run again with debug flag. Then file a new issue and paste your log in the issue.

LICENSE

AGPL-3.0 License

annihilatorrrr / tdl Goto Github PK

tdl's Introduction