☀️ A M A T E R A S U ☀️

      █████╗ ███╗   ███╗ █████╗ ████████╗███████╗██████╗  █████╗ ███████╗██╗   ██╗
     ██╔══██╗████╗ ████║██╔══██╗╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔════╝██║   ██║
     ███████║██╔████╔██║███████║   ██║   █████╗  ██████╔╝███████║███████╗██║   ██║
     ██╔══██║██║╚██╔╝██║██╔══██║   ██║   ██╔══╝  ██╔══██╗██╔══██║╚════██║██║   ██║
     ██║  ██║██║ ╚═╝ ██║██║  ██║   ██║   ███████╗██║  ██║██║  ██║███████║╚██████╔╝
     ╚═╝  ╚═╝╚═╝     ╚═╝╚═╝  ╚═╝   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚══════╝ ╚═════╝

The Absolute Pinnacle of Telegram Mirroring and Leeching

Telegram Channel • Support Group • Report a Bug

📑 Table of Contents

🔮 Overview
💎 Features
🧬 Architecture
⚙️ Prerequisites
🚀 Deployment
🔧 Configuration Reference
🆕 Native TeraBox Download & Selector Update
📖 Command Reference
🎞️ Encoding & Metadata
🎭 Auto-Rename Engine
🗂️ File Sorting Mode
🎨 Encoding Profile Creator (Web UI)
🔐 Google Token Generator (Web UI)
Telegram Session Generator (Web UI)
🧰 Advanced Usage & Arguments
🌐 FileToLink Streaming Server
📡 RSS Automation
🔑 User Roles & Permissions
❓ FAQ & Troubleshooting

🔮 Overview

Amaterasu is a feature-dense, production-ready Telegram bot designed for power users who need a single interface to download from virtually any source on the internet, and then upload the result to a cloud drive or back to Telegram — all from a chat window.

It converges five industrial download engines (Aria2c, qBittorrent, JDownloader, Sabnzbd, yt-dlp), TeraBox download support, and multiple storage backends (Google Drive, Rclone remotes, Telegram, DDL hosters) into one cohesive, self-hosted system.

Important

Amaterasu also ships with a built-in FileToLink streaming web server. Any file uploaded to a designated Telegram channel can be instantly converted into a direct HTTP stream link — seekable, resumable, and playable in VLC, MX Player, or any browser.

💎 Features

🌐 FileToLink Gateway Instantly spawn HTTP 206 streamable links from Telegram files. Features automated Multi-Token Load Balancing across multiple bot tokens to evade FloodWait penalties and maintain zero latency under heavy load.	🎭 Auto-Rename Engine Intercept any leech task or upload to automatically rename it before uploading. Supports robust auto-rename templates (e.g. `/autorename`) for batch operations and dynamic media grouping.
🌩️ Multi-Engine Downloads Pull from Torrents (Aria2c + qBittorrent), Direct Links, Usenet (Sabnzbd), Mega, TeraBox, JDownloader, and 1800+ sites via yt-dlp. Every engine has its own size limits and queue management.	🛡️ Enterprise Resilience MongoDB-backed persistence for all user configs, queuing, and task state. Automated retries, dynamic polling, and graceful FloodWait handling ensure zero data loss even on restart.

Full Feature List

Category	Features
Download Sources	Direct links, recursive Google Drive Index folders, Torrents (magnet & .torrent), Mega, TeraBox, Google Drive, Rclone remotes, Usenet (NZB), JDownloader, YouTube & 1800+ yt-dlp sites, Telegram files & links
Upload Destinations	Google Drive, Rclone remotes (OneDrive, Dropbox, S3, etc.), Mega, Telegram (as document or media), DDL hosters (GoFile, BuzzHeavier, PixelDrain, DevUploads, VikingFile)
Leech Features	Custom prefixes & suffixes, captions, auto-split for large files, hybrid leech (bot + user session), equal splits, media grouping, thumbnail layouts
Media Processing	FFmpeg integration, audio/video conversion (`-ca`, `-cv`), custom metadata injection (`-meta`), sample video generation (`-sv`), screenshot extraction (`-ss`), MediaInfo reports
File Management	Extract (`.zip`, `.rar`, `.7z`, `.tar`), archive with password, join split files, rename, auto-rename templates, name substitution via regex
Search	Torrent search via qBittorrent plugins, Google Drive search, Usenet/NZBHydra search, IMDB lookup
Automation	RSS feed monitoring with include/exclude filters, bulk download from text files, multi-link batch processing
Streaming	Built-in FileToLink web server with token-based access control, URL shortening, rate limiting, and multi-bot load balancing
Telegram UX	NEO-inspired `✦` panel cards, compact information-preserving task rows, consistent navigation/action labels, and an unchanged monospace System Metrics block
Admin Tools	Shell access, async/sync Python exec, log retrieval, broadcast messaging, session restart, user management
Runtime	Python Telegram bot + web UI
Deployment	Docker & Docker Compose (buildx)
Required config	`BOT_TOKEN`, `TELEGRAM_API`, `TELEGRAM_HASH`, `OWNER_ID`, `DATABASE_URL`
License	LICENSE

🧬 Architecture

graph TD
    A[Telegram User] -->|Commands / Files| B((Amaterasu Core))
    B --> L[(MongoDB)]
    
    B --> C{Download Engines}
    C -->|Torrents| D[qBittorrent & Aria2c]
    C -->|Usenet| E[Sabnzbd]
    C -->|Direct/Links| F[JDownloader & yt-dlp]
    C -->|Cloud| M[Mega & TeraBox]
    
    B -.->|Telegram Files| N
    C -->|Downloaded Files| N{Media Processing}
    N -->|SVT-AV1 / HEVC| O[FFmpeg Encoding]
    N -->|Regex| P[Auto-Rename & Meta]
    N -->|Archives| Q[Extract / Split / Join]

    N --> G{Storage & Distribution}
    
    G -->|Cloud Drives| H[Google Drive, Rclone & Mega]
    G -->|Direct Download| I[FileToLink Server]
    G -->|Telegram| J[Leech Uploader]
    G -->|DDL Hosters| K[GoFile / BuzzHeavier / PixelDrain / DevUploads / VikingFile]
    
    style B fill:#FF4500,stroke:#333,stroke-width:2px,color:#fff
    style A fill:#2496ED,color:#fff
    style I fill:#28a745,color:#fff
    style L fill:#4DB33D,color:#fff
    style N fill:#9370DB,color:#fff

Technology Stack

Component	Technology
Language	Python 3.11
Telegram Framework	WZGram 3.1.5 (`pyrogram` API)
Web Server	FastAPI + Uvicorn
Database	MongoDB (Motor async driver)
Containerization	Docker / Podman
Torrent Client	qBittorrent-nox + Aria2c
Usenet Client	Sabnzbd
Cloud Sync	Google Drive, Rclone, Mega; TeraBox is download-only (`aioterabox`)
Media Toolkit	FFmpeg, yt-dlp, MediaInfo

⚙️ Prerequisites

Before deploying Amaterasu, you will need:

Requirement	Where to Get It	Notes
Telegram API ID & Hash	my.telegram.org	Create an application under "API Development Tools"
Bot Token	@BotFather	Send `/newbot` and follow the prompts
MongoDB URI	MongoDB Atlas (free tier) or self-hosted	Format: `mongodb+srv://user:pass@cluster.mongodb.net/dbname`
Owner ID	@MissRose_bot or @userinfobot	Send `/id` to get your numeric Telegram User ID
VPS / Server	Any Linux VPS (Ubuntu/Debian recommended)	Minimum: 1 CPU, 1 GB RAM, 20 GB disk (2 GB+ RAM recommended for heavy media)
Google Drive (optional)	Google Cloud Console	Generate `token.pickle` or Service Account keys for GDrive uploads
User Session String (optional)	Generate with WZGram's compatible session API	Needed for downloading restricted Telegram content or uploading files > 2 GB

🚀 Deployment

Step 1: Prepare Your Server

Important

Minimum Requirements: 1 vCPU, 1 GB RAM, 20 GB SSD. Recommended: 2 vCPU, 2+ GB RAM, 40+ GB SSD (for heavy media processing, FFmpeg, and extraction).

Connect to your VPS and install the container runtime of your choice:

Install Docker + Docker Compose (Ubuntu/Debian)

# Update system
sudo apt update && sudo apt upgrade -y

# Install Docker
curl -fsSL https://get.docker.com | sh

# Install Docker Compose plugin
sudo apt install docker-compose-plugin -y

# Verify installation
docker --version
docker compose version

Install Podman (Ubuntu/Debian)

sudo apt update && sudo apt upgrade -y
sudo apt install podman -y

# Verify installation
podman --version

Step 2: Clone & Configure

# Clone the repository
git clone https://github.com/Zan-getsu/Amaterasu.git && cd Amaterasu


# Create your config file from the sample
cp config_sample.py config.py

# Edit config with your credentials
nano config.py

Inside config.py, fill in the 5 mandatory variables at minimum:

# ==========================================
# 1. REQUIRED CONFIGURATION
# ==========================================
BOT_TOKEN = "123456:ABC-DEF1234..."       # From @BotFather
OWNER_ID = 123456789                       # Your numeric Telegram User ID
TELEGRAM_API = 12345678                    # From my.telegram.org
TELEGRAM_HASH = "0123456789abcdef..."      # From my.telegram.org
DATABASE_URL = "mongodb+srv://user:pass@cluster.mongodb.net/amaterasu"  # MongoDB URI

Tip

You can also set these as environment variables instead of editing config.py. The bot checks both — environment variables take priority over the config file. This is useful for PaaS deployments.

Step 3: Optional Files Setup

These files are not required but unlock additional functionality. Place them in the project root directory (/Amaterasu/).

File	Purpose	How to Generate
`token.pickle`	Google Drive authentication (OAuth2 token)	Send `/tokengen`, create a Google OAuth Web application client, upload `credentials.json`, then download or activate the generated token
`accounts.zip`	Service Account keys for GDrive (bypasses quota limits)	Create multiple Service Accounts in GCP → download JSON keys → zip all `.json` files into `accounts.zip`
`rclone.conf`	Rclone remote configurations for cloud storage	Run `rclone config` on your local machine → copy `~/.config/rclone/rclone.conf` to the project
`cookies.txt`	Browser cookies for authenticated site downloads	Export cookies from your browser using a "Get cookies.txt" extension (Netscape format)
`terabox.txt`	Owner/global TeraBox account cookie	Export a logged-in Netscape cookie file containing `ndus`; install through `/bsetting` → Private Files
`.netrc`	Machine-level login credentials for FTP/HTTP sites	Create manually: `machine host login user password pass`
`list_drives.txt`	Multiple GDrive destinations with labels	Format: `Drive Name gdrive_folder_id index_url` (one per line)
`shortener.txt`	URL shortener configuration	Format per line: `domain shortener_api_url shortener_api_key`

Note

All of these can also be uploaded later via the /bsetting (Bot Settings) panel in Telegram — no server SSH required.

Step 4: Build & Launch

Choose one of the following deployment methods:

Method A: Docker Compose ⭐ (Recommended)

To cap the bot container's memory, set this in the checkout's .env file:

AMATERASU_MEMORY_LIMIT=10g

10g means 10 GiB. Change it to your chosen Docker memory value, such as 4g. The cap covers all processes inside the bot container, including FFmpeg and download engines. Swap is disabled when a positive cap is set, so it cannot consume additional memory through swap. The optional tunnel sidecar is a separate container and is not included in this cap. Unset or 0 preserves the existing unlimited default; this setting belongs in .env, not config.py.

Apply changes by recreating the container (restart alone does not apply them):

docker compose up -d --force-recreate amaterasu
docker inspect amaterasu-bot --format 'RAM={{.HostConfig.Memory}} RAM+swap={{.HostConfig.MemorySwap}}'

For 10g, both inspected values should be 10737418240 bytes. Use -f docker-compose.dev.yml for a source build. At the cap, Linux may kill a process or the container; the existing restart policy restarts the container if it exits. Choose a cap below the VPS's total RAM to leave room for the OS and other services.

# Build the image and start in detached mode
sudo docker compose up --build -d

# Watch live logs
sudo docker compose logs -f

The docker-compose.yml is pre-configured with:

network_mode: bridge — uses the container engine's default bridge and publishes the portal on host port 82. Download engines communicate inside the bot container, and the optional tunnel shares its network namespace. Podman's default bridge avoids an Aardvark DNS listener that could conflict with a VPS's dnsmasq on port 53. Service-name DNS between separate containers is unavailable on the default bridge.
Container DNS — defaults to 1.1.1.1 and 8.8.8.8, avoiding inherited host-only resolvers that bridge containers cannot reach. For provider/private DNS, set AMATERASU_DNS_PRIMARY and AMATERASU_DNS_SECONDARY to reachable resolver IPs in .env, then recreate the container. Public DNS does not resolve private Tailscale names; deployments using those names need a reachable private resolver. The VPS host's DNS configuration is unchanged.
restart: always — auto-restarts on crash or server reboot.
Volume mount (.:/usr/src/app:z) — your local config.py, token.pickle, etc. are live-synced into the container.
Safe update default (AUTO_UPDATE=false) — container startup does not modify the bind-mounted Git checkout. Compose passes AUTO_UPDATE through only when it is explicitly set, so an unset environment does not override config.py or the System & Automation setting saved in MongoDB. The entry in .env.example is intentionally commented; uncomment it only when an environment-level override is desired.

Method B: Docker (Manual)

# Build the image
sudo docker build -t amaterasu .

# Run with host networking (recommended for torrents)
sudo docker run -d --name amaterasu --restart always --network host \
  -v $(pwd):/usr/src/app:z \
  -e TZ=Asia/Dhaka \
  amaterasu

# View logs
sudo docker logs -f amaterasu

Method C: Podman

Use the same Compose files and .env memory limit as Docker. For rootful Podman with a Docker Compose provider, enable its API socket once during setup:

sudo systemctl enable --now podman.socket

# Start or recreate the bot
sudo podman compose up -d --force-recreate amaterasu

# View logs
sudo podman compose logs -f amaterasu

For a source build, add -f docker-compose.dev.yml after podman compose and use up --build -d --force-recreate amaterasu. If using the optional tunnel profile, recreate both containers with sudo podman compose --profile tunnel up -d --force-recreate. Recreation interrupts running tasks. The default bridge avoids the port-53 collision without changing the VPS's DNS services or Podman's global DNS port. An existing deployment switches networks when its container is recreated; no manual removal of the old project network is required.

If Docker also runs on the VPS, its forwarding firewall can block rootful Podman even when DNS works on the host. Install the forwarding maintenance once on the VPS host (requires Python 3, systemd, and iptables):

sudo python3 scripts/setup_podman_firewall.py

This installs a systemd timer that checks every 15 seconds, detects the bot's current IPv4 address on Podman's default bridge, and maintains exceptions in DOCKER-USER. It allows the bot's outbound traffic, replies, and new inbound traffic only through explicitly forwarded ports. It leaves the forwarding policy and other firewall rules intact, clears old bot addresses when the container stops or changes, and does nothing when DOCKER-USER is absent. After reboot, recreation, or a firewall reload, recovery can take about 16 seconds once the network exists. Run the setup command again after updating this tool to refresh its installed copy.

sudo systemctl status amaterasu-podman-firewall.timer
sudo journalctl -u amaterasu-podman-firewall.service --no-pager -n 30

If you previously added temporary rules for 10.88.0.2, remove those two rules after verifying connectivity with the maintenance service installed; otherwise the old address keeps its exception after recreation:

sudo iptables -w -D DOCKER-USER -i podman0 -s 10.88.0.2/32 -m conntrack --ctstate NEW,ESTABLISHED,RELATED -j ACCEPT
sudo iptables -w -D DOCKER-USER -o podman0 -d 10.88.0.2/32 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

To stop maintenance and remove only this tool's exceptions:

sudo systemctl disable --now amaterasu-podman-firewall.timer
sudo systemctl stop amaterasu-podman-firewall.service
sudo iptables -w -D DOCKER-USER -j AMATERASU-PODMAN
sudo iptables -w -F AMATERASU-PODMAN
sudo iptables -w -X AMATERASU-PODMAN

Method D: Cloud Platforms (Heroku / Railway / Render / CapRover)

Fork this repository to your GitHub account.
Connect your PaaS dashboard to the forked repo.
Set environment variables matching the mandatory config variables (BOT_TOKEN, OWNER_ID, TELEGRAM_API, TELEGRAM_HASH, DATABASE_URL).
Deploy — the Dockerfile and captain-definition handle everything automatically.

Warning

Most free-tier PaaS platforms have ephemeral storage. Files will be lost on restart. Use MongoDB-backed config (the default) and cloud storage (GDrive/Rclone) instead of local paths.

🔄 What Happens on Boot?

When the container starts, Amaterasu executes a precise boot sequence:

start.sh → update.py → python3 -m bot

Step	What It Does
1. Safe Update Check	Does not touch Git by default. With `AUTO_UPDATE=true`, fetches and fast-forwards only a clean, matching branch; dirty, ahead, detached, or diverged trees are skipped unchanged
2. Package Update	Runs `uv pip install -U -r requirements.txt` to sync Python dependencies (disable with `UPDATE_PKGS = False`)
3. Config Import	Loads `config.py` → merges with saved config from MongoDB → environment variables override both
4. Engine Boot	Starts Aria2c (with auto-fetched tracker lists), qBittorrent-nox, Sabnzbd, and JDownloader (if configured)
5. Telegram Connect	Initializes the bot client, user session(s), and helper/stream bot tokens
6. FileToLink Server	Launches the FastAPI + Uvicorn web server on the configured `PORT`
7. Ready	Registers command handlers and begins responding to Telegram messages

Note

Automatic Git updates are opt-in. With AUTO_UPDATE=false, update on the host with git pull and then run docker compose up -d. With AUTO_UPDATE=true, container startup and Telegram hard/soft restarts fetch and fast-forward automatically whenever the checkout is clean and aligned with UPSTREAM_BRANCH.

🌐 Reverse Proxy Setup (Optional)

If you want to serve the FileToLink streaming server over HTTPS with a custom domain:

Nginx Example

server {
    listen 443 ssl http2;
    server_name stream.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/stream.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/stream.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:83;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;        # Required for streaming
        proxy_request_buffering off;
    }
}

Then in config.py:

BASE_URL = "https://stream.yourdomain.com"
PORT = 83        # Internal port (not exposed publicly)

Caddy Example (Auto-SSL)

stream.yourdomain.com {
    reverse_proxy localhost:83
}

Caddy automatically provisions and renews SSL certificates. Set the same config.py values as the Nginx example.

Cloudflare Tunnel Setup

Amaterasu can start cloudflared from its own config. This keeps Cloudflare Tunnel controlled by config.py, environment variables, MongoDB-backed /bsetting, and the normal bot settings UI.

Use a quick tunnel only for testing. Cloudflare gives a temporary trycloudflare.com URL, and that URL changes whenever the tunnel restarts.

CLOUDFLARE_TUNNEL_ENABLED = True
CLOUDFLARE_TUNNEL_TOKEN = ""
CLOUDFLARE_TUNNEL_TARGET = ""
CLOUDFLARE_TUNNEL_AUTO_URL = True

With CLOUDFLARE_TUNNEL_AUTO_URL = True, Amaterasu watches the cloudflared logs, captures the generated trycloudflare.com URL, and updates BASE_URL in memory. If MongoDB is configured, it also saves the new BASE_URL.

The legacy Compose sidecar tunnel is opt-in. Start it only when you explicitly want the separate sidecar flow:

docker compose --profile tunnel up -d

For production, use a named tunnel with your own domain:

Open the Cloudflare dashboard.
Go to Zero Trust -> Networks -> Tunnels.
Create a Cloudflared tunnel and copy its token.
Add a public hostname pointing to http://localhost:8080.
Set the token in config.py or /bsetting:

CLOUDFLARE_TUNNEL_ENABLED = True
CLOUDFLARE_TUNNEL_TOKEN = "eyJ..."
CLOUDFLARE_TUNNEL_TARGET = ""
BASE_URL = "https://stream.yourdomain.com"
PORT = 8080

The Cloudflare config variables are:

Variable	Purpose
`CLOUDFLARE_TUNNEL_ENABLED`	Starts or stops `cloudflared` with Amaterasu
`CLOUDFLARE_TUNNEL_TOKEN`	Named tunnel token. Empty means quick tunnel
`CLOUDFLARE_TUNNEL_TARGET`	Local URL to expose. Empty means `http://127.0.0.1:PORT`
`CLOUDFLARE_TUNNEL_METRICS`	Local metrics listener, default `127.0.0.1:49312`
`CLOUDFLARE_TUNNEL_AUTO_URL`	Auto-save the generated quick tunnel URL

Why this is safer than always-on tunnel containers or separate .env files:

Normal deployments are unchanged unless CLOUDFLARE_TUNNEL_ENABLED is set.
The tunnel token lives in the same config path as the rest of Amaterasu.
/bsetting can enable, disable, or restart the tunnel without editing Compose.
Quick tunnel URLs can be captured automatically, while named tunnels stay stable for production.

Troubleshooting:

Symptom	Fix
Tunnel starts but links still point to an IP or old domain	Update `BASE_URL` to your public Cloudflare URL
Named tunnel refuses to start	Confirm `CLOUDFLARE_TUNNEL_TOKEN` is set correctly in config
Quick tunnel URL changed after restart	Expected behavior. Use a named tunnel for stable links
FileToLink or player page loads but streams fail	Make sure the Cloudflare public hostname points to `http://localhost:8080` and `PORT=8080` matches the bot web port

🛠️ Maintenance & Operations

Action	Docker Compose	Podman	Direct Docker
Stop	`sudo docker compose stop`	`sudo podman stop amaterasu`	`sudo docker stop amaterasu`
Start	`sudo docker compose start`	`sudo podman start amaterasu`	`sudo docker start amaterasu`
Restart	`sudo docker compose restart`	`sudo podman restart amaterasu`	`sudo docker restart amaterasu`
Rebuild	`sudo docker compose up --build -d`	`sudo podman build -t amaterasu . && podman run ...`	`sudo docker build -t amaterasu . && docker run ...`
View Logs	`sudo docker compose logs -f`	`sudo podman logs -f amaterasu`	`sudo docker logs -f amaterasu`
Shell Into	`sudo docker compose exec amaterasu bash`	`sudo podman exec -it amaterasu bash`	`sudo docker exec -it amaterasu bash`
Disk Cleanup	`sudo docker system prune -af`	`sudo podman system prune -af`	`sudo docker system prune -af`

Tip

Safe Update Workflow: Run git pull as the host user, then docker compose up -d. A plain container restart never rewrites the checkout when AUTO_UPDATE=false (the default). Rebuild the local image when application files, Dockerfile, or dependencies change; the published-image Compose file pulls the published image according to its pull policy.

🔧 Configuration Reference

All variables go inside config.py. Copy config_sample.py as your starting template. In Telegram, /bsetting organizes these variables by feature category and also provides an alphabetical All Variables view; shared values such as BASE_URL live under General.

1. Required (Mandatory)

Variable	Type	Description
`BOT_TOKEN`	`str`	Bot token from @BotFather
`OWNER_ID`	`int`	Your Telegram User ID (numeric)
`TELEGRAM_API`	`int`	API ID from my.telegram.org
`TELEGRAM_HASH`	`str`	API Hash from my.telegram.org
`DATABASE_URL`	`str`	MongoDB connection string

2. Telegram Client & Sessions

Variable	Type	Default	Description
`USER_SESSION_STRING`	`str`	`""`	WZGram-compatible session string for a user account. Required for restricted content downloads and uploads >2 GB
`HELPER_TOKENS`	`str`	`""`	Space-separated helper bot tokens used by HyperDL/HyperUP parallel Telegram transfers
`USE_HELPER_BOTS_FOR_FILETOLINK`	`bool`	`True`	Also use `HELPER_TOKENS` as FileToLink stream workers. Set `False` if helpers cannot read the effective BIN channel
`FILETOLINK_ADAPTIVE_STREAMING`	`bool`	`True`	Use the WZML-X adaptive MTProto range engine; automatically falls back to WZGram's native streamer before response bytes start
`FILETOLINK_GETFILE_CONCURRENCY`	`int`	`8`	Maximum concurrent Telegram `GetFile` requests per FileToLink stream bot. Valid range: 1–32
`FILETOLINK_PREFETCH_CHUNKS`	`int`	`4`	Maximum ordered look-ahead chunks per transfer; capped by concurrency and reduced automatically under load
`HELPER_STRINGS`	`str`	`""`	Space-separated helper user session strings. These clients can start with the bot, but HyperDL/HyperUP currently uses helper bot tokens as its active worker pool
`HELPER_BOT_PROXIES`	`str`	`""`	Optional newline-separated proxy dictionaries for `HELPER_TOKENS`, one proxy per helper bot
`HELPER_USER_PROXIES`	`str`	`""`	Optional newline-separated proxy dictionaries for `HELPER_STRINGS`, one proxy per helper user
`DEFAULT_LANG`	`str`	`""`	Default language code for the bot
`TG_PROXY`	`dict`	`{}`	Proxy config for WZGram (`{"scheme": "socks5", "hostname": "...", "port": ...}`)
`BOT_PM`	`bool`	`False`	If `True`, bot sends task completion messages in PM
`BOT_MAX_TASKS`	`int`	`0`	Global maximum concurrent tasks (0 = unlimited)
`USER_MAX_TASKS`	`int`	`0`	Per-user maximum concurrent tasks
`USER_TIME_INTERVAL`	`int`	`0`	Minimum seconds between user commands (anti-spam)
`VERIFY_TIMEOUT`	`int`	`0`	Verification timeout in seconds
`LOGIN_PASS`	`str`	`""`	Password for `/login` command (restricts unauthorized access)
`SET_COMMANDS`	`bool`	`True`	If `True`, registers bot commands in Telegram's command menu
`TIMEZONE`	`str`	`""`	Timezone for messages and the daily 06:00 automatic restart (e.g., `Asia/Dhaka`)

3. Chat & Permissions

Variable	Type	Default	Description
`CMD_SUFFIX`	`str`	`""`	Suffix appended to all commands (useful when running multiple bot instances)
`AUTHORIZED_CHATS`	`str`	`""`	Space-separated chat IDs where bot will respond
`SUDO_USERS`	`str`	`""`	Space-separated user IDs with elevated privileges
`FORCE_SUB_IDS`	`str`	`""`	Channel IDs users must join before using the bot
`BANNED_CHANNELS`	`str`	`""`	Blocked channel IDs

4. Leech & Upload Settings

Variable	Type	Default	Description
`DEFAULT_UPLOAD`	`str`	`""`	Default upload mode: `gd` (Google Drive), `rc` (Rclone), or `mega`
`AS_DOCUMENT`	`bool`	`False`	Upload files as documents instead of media (preserves original filename)
`EQUAL_SPLITS`	`bool`	`False`	Split files into equal-sized parts instead of Telegram's default
`MEDIA_GROUP`	`bool`	`False`	Send split files as a media group (album)
`TRANSMISSION_MODE`	`str`	`both`	Telegram upload mode: `bot`, `user`, or `both`
`USE_HYPER`	`bool`	`True`	Enable HyperDL/HyperUP acceleration when helper bots and `LEECH_DUMP_CHAT` are configured
`HYPER_THREADS`	`int`	`0`	Number of helper workers used for HyperDL. `0` lets Amaterasu choose automatically
`HYPER_PIPELINE`	`int`	`4`	Concurrent Telegram `GetFile` request depth per HyperDL worker group
`HYPER_CHUNK`	`int`	`1048576`	HyperDL working chunk size. Telegram requests are normalized to 1 MiB
`LEECH_PREFIX`	`str`	`""`	Text prepended to every uploaded filename
`LEECH_SUFFIX`	`str`	`""`	Text appended to every uploaded filename
`LEECH_FONT`	`str`	`""`	Caption font style: `b`, `i`, `u`, `s`, `code`, or `spoiler`; each user can override it from `/usetting` → Leech Settings
`LEECH_CAPTION`	`str`	`""`	Custom caption template for uploaded files
`THUMBNAIL_LAYOUT`	`str`	`""`	Default thumbnail layout (e.g., `3x3`)
`EXCLUDED_EXTENSIONS`	`str`	`""`	Space-separated file extensions to skip during upload

HyperDL / HyperUP Setup

HyperDL and HyperUP accelerate Telegram-to-server downloads and server-to-Telegram uploads by using extra helper bot clients. HyperDL splits eligible files across helpers: files of at least 10 MiB use one or more available HyperDL lanes first, while simultaneous overflow and any integrity/setup failure use WZGram. The normal transfer path remains active whenever the required Hyper setup is unavailable.

Minimum working config:

USE_HYPER = True
LEECH_DUMP_CHAT = "-1001234567890"
HELPER_TOKENS = "123456:AA... 234567:BB... 345678:CC..."
USE_HELPER_BOTS_FOR_FILETOLINK = True

Required setup:

Create one or more extra Telegram bots with @BotFather. Do not reuse BOT_TOKEN.
Add the main bot and every helper bot to LEECH_DUMP_CHAT.
Give the bots permission to send messages/files in that chat. For channels, make them admins.
Put the helper bot tokens in HELPER_TOKENS, separated by spaces.
Restart the bot and check logs for lines like Helper Bot [...] Started!.

How it is used:

Path	Requirement	Behavior
HyperDL	`USE_HYPER=True`, `HELPER_TOKENS`, `LEECH_DUMP_CHAT`	Files at least 10 MiB are copied to `LEECH_DUMP_CHAT`, then helper bots download different byte ranges in parallel; WZGram handles overflow and fallback
HyperUP	`USE_HYPER=True`, `HELPER_TOKENS`, `LEECH_DUMP_CHAT`	Helper bots provide accelerated upload capacity
Normal transfer	Missing helper bots, missing dump chat, or `USE_HYPER=False`	Amaterasu uses the regular Telegram download/upload path

Recommended helper count:

Server / workload	Suggested helpers
Small VPS, 1-2 vCPU	2-3 helper bots
Normal VPS, 2-4 vCPU	3-5 helper bots
Heavy Telegram leech workload	5-8 helper bots, then tune based on FloodWait logs

Optional tuning:

HYPER_THREADS = 0        # 0 = auto. Set 2, 4, 6... to cap parallel download parts.
HYPER_PIPELINE = 4       # Higher can be faster, but may increase FloodWaits.
HYPER_CHUNK = 1024 * 1024 # Telegram GetFile requests are normalized to 1 MiB.

Optional per-helper proxy config uses one Python dictionary per line. Blank lines mean "no proxy" for that helper index.

HELPER_BOT_PROXIES = """
{"scheme": "socks5", "hostname": "1.2.3.4", "port": 1080, "username": "user", "password": "pass"}

{"scheme": "http", "hostname": "5.6.7.8", "port": 8080}
"""

Troubleshooting:

Symptom	Check
Hyper never starts	Confirm `USE_HYPER=True`, `HELPER_TOKENS` is not empty, and `LEECH_DUMP_CHAT` is set
`Cannot copy to dump chat`	Main bot cannot copy the source message into `LEECH_DUMP_CHAT`; check chat ID and bot permissions
Helper bot failed at startup	Token may be wrong, bot may be banned/limited, or proxy syntax may be invalid
Many FloodWait logs	Reduce helper count, lower `HYPER_THREADS`, or lower `HYPER_PIPELINE`
Upload works but not faster	Add more helper bots, use a nearby VPS region, and ensure `LEECH_DUMP_CHAT` is a supergroup/channel where all helper bots can send

5. Google Drive

Variable	Type	Default	Description
`GDRIVE_ID`	`str`	`""`	Default Google Drive folder ID for mirror uploads
`GD_DESP`	`str`	`""`	Description text for the GDrive destination
`IS_TEAM_DRIVE`	`bool`	`False`	Set `True` if `GDRIVE_ID` is a Shared/Team Drive
`STOP_DUPLICATE`	`bool`	`False`	Check for duplicate files on GDrive before uploading
`INDEX_URL`	`str`	`""`	GDrive Index URL for generating direct links
`USE_SERVICE_ACCOUNTS`	`bool`	`False`	Use Service Account JSON files for GDrive operations

6. Rclone

Variable	Type	Default	Description
`RCLONE_PATH`	`str`	`""`	Default Rclone remote path (e.g., `remote:path/to/folder`)
`RCLONE_FLAGS`	`str`	`""`	Extra Rclone flags applied to all operations
`RCLONE_SERVE_URL`	`str`	`""`	URL for Rclone serve
`SHOW_CLOUD_LINK`	`bool`	`False`	Show cloud link after mirror upload
`RCLONE_SERVE_PORT`	`int`	`0`	Port for Rclone serve
`RCLONE_SERVE_USER`	`str`	`""`	Basic auth username for Rclone serve
`RCLONE_SERVE_PASS`	`str`	`""`	Basic auth password for Rclone serve

TeraBox

Variable	Type	Default	Description
`TERABOX_ENABLED`	`bool`	`True`	Enables native TeraBox public-share and account downloads
`TERABOX_LIMIT`	`int`	`0`	Maximum TeraBox download size in GB; `0` means unlimited

TeraBox is intentionally download-only. tb and tbx are not valid upload destinations. See Native TeraBox & Selector Update for cookie setup, selection behavior, commands, and deployment details.

7. Download Size Limits

All limits are in GB. Set 0 to disable the limit.

Variable	Description
`DIRECT_LIMIT`	Max size for direct link downloads
`DIRECT_PARALLELISM`	Concurrent files within a multi-file direct/index download (`1`-`16`, default `4`)
`MEGA_LIMIT`	Max size for Mega downloads
`TERABOX_LIMIT`	Max size for TeraBox downloads in GB (`0` = unlimited)
`TORRENT_LIMIT`	Max size for torrent downloads
`GD_DL_LIMIT`	Max size for GDrive downloads
`RC_DL_LIMIT`	Max size for Rclone downloads
`CLONE_LIMIT`	Max size for clone operations
`JD_LIMIT`	Max size for JDownloader downloads
`NZB_LIMIT`	Max size for Usenet downloads
`YTDLP_LIMIT`	Max size for yt-dlp downloads
`PLAYLIST_LIMIT`	Max number of videos in a YouTube playlist
`LEECH_LIMIT`	Max total size for leech operations
`EXTRACT_LIMIT`	Max size for extraction operations
`ARCHIVE_LIMIT`	Max size for archive/zip operations
`STORAGE_LIMIT`	Max total storage usage on server

8. Torrent / Aria2c / qBittorrent

Variable	Type	Default	Description
`DISABLE_TORRENTS`	`bool`	`False`	Completely disable torrent functionality
`DISABLE_SEED`	`bool`	`False`	Disable seeding after torrent download
`TORRENT_TIMEOUT`	`int`	`0`	Timeout for torrent downloads in seconds
`BASE_URL`	`str`	`""`	Public URL for FileToLink and web UI links, e.g. `https://stream.example.com`
`WEB_PINCODE`	`bool`	`False`	Enable pincode verification for torrent file selection
`AMATERASU_WEB_SECRET`	`str`	`""`	Secret used to sign and verify web interface tokens. Set a long random value so file-selector and web auth links keep working after restarts
`QUEUE_ALL`	`int`	`0`	Max total tasks in queue (0 = unlimited)
`QUEUE_DOWNLOAD`	`int`	`0`	Max concurrent downloads
`QUEUE_UPLOAD`	`int`	`0`	Max concurrent uploads
`UPLOAD_PARALLELISM`	`int`	`3`	Concurrent files within each Telegram leech task (`1`-`16`); also bounds MIME, ffprobe, and thumbnail work

9. JDownloader & Usenet

Variable	Type	Default	Description
`JD_EMAIL`	`str`	`""`	MyJDownloader account email
`JD_PASS`	`str`	`""`	MyJDownloader account password
`MEGA_EMAIL`	`str`	`""`	Mega.nz account email
`MEGA_PASSWORD`	`str`	`""`	Mega.nz account password
`USENET_SERVERS`	`list`	`[]`	List of Usenet server configurations for Sabnzbd

10. Media & Search

Variable	Type	Default	Description
`IMAGES`	`list`	`[]`	Photo/GIF URLs and Telegram media file IDs used by the gallery and random message media
`IMG_SEARCH`	`str`	`""`	Comma-separated wallpaper search keywords used to auto-fill `IMAGES` on startup
`IMG_PAGE`	`int`	`1`	Number of Wallpaperflare result pages to fetch per `IMG_SEARCH` keyword
`USE_IMAGES`	`bool`	`False`	Enable random images on supported bot messages
`IMDB_TEMPLATE`	`str`	`""`	Custom HTML template for IMDB results
`INSTADL_API`	`str`	`""`	Instagram downloader API endpoint
`HYDRA_IP`	`str`	`""`	NZBHydra2 IP address for Usenet search
`HYDRA_API_KEY`	`str`	`""`	NZBHydra2 API key
`SEARCH_API_LINK`	`str`	`""`	Torrent search API URL
`SEARCH_LIMIT`	`int`	`0`	Max search results to display
`SEARCH_PLUGINS`	`list`	`[]`	qBittorrent search plugin URLs

11. YouTube Tools

Variable	Type	Default	Description
`YT_DLP_OPTIONS`	`str`	`""`	Default yt-dlp options in JSON format
`YT_DESP`	`str`	`""`	Default description for YouTube uploads
`YT_TAGS`	`list`	`[]`	Default tags for YouTube uploads
`YT_CATEGORY_ID`	`int`	`0`	YouTube category ID
`YT_PRIVACY_STATUS`	`str`	`""`	YouTube upload privacy (`public`, `unlisted`, `private`)

12. Log Channels & Notifications

Variable	Type	Default	Description
`LEECH_DUMP_CHAT`	`str`	`""`	Chat ID where leeched files are dumped (e.g., `-100123456789`)
`USE_LEECH_DUMP_AS_BIN_CHANNEL`	`bool`	`False`	Use `LEECH_DUMP_CHAT` as FileToLink storage; falls back to `BIN_CHANNEL` if the dump chat is empty
`LINKS_LOG_ID`	`str`	`""`	Chat ID for logging generated links
`MIRROR_LOG_ID`	`str`	`""`	Chat ID for logging mirror uploads
`PROGRESS_BAR`	`str`	`"█:░"`	Progress bar symbols in `FILLED:EMPTY` format, e.g. `█:░` or `🟩:⬛`
`STATUS_LIMIT`	`int`	`10`	Max number of tasks shown per status page
`STATUS_UPDATE_INTERVAL`	`int`	`0`	Seconds between status message updates
`INCOMPLETE_TASK_NOTIFIER`	`bool`	`False`	Notify about incomplete tasks on restart
`INC_TASK_RESUME`	`bool`	`False`	Auto-resume incomplete tasks after restart
`CLEAN_LOG_MSG`	`bool`	`False`	Clean log messages after task completion
`DELETE_LINKS`	`bool`	`False`	Delete user's link message after processing
`MEDIA_STORE`	`bool`	`False`	Store media metadata
`COLORED_BTNS`	`bool`	`True`	Enable colored inline button styles where Telegram supports them

13. FileToLink Streaming

Variable	Type	Default	Description
`BIN_CHANNEL`	`int`	`0`	Telegram channel ID used as file storage backend
`MAX_BATCH_FILES`	`int`	`0`	Max files per batch operation
`CHANNEL`	`bool`	`False`	Enable channel mode
`MULTI_TOKEN1..50`	`str`	`""`	Optional dedicated FileToLink bot tokens for load balancing
`AUTO_PROVISION_STREAM_BOTS`	`bool`	`False`	Use `USER_SESSION_STRING` at startup to add and promote configured FileToLink workers in the effective BIN channel and `LEECH_DUMP_CHAT`; provisioning is skipped if unavailable.
`TOKEN_ENABLED`	`bool`	`False`	Reserved legacy setting; FileToLink URLs are always signed
`TOKEN_TTL_HOURS`	`int`	`0`	Reserved legacy setting; route tokens currently do not expire
`SHORTEN_ENABLED`	`bool`	`False`	Enable URL shortening for stream links
`GLOBAL_RATE_LIMIT`	`bool`	`False`	Reserved legacy setting; not currently enforced
`RATE_LIMIT_ENABLED`	`bool`	`False`	Reserved legacy setting; not currently enforced

FILETOLINK_ADAPTIVE_STREAMING enables latency-first playback chunks, adaptive ordered request windows, duplicate-chunk coalescing, file-reference refresh, and bounded worker failover. If the direct engine cannot initialize, Amaterasu falls back to WZGram's native streamer before sending response bytes. FILETOLINK_GETFILE_CONCURRENCY caps in-flight Telegram chunk requests per stream bot (default 8), while FILETOLINK_PREFETCH_CHUNKS controls the maximum ordered look-ahead per transfer (default 4). These values can be changed from /bsetting; the web stream service restarts automatically so the new values take effect immediately. Active transfers automatically receive a smaller prefetch window so simultaneous users share each worker fairly. FILETOLINK_CACHE_MAX_MB caps a single cached file (default 256) and FILETOLINK_CACHE_TOTAL_MAX_MB caps total cache usage (default 2048). Complete live responses populate the cache directly without a second Telegram download. Use /link status to inspect stream clients, tuning, storage config, and cache usage.

14. Web Server

Variable	Type	Default	Description
`PORT`	`int`	`8080`	Advanced environment-only internal listener port. It is hidden from Telegram bot settings; use Docker `-p HOST_PORT:8080` for public port mapping
`BIND_TO_LOOPBACK`	`bool`	`True`	When `True`, the web UI binds to `127.0.0.1` only — operators must put a reverse proxy (nginx, Caddy, Cloudflare Tunnel) in front. When `False`, binds `0.0.0.0` for direct LAN access without a reverse proxy. Pair with `ports: ["0.0.0.0:8080:8080"]` in docker-compose for direct access. Trade-off: `False` is more convenient but exposes the web UI to anyone who can reach the host on port 8080.
`CLOUDFLARE_TUNNEL_ENABLED`	`bool`	`False`	Start Cloudflare Tunnel from Amaterasu
`CLOUDFLARE_TUNNEL_TOKEN`	`str`	`""`	Named tunnel token. Empty uses a temporary quick tunnel
`CLOUDFLARE_TUNNEL_TARGET`	`str`	`""`	Local URL exposed by the tunnel. Empty uses `http://127.0.0.1:PORT`
`CLOUDFLARE_TUNNEL_METRICS`	`str`	`"127.0.0.1:49312"`	Local cloudflared metrics listener
`CLOUDFLARE_TUNNEL_AUTO_URL`	`bool`	`True`	Auto-fill quick tunnel URL into `BASE_URL`
`WORKERS`	`int`	`0`	Number of Uvicorn worker processes
`LOGIN_PASS`	`str`	`""`	Optional web UI login password (separate from `WEB_ACCESS_PASSWORD`). When set, all non-public web routes require a `session_token` cookie obtained via `/login`. When empty, no login is required. `WEB_ACCESS_PASSWORD` protects file download links; `LOGIN_PASS` protects the web UI admin panel.

Web UI Access

By default, the web UI binds to 127.0.0.1:8080 — only accessible from the host itself. This is the safest default: operators must put a TLS-terminating reverse proxy (nginx, Caddy, Cloudflare Tunnel) in front, which handles HTTPS and access control.

For quick deployments without a reverse proxy (e.g., testing on a local LAN, or accessing via SSH tunnel), set BIND_TO_LOOPBACK=false in your .env file or shell:

BIND_TO_LOOPBACK=false docker compose up -d

This rewrites the bind address to 0.0.0.0:8080:8080, making the web UI reachable on the host LAN. Trade-off: anyone who can reach the host on port 8080 can access the web UI. Use only on trusted networks.

For an additional layer of protection on the web UI itself (beyond the file-download password), set LOGIN_PASS to require a login cookie for all admin routes.

14b. Self-Update

Variable	Type	Default	Description
`UPSTREAM_REPO`	`str`	`https://github.com/Zan-getsu/Amaterasu`	Git repo URL for auto-update. Empty disables auto-update
`UPSTREAM_BRANCH`	`str`	`"main"`	Branch to track
`AUTO_UPDATE`	`bool`	`False`	Opt in to Git updates. A clean matching branch is fast-forwarded; dirty, ahead, detached, or diverged repositories are skipped without changing files
`UPDATE_PKGS`	`bool`	`False`	Run `uv pip install -U -r requirements.txt` on every boot. Off by default to avoid surprises — pin and update explicitly
`UPSTREAM_ALLOWLIST`	`str`	(3 default patterns)	Comma-separated regex patterns for allowed `UPSTREAM_REPO` URLs. Default allows `github.com`, `raw.githubusercontent.com`, and `git.nbmirror.qzz.io`. Add your own fork URL here to enable auto-update from a custom fork

AUTO_UPDATE=false applies to every update entry point: initial container boot, hard restart, scheduled restart, and soft reload. UPDATE_PKGS is independent and controls only Python package updates.

With AUTO_UPDATE=true, Amaterasu never runs git reset --hard, git clean, or an automatic checkout over local work. It checks git status before and after fetching, requires the current branch to equal UPSTREAM_BRANCH, and applies only a fast-forward. Git child processes use the numeric UID/GID that owns the mounted project directory, derived at runtime; no host username, path, UID, or GID is hardcoded. If an existing installation was already damaged by an older image, repair that ownership once before using the new updater—the new startup flow will not apply chown or conceal existing permission damage.

SABnzbd and qBittorrent mutable configuration, logs, and engine state are kept outside the Git checkout. Docker deployments use /data/amaterasu on the existing tunnel_data volume; non-Docker runs use the ignored .runtime directory. The files under configs/sabnzbd and configs/qbittorrent are immutable seed templates. Startup invokes setpkgs.sh through bash and never changes the tracked script's executable bit. AMATERASU_RUNTIME_DIR can override the runtime root for non-standard deployments without depending on a host username, UID, GID, or installation path.

An installation upgrading from an older release may need one manual cleanup because the old startup code already modified setpkgs.sh, configs/sabnzbd/SABnzbd.ini, configs/qbittorrent/qBittorrent/config/qBittorrent.conf, or created engine logs/state below those directories. Stop the container, inspect git diff carefully, back up any runtime data you need, restore only the known generated tracked changes, move legacy untracked runtime data outside the checkout, and run git pull --ff-only. This is a one-time migration; do not restore files containing intentional source changes. Once the runtime-state fix is installed, AUTO_UPDATE=true can update on subsequent restarts without normal startup dirtying the repository.

Docker build contexts exclude .git and deployment secrets. A container started without a Git checkout mounted at the application directory therefore skips AUTO_UPDATE=true safely; update that deployment by pulling/rebuilding the image instead. The standard Compose checkout mount remains available for config.py and private runtime files, but startup does not write its Git metadata unless an operator explicitly opts into a safe update or confirms the bot-settings upstream-push action.

Self-Update from a Custom Fork

By default, update.py only accepts UPSTREAM_REPO URLs matching one of three patterns: github.com, raw.githubusercontent.com, or git.nbmirror.qzz.io. This prevents arbitrary-repo fetch but breaks fork workflows — operators who fork Amaterasu to their own GitHub cannot auto-update.

To enable auto-update from your own fork, set AUTO_UPDATE=true and UPSTREAM_ALLOWLIST in your .env file or config.py:

# .env file
AUTO_UPDATE=true
UPSTREAM_ALLOWLIST=^https://github\.com/yourname/Amaterasu/?$

Multiple patterns are comma-separated:

UPSTREAM_ALLOWLIST=^https://github\.com/yourname/Amaterasu/?$,^https://gitlab\.com/yourname/Amaterasu/?$

Each pattern is a Python regex. Invalid patterns are skipped with a warning. If no valid patterns are parsed, the default 3-pattern allowlist is used as a fallback.

SABnzbd.ini Patcher Bypass

Variable	Type	Default	Description
`SKIP_SABNZBD_INI_CHECK`	`bool`	`False`	When `True`, the SABnzbd.ini patcher skips validation and starts SABnzbd even if known-bad credential markers (`sabpassword`, `CHANGEME`, `REPLACED_AT_BOOT_BY_AMATERASU`) cannot be replaced. Use this only if you manage SABnzbd.ini manually or migrate from a custom config. The default (`False`) refuses to start SABnzbd with default credentials — a safety net against shipping known-bad credentials

15. Miscellaneous

Variable	Type	Default	Description
`NAME_SWAP`	`str`	`""`	Default name substitution rules
`FFMPEG_CMDS`	`dict`	`{}`	Pre-defined FFmpeg command presets
`UPLOAD_PATHS`	`dict`	`{}`	Named upload path shortcuts
`DISABLE_LEECH`	`bool`	`False`	Disable all leech functionality
`DISABLE_BULK`	`bool`	`False`	Disable bulk download feature
`DISABLE_MULTI`	`bool`	`False`	Disable multi-link feature
`DISABLE_FF_MODE`	`bool`	`False`	Disable FFmpeg processing
`UPSTREAM_REPO`	`str`	`https://github.com/Zan-getsu/Amaterasu`	Repository URL used only when `AUTO_UPDATE=true`. Allowed hosts: `github.com`, `raw.githubusercontent.com`, `git.nbmirror.qzz.io`
`UPSTREAM_BRANCH`	`str`	`main`	Branch eligible for a safe fast-forward update
`AUTO_UPDATE`	`bool`	`False`	Opt in to safe, clean-tree-only Git updates on boot or bot restart
`UPDATE_PKGS`	`bool`	`False`	Auto-update pip packages on restart
`RSS_DELAY`	`int`	`0`	Seconds between RSS feed checks
`RSS_CHAT`	`str`	`""`	Chat ID for RSS notifications
`RSS_SIZE_LIMIT`	`int`	`0`	Max file size for RSS auto-downloads

🆕 Native TeraBox Download & Selector Update

Amaterasu handles TeraBox as a native download source. TeraBox upload code was removed because the service rejects the public finalization protocol as an unsupported API. Signed web file selection remains available for TeraBox and Rclone.

TeraBox Setup & Cookies

Public TeraBox shares can use the cookie-free fallback. A valid logged-in cookie is preferred when available and is required for account browsing.

Sign in to TeraBox in a browser and open your account drive.
Use Cookie-Editor to export the current site cookies in Netscape format. Save the export as a .txt file; do not convert it to JSON.
Confirm the export contains a nonempty ndus authentication cookie. A normal fresh export may omit jsToken, csrfToken, and browserid because current TeraBox pages derive them at runtime. Amaterasu bootstraps those values, follows TeraBox's per-account regional endpoint, and accepts the session only after an authenticated quota check succeeds.
Install the cookie using one of these private paths:

Scope	Install location	Stored as
Current Telegram user	`/usetting` → TeraBox cookie upload	`terabox_cookies/<user_id>.txt`
Bot owner/global fallback	`/bsetting` → Private Files	`terabox.txt`

When both files exist, Amaterasu asks which account to use. User cookies take no implicit precedence over the owner account.

If TeraBox rejects the session, sign in again and make a fresh Netscape export. An ndus cookie can be unexpired according to its file metadata while the server has already revoked it.

If the bot host cannot reach TeraBox directly, set TERABOX_PROXY to a stable HTTP(S) proxy URL, for example http://user:password@proxy.example:8080, before starting the bot. The proxy is opt-in, applies only to native TeraBox requests, and should use the same trusted region as the browser session when possible. SOCKS proxy URLs require additional connector support and are not accepted by this setting.

Caution

A TeraBox cookie grants account access. Never commit it, paste its contents into Telegram, include it in logs, or expose it from a public web directory.

TeraBox Command Recipes

Goal	Command	Cookie requirement	Result
Download a public share to Telegram	`/leech <terabox-share-link>`	Optional for supported public shares	Files are downloaded, processed, and leeched normally
Download a public share then mirror it	`/mirror <terabox-share-link>`	Optional for supported public shares	Uses the normal configured cloud destination
Download a public share then send it to a DDL hoster	`/uphoster <terabox-share-link>`	Optional for supported public shares	Native TeraBox download followed by the selected hoster
Browse an account and leech selected files	`/leech tbx`	Required	Selected account items are sent to Telegram
Browse an account and mirror selected files	`/mirror tbx`	Required	Selected account items use the normal mirror destination

TeraBox tasks use Amaterasu's normal download limits, queue handoff, status, and cancellation flow. Downloads use resumable .part files, bounded retries, atomic finalization, response-size validation, and one direct-link refresh when TeraBox expires a generated URL. A stale account cookie no longer prevents a public share from trying the cookie-free fallback.

No downloader can guarantee access to every share. Deleted files, wrong or missing share passwords, owner-restricted content, TeraBox rate limits, and regional or network blocks still return a clear failure instead of publishing an incomplete file as successful.

Supported TeraBox hostnames are detected by parsed hostname rather than unsafe substring matching. This includes the common TeraBox, 1024tera, FreeTeraBox, Nephobox, and Dubox share domains.

Secure Web Selectors

Set a valid, public HTTP(S) BASE_URL to enable the browser-based selectors. AMATERASU_WEB_SECRET should be a long, stable random value so signed selector links remain valid across restarts. WEB_PINCODE remains available for the existing torrent selector.

TeraBox selection

A public TeraBox folder uses the web selector when the command includes -s, the share contains multiple files, and BASE_URL is valid.
Public-share selection has no Telegram-button fallback: configure BASE_URL before using -s, or omit -s to process the share without web selection.
/mirror tbx and /leech tbx use the web selector when BASE_URL is valid.
Account browsing falls back to Telegram inline buttons when no valid BASE_URL is configured.
The selector supports folder navigation, select all, invert selection, selection counts, and nested items.

Rclone selection

/mirror rcl uses the web selector for interactive Rclone downloads when BASE_URL is valid.
Only the selected files are passed to Rclone through --files-from.
Personal mrcc: configurations continue to work.
Clone operations keep their existing behavior; the new selector targets Rclone downloads.
Without a valid BASE_URL, Amaterasu falls back to the existing Telegram selection flow.

Each selector uses a separate HMAC scope (terabox-select, rclone-select, or the existing torrent-select), verifies the task GID and Telegram owner, stores short-lived state outside public static files, and rejects item IDs that were not present in the displayed listing. Selector filenames are escaped before rendering to prevent HTML/script injection.

Compatibility & Reliability

This port includes the following runtime fixes in addition to TeraBox:

Immediate Processing... acknowledgement while mirror, clone, and hoster tasks prepare their download; it is removed when the task starts, fails, or opens a selector.
qBittorrent state compatibility for metadata, forced download, queued, checking, paused/stopped download and upload, seeding, and terminal states.
qBittorrent tags accept lists or comma-separated strings; time values accept numbers, timedeltas, and datetimes; status getters tolerate missing values.
qBittorrent registration has a 60-second timeout and metadata polling yields between checks instead of busy-looping.
The generated qBittorrent service password is enforced consistently; the insecure adminadmin default and stale database overrides are not accepted.
Media probing skips known non-media files such as PDF, EPUB, DOCX, RTF, JSON, text files, and fonts.
Google Drive, GoFile, BuzzHeavier, and PixelDrain completion/finally paths no longer report false failures after a successful upload.
/stats exposes the installed TeraBox SDK version, and bot/user settings describe the new TeraBox values and private cookie files.
TeraBox authentication bootstraps page-derived session fields before login, follows the server-provided regional account host without changing SDK process globals, and validates the session with a read-only quota request.

Verification

Use the following checks before deployment:

python -m compileall -q bot web terabox
python -m pytest -q tests
docker build --pull -t amaterasu:test .

The automated suite covers native TeraBox authentication, regional routing, public fallback, proxy propagation, resumable downloads, direct-link refresh, incomplete-response rejection, selector security/state checks, and the wider bot regression suite. The web selector was also checked at desktop and mobile widths for navigation, selection submission, overflow, and console errors.

The native cookie flow has been verified with read-only login, quota, and root listing requests. Automated tests use mocked TeraBox responses and never expose credentials or perform account writes.

📖 Command Reference

☁️ Mirror Commands (Download → Cloud Drive)

Command	Shortcut	Description
`/mirror`	`/m`	Download a link, torrent file, or magnet → upload to cloud drive (GDrive/Rclone/Mega)
`/qbmirror`	`/qm`	Same as mirror but forces qBittorrent engine (best for torrents)
`/jdmirror`	`/jm`	Same as mirror but forces JDownloader engine
`/nzbmirror`	`/nm`	Download a `.nzb` file via Sabnzbd → upload to cloud
`/ytdl`	`/y`	Download from YouTube or 1800+ sites via yt-dlp → upload to cloud
`/clone`	`/cl`	Copy a Google Drive / Rclone file or folder directly to your drive

📥 Leech Commands (Download → Telegram)

Command	Shortcut	Description
`/leech`	`/l`	Download a link/torrent → upload directly to Telegram
`/qbleech`	`/ql`	Leech using qBittorrent engine
`/jdleech`	`/jl`	Leech using JDownloader engine
`/nzbleech`	`/nl`	Leech a `.nzb` via Sabnzbd → upload to Telegram
`/ytdlleech`	`/yl`	Download from YouTube/yt-dlp sites → upload to Telegram

📤 Upload Hoster Commands

Command	Shortcut	Description
`/uphoster`	`/up`	Download a link, including a TeraBox share → upload to DDL servers (GoFile, BuzzHeavier, PixelDrain, DevUploads, VikingFile)

🔍 Search & Info Commands

Command	Shortcut	Description
`/list`	—	Search your Google Drive(s) for files/folders
`/search`	—	Search torrents via installed qBittorrent search plugins
`/nzbsearch`	`/ns`	Search Usenet via NZBHydra2
`/imdb`	—	Look up a movie or TV show on IMDB
`/count`	—	Count files/folders in a Google Drive link
`/mediainfo`	`/mi`	Get detailed MediaInfo for a file (reply or link)

⚙️ Task Management

Command	Shortcut	Description
`/status`	`/s`	View active tasks plus live CPU, RAM, storage, uptime, and real-time system DL/UP rates
`/cancel`	`/c`	Cancel a specific task (by GID or reply)
`/cancelall`	`/call`	Cancel all active tasks (with confirmation)
`/forcestart`	`/fs`	Force a queued task to start immediately
`/select`	`/sel`	Select specific files from a torrent/NZB to download

👤 User Commands

Command	Shortcut	Description
`/usetting`	`/us`	Open your personal settings panel (thumbnail, prefix, upload destination, etc.)
`/tokengen`	—	Open your private Google OAuth token generator and download manager
`/sessiongen`	—	Open your private Telegram session generator
`/stats`	`/st`	View server hardware stats (CPU, RAM, Disk, Network)
`/ping`	—	Check bot response latency
`/help`	`/h`	Show all available commands with descriptions
`/login`	—	Authenticate with bot password (if `LOGIN_PASS` is set)

🎬 Media & File Tools

Command	Shortcut	Description
`/link`	`/stream`, `/f2l`	Generate direct stream/download links for Telegram files
`/autorename`	`/ar`	Set up or use an auto-rename template
`/sort`	—	Toggle file sorting mode and resend collected files alphabetically
`/telegraph`	`/tg`	Upload an image or video (under 5 MB) to Telegraph and get a permanent link
`/speedtest`	`/stest`	Run a server speed test via speedtest.net

🔐 Admin / Sudo Commands

Command	Shortcut	Permission	Description
`/bsetting`	`/bs`	Sudo	Open the bot configuration dashboard
`/authorize`	`/a`	Sudo	Authorize a chat or user
`/unauthorize`	`/ua`	Sudo	Revoke authorization
`/addsudo`	`/as`	Sudo	Grant sudo privileges to a user
`/rmsudo`	`/rs`	Sudo	Revoke sudo privileges
`/users`	—	Sudo	View all registered users and their settings
`/broadcast`	`/bc`	Sudo	Send a message to all bot users
`/log`	—	Sudo	Download the bot's log file
`/shell`	—	Sudo	Execute a shell command on the server
`/exec`	—	Sudo	Execute synchronous Python code
`/aexec`	—	Sudo	Execute asynchronous Python code
`/restart`	`/r`	Sudo	Restart the bot (runs the guarded updater only when `AUTO_UPDATE=true`)
`/restartses`	`/rses`	Sudo	Restart all user/helper sessions
`/purge`	`/clear_drive`	Sudo	Scan and bulk-delete contents from a Google Drive folder
`/rss`	—	Authorized	Open the RSS feed management panel

🧹 Drive Purge Manager

The Drive Purge Manager provides Sudo users with an interactive cleanup panel for a Google Drive folder.

/purge
/clear_drive
/purge DRIVE_ID
/clear_drive DRIVE_ID

Without a Drive ID, the command uses the configured GDRIVE_ID.
A supplied Drive ID or Google Drive folder link overrides GDRIVE_ID.
The target is scanned recursively before any destructive option is shown.
Service Account authentication follows the existing GDrive behavior and falls back to token.pickle when the Service Account cannot access the target.

Mode	Behavior
Delete All	Permanently deletes every file and subfolder inside the target
Delete By Age	Deletes items whose created and modified times are older than the selected duration
Delete By Range	Deletes the first selected number of files in scan order
Delete Files Only	Deletes files while preserving the folder structure
Delete Empty Folders	Deletes folder trees that contain no files
Delete Only Folders	Moves nested files to the target root, then deletes the folders
Dry Run Preview	Shows the full Delete All plan without deleting anything

Safety and operation

Google Drive deletion is permanent; items are not moved to Trash.
Every destructive mode shows its exact file, folder, and size plan before deletion.
Delete All, configured-root cleanup, operations over 1,000 files, and operations over 100 GB require a second confirmation button.
The control panel expires after five minutes of inactivity. Custom age and amount inputs expire after 60 seconds.
Only one purge panel or running purge can target the same Drive ID at a time.
Deletions use Drive API batches of 50 with paced dispatch, per-item fallback, and quota-aware exponential backoff with jitter.
Stop Purge finishes the current batch, stops new batches, and returns a partial completion report.
Actions and results are written to the bot log with the user, target, mode, deleted totals, recovered size, execution time, and timestamp.

🎞️ Encoding & Metadata

Amaterasu features a powerful built-in FFmpeg encoding engine capable of transforming and optimizing media on the fly before uploading.

1. Encode Profiles

Instead of typing out complex FFmpeg commands every time, you can create and save Encode Profiles through your personal settings panel:

Send /usetting in the chat.
Navigate to Encode Profiles → ➕ Create Profile.
Submit a JSON configuration defining your preferred codecs and parameters.

You can set any profile as your Default. The bot will automatically use this profile whenever you start an encoding task (e.g., using the -en flag).

2. Supported Codecs

Video: libsvtav1 (AV1), libx265 (HEVC/H.265), libx264 (H.264), libvpx-vp9 (VP9), mpeg4, copy
Audio: libopus, aac, flac, libmp3lame, ac3, copy
Subtitle: copy, burn, none

The built-in default is H.264 + AAC in 8-bit 4:2:0 for broad hardware and player compatibility. Advanced AV1, HEVC, Opus, and FLAC profiles remain available; Amaterasu automatically uses Matroska when the selected codecs are not safely compatible with the source container. Every completed encode is probed and seek-decoded at multiple timestamps before the source is removed. If that validation fails, the invalid output is deleted and the source is kept.

SVT-AV1 profiles use FFmpeg's native CRF and preset controls, stay within the bot's assigned CPU set, and default to preset 6, a ten-second seek interval, and fast-decode bitstreams. Existing profiles remain compatible: legacy extra_params such as film grain, tune, and explicit keyint values are preserved, while named profile fields remain authoritative for CRF and preset.

3. Track Mapping & Metadata Injection

You can dynamically isolate specific audio/subtitle tracks and inject custom metadata (titles, release years, track names) either directly into your Encode Profile or on the fly using the -enmeta command argument.

A. In your Encode Profile (JSON)

Include a "metadata" block in your profile configuration:

{
    "name": "Multi-Audio AV1 Encode",
    "video_codec": "libsvtav1",
    "audio_codec": "libopus",
    "subtitle_mode": "copy",
    "metadata": {
        "title": "Dr. Stone S01E01",
        "v_track": "0",
        "a_track": "1",
        "s_track": "0",
        "s:v:0": "title=1080p SVT-AV1",
        "s:a:0": "title=English Dubbed",
        "s:s:0": "title=English Subtitles"
    }
}

B. On the Fly (Command Line)

Override or apply metadata instantly using the -enmeta flag. Separate key-value pairs with a pipe |:

/leech <link> -en -enmeta "title=My Movie|v_track=0|a_track=1|s:a:0=title=English Audio"

Track Selection Keys:

v_track: Select which video track to keep (e.g., 0 for the first). Use ? to keep all.
a_track: Select which audio track to keep (e.g., 1 for the second).
s_track: Select which subtitle track to keep.

Stream Specifiers:

s:v:0: Applies metadata to the first video track.
s:a:1: Applies metadata to the second audio track.
s:s:0: Applies metadata to the first subtitle track.

4. Cover Art Embedding

When you set a custom thumbnail (via /setthumb or the -t argument), the bot will automatically embed that image as the official cover art (attached_pic) directly into the final MP4/MKV container during the encoding process.

🎭 Auto-Rename Engine

Amaterasu includes a powerful, regex-driven Auto-Rename Engine inspired by dedicated renaming bots. It can intelligently extract information from messy filenames and restructure them into clean, standardized formats.

1. Setting Up Your Template

Instead of manually typing a new name for every file, you define a Template.

Send /usetting in the bot's private chat.
Navigate to Misc Settings → Auto-Rename.
Enter your template using dynamic placeholders.

Supported Placeholders:

{title} - The extracted base name of the media, stripped of tags and quality info.
{season} - The extracted season number (e.g., 01).
{episode} - The extracted episode number (e.g., 04).
{quality} - The extracted resolution/quality (e.g., 1080p, 4k, WEBRip).

Example Template: [MyGroup] {title} - S{season}E{episode} [{quality}] If the bot receives messy.show.s1.e4.1080p.mkv, it will become [MyGroup] Messy Show - S01E04 [1080p].mkv.

2. How to Use Auto-Rename

There are two primary ways the Auto-Rename Engine works:

Mode 1: Live Telegram Renaming

Send /autorename in the bot's private chat to toggle Auto-Rename Mode ON.
Simply forward or upload any media/document to the bot.
The bot will instantly download it, apply your template to the filename, and upload it back to you.

Mode 2: Download Tasks

When you start a mirror/leech task (e.g., downloading a torrent or a yt-dlp link), the bot will automatically apply your Auto-Rename template to all files inside the task before they are uploaded to your cloud drive or Telegram.

🗂️ File Sorting Mode

File Sorting Mode lets you send a batch of Telegram files in any order, then have Amaterasu return them alphabetically by file name. It is designed for fast cleanup of messy uploads, episode packs, document batches, and renamed file sets.

How to Use

Send /sort in the chat where you want to collect files.
Send or forward the files you want sorted.
Send /sort again to turn sorting off and deliver the files back in sorted order.

Example workflow:

/sort
03 - Ending.mkv
01 - Opening.mkv
02 - Episode.mkv
/sort

The bot will resend:

01 - Opening.mkv
02 - Episode.mkv
03 - Ending.mkv

What Gets Stored

While sort mode is active, Amaterasu only caches Telegram metadata:

Cached Data	Purpose
`file_id`	Resend the same Telegram file without downloading it
File name	Sort files alphabetically
Media type	Resend as document, video, audio, photo, or other supported media
Message ID	Keep a stable order when file names match

Important

File Sorting Mode does not download files to the server. It uses Telegram file_ids to resend cached files, so delivery is fast and does not consume hosting bandwidth.

Supported Media

Sort mode supports common Telegram media messages, including documents, videos, audio files, photos, voice notes, animations, video notes, and stickers. Files without a Telegram file name are assigned a safe fallback name for sorting.

Notes

Sending /sort a second time always ends the current sort session.
If no files were collected, the bot simply disables sort mode.
Files are sorted case-insensitively by file name.
If your bot uses CMD_SUFFIX, use the suffixed command, such as /sort1.

🎨 Encoding Profile Creator (Web UI)

Amaterasu ships with a built-in visual web application for creating, editing, and managing Encode Profiles — without writing a single line of JSON by hand.

Open User Settings in Telegram, choose Encode Profiles, then select Open Web Creator. The bot generates the required signed URL automatically.

Opening /app/encode-profiles directly without the signed user_id and token parameters intentionally uses browser-local offline storage and does not sync to MongoDB.

Why Use the Web UI?

Encoding profiles are powerful but involve complex FFmpeg concepts — stream specifiers (s:a:0), disposition flags, CRF values, codec parameters, and metadata injection. The Web UI completely abstracts all of this into user-friendly dropdowns, sliders, and visual selectors.

Traditional (Raw JSON)	Web UI Equivalent
`"s:a:0": "title=English"`	Select Audio → Track 1 → Title → Type `English`
`"a_track": "0,1"`	Select Audio Tracks to Keep → Tracks 1 & 2
`"crf": 24`	Drag the CRF slider to 24
Typing full JSON and pasting into Telegram	Click Save Profile

🏗️ Building a Profile (Step-by-Step)

Step 1: Open the Profile Builder

Navigate to the web UI URL and click "➕ Create New Profile", or select an existing profile to edit. You can also start from a Quick Preset (pre-configured templates for common workflows like AV1 anime encoding or H.264 fast encoding).

Step 2: Configure Video Settings

The Video Settings section is open by default. Here you can configure:

Setting	Description	UI Element
Video Codec	The encoder to use (`libsvtav1`, `libx265`, `libx264`, or `copy`)	Dropdown
CRF (Quality)	Quality level — lower = better quality, larger file. `28-34` is a practical AV1 range.	Slider with live label
Preset / Speed	Encoding speed vs compression tradeoff. Slower = smaller files.	Dropdown
Pixel Format	Bit depth. `yuv420p10le` recommended for 10-bit AV1/HEVC.	Dropdown
Format Profile & Level	Codec compliance level (e.g., Profile `0`, Level `5.1`).	Dropdowns
Frame Timing	Preserve VFR timing, force CFR, pass timestamps through, or let FFmpeg decide.	Dropdown
AV1 Seek Interval	Target seconds between AV1 keyframes; `10` is the balanced default.	Dropdown
AV1 Fast Decode	Reduces decoder complexity for smoother AV1 playback.	Toggle
Color Primaries / TRC / Colorspace	HDR / SDR color metadata (`bt709`, `bt2020`, etc.).	Dropdowns
Extra Parameters	Advanced SVT-AV1/x265 params in colon-separated format.	Text field

Note

Hover over the [?] icon next to settings like CRF, Preset, and Pixel Format for instant explanations of what they do.

Below the video codec settings, you'll find the Video Track Selection & Tags sub-section:

Video Tracks to Keep: A dropdown offering Keep All Tracks, Track 1 Only, Tracks 1 & 2, or a Custom Mapping option for advanced users.
Video Metadata Tags: Visually add tags (Title, Language, Handler, or Custom) to specific video tracks. No need to type s:v:0 — just select Track 1 from a dropdown.
Video Disposition Flags: Set flags like default, forced, or 0 (remove all) per track.

Step 3: Configure Audio Settings

Expand the Audio Settings section to configure:

Setting	Description
Audio Codec	`libopus`, `aac`, `flac`, or `copy`
Bitrate	Output audio bitrate (e.g., `128k`, `192k`, `320k`)
Channels	Channel layout (Stereo, 5.1, 7.1, or keep original)
VBR Toggle	Variable bitrate optimization for Opus profiles

Just like Video, the Audio section includes its own Track Selection, Metadata Tags, and Disposition Flags sub-sections. For example, to label two audio tracks:

Click "Add Tag" → Select Track 1 → Title → Type English.
Click "Add Tag" again → Select Track 2 → Title → Type Japanese.
To set the language metadata, add another tag → Select Track 1 → Language → Pick English (eng) from the dropdown.

Important

You can add multiple tags to the same track (e.g., both a Title and a Language for Track 1). The UI handles duplicate-key deconfliction automatically.

Step 4: Configure Subtitle Settings

Expand the Subtitle Settings section:

Setting	Description
Subtitle Mode	`copy`, `burn` (hardsubs), or `none`
Subtitle Tracks to Keep	Same track selector as Video/Audio
Subtitle Metadata Tags	Add Title/Language tags to subtitle tracks
Subtitle Disposition Flags	Mark subtitle tracks as `default`, `forced`, etc.

Step 5: Global Metadata

The Global Metadata section handles file-level settings:

Setting	Description
Rename File To	Rename pattern for the output file (supports dynamic variables)
Global Title	The internal metadata title embedded in the container
Cover Image URL	A direct image URL or Telegram link to embed as cover art

Dynamic Variable Chips

Below the Rename File To and Global Title fields, you'll see clickable chips for quick variable insertion:

Chip	Inserts	Resolves To (Example)
`{title}`	Parsed show/movie title	`Dr STONE`
`{episode}`	Episode identifier	`S04E33`
`{quality}`	Resolution quality tag	`1080p`
`{resolution}`	Exact resolution	`1920x1080`
`{basename}`	Original filename without extension	`Dr.STONE.S04E33.1080p.WEB-DL`
`{filename}`	Full original filename	`Dr.STONE.S04E33.1080p.WEB-DL.mkv`
`{year}`	Detected year from filename	`2024`
`{audiolang}`	Primary audio language	`Japanese`
`{sublang}`	Primary subtitle language	`English`

Click any chip to instantly insert it into the text field. Example rename pattern:

[Zangetsu] {title} - {episode}.mkv

This would produce: [Zangetsu] Dr STONE - S04E33.mkv

🔍 Live Preview

At the bottom of the Profile Builder, a Live Preview panel shows the output of your settings in real-time. You can toggle between two views:

View	Description
JSON Layout	The raw JSON that will be saved as your profile. This is the exact format the bot's backend consumes.
FFmpeg Command	A generated mock `ffmpeg` CLI command showing how your settings translate to actual FFmpeg arguments. Great for advanced users to verify.

The preview updates instantly as you change any setting.

📥 Importing & Exporting Profiles

Action	How
Export	Click the Copy button (📋) in the preview panel. The JSON is copied to your clipboard.
Import	Click the Import button (⬇️) in the top bar. Paste any existing profile JSON into the prompt. The UI will auto-populate all fields.
Save to Bot	Click Save Profile. The profile is stored in your MongoDB database and immediately available in Telegram via `/usetting → Encode Profiles`.

📋 Example: Complete Anime Encoding Profile

Here's what a typical anime encoding profile looks like when built through the Web UI:

{
    "name": "My Custom Anime Preset",
    "video_codec": "libsvtav1",
    "audio_codec": "copy",
    "subtitle_mode": "copy",
    "metadata": {
        "title": "[MyGroup] {title} - {episode}",
        "v_track": "0",
        "a_track": "1,0",
        "s_track": "1,2",
        "s:v:0": "title=Encoded by MyGroup",
        "s:a:0": "title=English",
        "s:a:1": "title=Japanese",
        "s:s:1": "title=English",
        "s:s:2": "title=English (Signs/Songs)"
    },
    "video_params": {
        "crf": 30,
        "preset": 6,
        "pix_fmt": "yuv420p10le",
        "keyint_seconds": 10,
        "fast_decode": true,
        "fps_mode": "vfr",
        "extra_params": "tune=1:film-grain=4",
        "profile": "0",
        "level": "5.1",
        "color_primaries": "bt709",
        "color_trc": "bt709",
        "colorspace": "bt709"
    },
    "audio_params": {
        "bitrate": "128k",
        "vbr": true
    },
    "rename": "{title} - {episode} [{resolution}].mkv",
    "cover_image": "https://example.com/poster.jpg",
    "disposition": {
        "a:0": "default",
        "s:1": "default"
    }
}

The above profile was built entirely through visual dropdowns and selectors — zero FFmpeg knowledge required.

🔐 Google Token Generator (Web UI)

Send /tokengen as an authorized user. The bot replies with a private, signed link that expires after 15 minutes; run the command again whenever you need a fresh link. The page is dedicated to that Telegram user and provides:

Upload credentials.json for a Google OAuth Web application client.
Enter manually using the same OAuth Client ID and Client Secret.
A read-only callback URL to add under Google Cloud's Authorized redirect URIs.
Legacy-compatible token.pickle and token.json downloads.
Encrypted, per-user MongoDB storage so the generated files remain available through future /tokengen links.
Use in Amaterasu, which explicitly copies the saved generated token into that user's existing TOKEN_PICKLE setting. Generation alone never replaces the user's active Drive token.

OAuth client input is encrypted only for the pending authorization attempt, expires after 15 minutes, and is consumed once. The generated credential is encrypted at the application layer before MongoDB storage. Keep AMATERASU_WEB_SECRET stable: changing it intentionally makes previously saved encrypted tokens unreadable.

The callback URL is always derived from BASE_URL, so configure a public https:// URL before using /tokengen. DATABASE_URL is also required.

token.pickle and token.json contain sensitive Google credentials. Never share the private bot link or either downloaded file.

Google Drive API and OAuth Setup

Use this flow when you want Amaterasu to upload to your own Google Drive account. The short version: Google Cloud creates credentials.json; Amaterasu turns it into your private token.pickle.

Open Google Cloud Console.
Enable 2-Step Verification on the Google account you will authorize.
If you are on a phone or tablet, enable desktop site or desktop mode in the browser.
Create a new Google Cloud project, or select the project you want to use.
Open the navigation menu, then go to APIs & Services -> Library.
Click Enable APIs and Services.
Search for Google Drive API, open it, and click Enable.
Open APIs & Services -> OAuth consent screen.
Click Get Started.
Enter an app name.
Under Audience, select External.
Enter your Gmail address anywhere Google asks for a contact email.
Save the OAuth consent screen configuration.
Open APIs & Services -> OAuth consent screen -> Audience.
Under Test users, click Add users.
Add the same Gmail account you plan to use for authorization.
Open APIs & Services -> Credentials.
Click Create credentials, then select OAuth client ID.
For Application type, select Web application.
In Telegram, send /tokengen and open the private bot link.
Copy the Authorized redirect URI shown on the token generator page.
Return to Google Cloud and paste that URI into Authorized redirect URIs.
Click Create.
Download the OAuth client JSON file.
Rename the downloaded file exactly to credentials.json.
Return to the bot link.
In Authorize your account, upload credentials.json.
In Google account hint, enter the same Gmail address you added as a test user.
Click Continue with Google.
Sign in with the same Google account.
If Google shows an unverified-app warning, continue only after confirming the app and OAuth credentials belong to you.
Review the requested permissions and allow access.
After authorization completes, download token.pickle or click Use in Amaterasu to make the generated token the active Drive token for that Telegram user.

Keep credentials.json and token.pickle private. Do not upload them to a public repository, paste them in chat, or share them with anyone.

Telegram Session Generator (Web UI)

Send /sessiongen as an authorized user. The bot returns a private, signed link bound to your Telegram user ID. The link expires after 15 minutes.

The page collects your Telegram API ID and API hash, phone number, login code, and optional two-step verification password through a guided flow. These values stay only in the short-lived server login attempt and are never written to MongoDB. When sign-in succeeds, Amaterasu:

sends the new WZGram-compatible session string to that account's Saved Messages;
encrypts the session string with AMATERASU_WEB_SECRET;
makes it the user's current session and appends it to their encrypted history;
shows safe account metadata and decrypts a selected session only when its Copy session button is pressed.

Each user enters the API values for their own application from my.telegram.org/apps. Generating a new session automatically updates that user's active database record; no manual replacement action is required. Earlier generated sessions remain in that user's encrypted history and can be copied while using a valid private link. BASE_URL and DATABASE_URL are required.

Keep the Saved Messages copy private. Anyone with the session string can access the Telegram account until the session is revoked.

🧰 Advanced Usage & Arguments

Every mirror/leech command supports powerful inline arguments. Combine them freely:

/mirror https://example.com/file.zip -n "My File" -e -up gdl

Argument Quick Reference

Argument	Purpose	Example
`-n [name]`	Rename the downloaded file	`/mirror link -n MyMovie.mkv`
`-e [password]`	Extract archive (optional password)	`/leech link -e secretpass`
`-z [password]`	Compress into ZIP (optional password)	`/mirror link -z mypassword`
`-up [dest]`	Override upload destination	`/mirror link -up gdl` or `-up rc` or `-up @channel`
`-s`	Show quality/file selection, including supported multi-file TeraBox shares	`/ytdl link -s` or `/leech terabox-link -s`
`-i [count]`	Multi-link: process N consecutive messages. Leech commands send one combined file-list summary after the whole batch finishes.	`/leech -i 5`, `/qbleech -i 5`, `/jdleech -i 5`
`-b`	Bulk: process links from a text file/message	`/leech -b`
`-m [folder]`	Move all downloads into a single folder	`/mirror -i 3 -m MyFolder`
`--merge`	Merge an ordered playlist, selected folder, torrent series, bulk, or `-i` collection into one MKV; add `-en` to encode the merged timeline once	`/ytdl playlist --merge`, `/qbleech magnet -s --merge`, `/leech -i 3 --merge -n Combined.mkv`
`-j`	Join split files before processing	`/mirror link -j`
`-d [ratio:time]`	Seed torrent (ratio and/or time in minutes)	`/qbmirror link -d 1.0:60`
`-t [url]`	Custom thumbnail for this task	`/leech link -t https://img.url/thumb.jpg`
`-sp [size]`	Custom split size	`/leech link -sp 500mb`
`-sv [dur:part]`	Generate sample video	`/leech link -sv 60:4`
`-ss [count]`	Take screenshots	`/leech link -ss 10`
`-ca [format]`	Convert audio to format	`/leech link -ca mp3`
`-cv [format]`	Convert video to format	`/leech link -cv mp4`
`-meta [data]`	Inject metadata (pipe-separated)	`/mirror link -meta title=My Movie\|year=2024`
`-ff [preset]`	Apply FFmpeg preset	`/leech link -ff subtitle`
`-ns [rules]`	Name substitution rules	`/mirror link -ns old/new/s`
`-rcf [flags]`	Rclone flags override	`/mirror link -rcf --buffer-size:8M`
`-f`	Force start (bypass queue)	`/mirror link -f`
`-fd`	Force download only	`/mirror link -fd`
`-fu`	Force upload only	`/mirror link -fu`
`-doc`	Force upload as document	`/leech link -doc`
`-med`	Force upload as media	`/leech link -med`
`-bt`	Leech via bot session	`/leech link -bt`
`-ut`	Leech via user session	`/leech link -ut`
`-hl`	Hybrid leech (auto bot/user)	`/leech link -hl`
`-tl [WxH]`	Thumbnail layout	`/leech link -tl 3x3`
`-au [user]`	Direct link auth username	`/mirror link -au admin`
`-ap [pass]`	Direct link auth password	`/mirror link -ap secret`
`-h [headers]`	Custom HTTP headers	`/mirror link -h Referer: https://site.com`

Merge Videos into One File

Add --merge to a supported download command when you want Amaterasu to download several videos and upload them as one ordered MKV file.

It works with mirror, leech, qBittorrent, JDownloader, NZB, yt-dlp, and upload hoster tasks. The input can be a playlist, a torrent or downloaded folder, a bulk list, or a multi-link -i batch.

Quick start

Merge a YouTube playlist and upload the result to your cloud destination:

/ytdl PLAYLIST_URL --merge

Merge a torrent series and upload the result to Telegram:

/qbleech MAGNET_LINK -s --merge

Merge the next three links or Telegram files into one video:

/leech -i 3 --merge -n "My Collection.mkv"

The -n name applies to the final combined video, not to each downloaded part. If you omit it, Amaterasu uses the playlist or folder name followed by [Merged].mkv. A multi-link task without a useful folder name becomes Combined [Merged].mkv.

Choose the merge mode

Mode	Command	What happens
Fast, lossless merge	`--merge`	Copies the existing video, audio, subtitle, and attachment streams without re-encoding. This is the fastest mode and causes no additional quality loss.
Merge, then encode	`--merge -en PRESET`	Creates one timeline first, then encodes that complete timeline once with the selected encoding preset. Encoding is restricted to SUDO users.

Examples:

/ytdlleech PLAYLIST_URL --merge
/ytdlleech PLAYLIST_URL --merge -en default
/mirror FOLDER_LINK --merge -en my_av1_preset -n "Season 01.mkv"

Using -en does not encode every episode separately. Amaterasu merges the ordered timeline first and runs one encoding job on the result. If you use -en without a preset name, the normal encoding preset menu is shown.

Important

Stream copy requires compatible video and audio layouts. With -en, the continuous encoder can normalize supported video codec and resolution differences while retaining the original selectable subtitle tracks. Unsupported audio layout, color/HDR, or profile differences stop the merge with an explicit error instead of silently dropping a track.

Arrange the order while downloading

Amaterasu sends an Arrange Merge Order web button after the batch sources have been collected. The planner updates as filenames become available, while the downloads continue in the background.

Inside the planner you can:

Drag and drop files into any order, including on a touch screen.
Restore the original input or playlist order.
Sort naturally by filename, so Episode 2 comes before Episode 10.
Sort by common season and episode patterns such as S01E03, 1x03, or Episode 3.
Reverse the complete order.
Use the accessible up and down controls instead of dragging.

Changes save automatically. The planner never creates a post-download confirmation step: if you close it or never open it, Amaterasu merges and uploads automatically using the latest saved order. Once merging begins, the timeline is locked so a late browser edit cannot change an active FFmpeg job.

Bulk and -i tasks receive the planner automatically as soon as all their sources are registered. Playlist and torrent tasks also receive the button, but their existing playlist or torrent order remains the default unless you change it.

The planner requires a valid BASE_URL. When the web interface is unavailable, the task remains fully automatic and uses playlist/input order or natural filename order; it never waits for web confirmation.

More recipes

# Mirror a selected torrent series to cloud storage
/qbmirror MAGNET_LINK -s --merge -n "Complete Series.mkv"

# Leech files downloaded by JDownloader as one video
/jdleech DOWNLOAD_URL --merge

# Mirror videos from an NZB collection as one file
/nzbmirror NZB_LINK --merge

# Merge links supplied through bulk mode
/leech -b --merge -n "Course.mkv"

# Merge five consecutive Telegram files or links
/leech -i 5 --merge

# Download, merge, encode once, and upload to a DDL host
/uphoster COLLECTION_URL --merge -en default

For -i, either reply to the first source, or send all sources consecutively and run the command immediately after the last one. You can correct their final order in the web planner while they download.

Safety and file handling

Every requested item must download successfully. If one item fails, the entire merge stops; Amaterasu does not silently upload an incomplete video.
Amaterasu checks available disk space before merging and keeps the downloaded parts until the final file passes media validation.
The final duration and track layout are checked, and bounded video/audio playback samples are decoded near the start, middle, and end.
Each source becomes a chapter in the MKV, making episodes or playlist items easier to navigate.
Compatible embedded subtitles and font attachments are preserved with corrected timeline offsets.
SRT tracks with matching languages and roles continue across episodes in one selectable track, including gaps where an episode has no subtitles. ASS tracks with matching script settings are also joined; each episode keeps its styles, colors, fonts, positioning, and named style resets.
Mixed subtitle formats, bitmap subtitles, and incompatible ASS script settings remain separate selectable tracks. The planner and upload message explain when some tracks cover individual parts. Subtitles are never burned in or silently converted to another format.
Recognized external subtitle sidecars such as .srt, .ass, or .vtt are associated with their video and merged with the same chapter offset. Missing, ambiguous, or incomplete sidecar pairs stop the task with a clear error.
Cover art embedded in source videos is omitted from the merged MKV. Use -t if you want to set the upload thumbnail for this task.
Hard cuts are used between videos; transitions are not added.
A merged leech may still be split during upload when it exceeds Telegram's file-size limit.

--merge cannot be combined with torrent seeding (-d) or cloud-to-cloud transfer (--c2c). It is also not a clone operation: use a download command such as /mirror, /ytdl, or /qbmirror so Amaterasu has local media files to combine.

When a merge is rejected

The most common cause is that one source was created with different media settings. For the best result, use files from the same series, release, camera, or export profile. If Amaterasu reports a mismatch, make the named property consistent first—for example resolution, codec, frame rate, audio channel layout, or subtitle streams—and retry the command.

Do not remove --merge and manually concatenate incompatible files with stream copy. The compatibility check exists to prevent timestamp problems, missing tracks, and files that fail partway through playback.

Telegram Link Downloads

The bot can download files from Telegram links directly:

/mirror https://t.me/channel_name/123          # Public channel
/mirror tg://openmessage?user_id=123&message_id=456   # Private message
/mirror https://t.me/c/123456/789              # Private channel (needs USER_SESSION_STRING)
/mirror https://t.me/channel_name/100-150      # Range download (messages 100 to 150)

Rclone Paths

Use Rclone paths exactly like links:

/mirror remote:path/to/file.iso               # Download from Rclone remote
/mirror rcl                                    # Interactive remote/path selection (web UI when BASE_URL is valid)
/mirror mrcc:myremote:path                     # Use your personal Rclone config (from /usetting)

Upload Destination Shortcuts

Prefix	Meaning
`gdl`	Upload using GDrive (interactive folder picker)
`gd`	Upload to default `GDRIVE_ID`
`rc`	Upload to default `RCLONE_PATH`
`rcl`	Upload using Rclone (interactive remote picker)
`tp:id`	Upload to GDrive ID using token.pickle
`sa:id`	Upload to GDrive ID using Service Accounts
`mtp:id`	Upload using your personal token.pickle (from /usetting)
`mrcc:path`	Upload using your personal Rclone config (from /usetting)
`b:@channel`	Leech to channel via bot session
`u:@channel`	Leech to channel via user session
`h:@channel`	Hybrid leech to channel
`pm`	Leech to your private messages

🌐 FileToLink Streaming Server

Amaterasu includes a built-in FastAPI web server that converts any Telegram file into a direct HTTP stream link.

How It Works

Reply to any file in Telegram with /link (or /stream or /f2l).
The bot generates a direct download URL and a streaming URL.
These links are seekable (HTTP 206 Range Requests), meaning you can play videos directly in VLC, MX Player, or any browser without downloading the full file.

For multiple consecutive files, reply to the first file and use /link -i 10 to generate links for 10 files in one command.

Use /link status to check the active BASE_URL, stream bot pool, current stream loads, and FileToLink cache usage.

The web server serves an existing cached file immediately when available. For uncached full-file opens, the active transfer stays live-first and cache warming starts only after a successful full transfer; Range playback is kept live-first to avoid competing with initial seek/buffer requests.

Multi-Token Load Balancing

By default, tokens already configured in HELPER_TOKENS are reused as FileToLink workers, so they do not need to be entered again. Every helper must be able to read the effective BIN channel. Set USE_HELPER_BOTS_FOR_FILETOLINK=False to keep helpers dedicated to HyperDL/HyperUP.

For a separate FileToLink pool, configure MULTI_TOKEN1 through MULTI_TOKEN50. Tokens present in both settings are deduplicated. The server distributes file requests across the resulting pool to avoid Telegram FloodWait limits and temporarily cools down a stream bot after repeated failures so another available token can take over.

Set USE_LEECH_DUMP_AS_BIN_CHANNEL=True to use LEECH_DUMP_CHAT for FileToLink storage as well. The saved BIN_CHANNEL value remains unchanged and is used again if the option is disabled.

Access Control

Feature	Variable	Description
Web Token Signing	`AMATERASU_WEB_SECRET`	Signs web interface tokens for file selection and web auth. If empty, Amaterasu falls back to `LOGIN_PASS`, then `BOT_TOKEN`
Token Authentication	Always enabled	Generated stream URLs always contain a signed route token
Token Expiry	`TOKEN_TTL_HOURS`	Reserved for compatibility; route tokens currently do not expire
URL Shortening	`SHORTEN_ENABLED`	Shorten generated links via a URL shortener
Global Rate Limit	`GLOBAL_RATE_LIMIT`	Reserved for compatibility; not currently enforced
Session Rate Limit	`RATE_LIMIT_ENABLED`	Reserved for compatibility; not currently enforced

📡 RSS Automation

The built-in RSS module monitors feeds and auto-downloads new entries matching your filters.

Setup

Send /rss to open the RSS management panel.
Add feeds with the format:

Title https://rss-feed-url.com -c /mirror -inf 1080|mkv -exf cam|ts

Filter Syntax

-inf (Include Filter): Only download titles matching these words.
-exf (Exclude Filter): Skip titles containing these words.
| means AND between groups.
or means OR within a group.
-stv true for case-sensitive matching.

Example

Anime https://nyaa.si/?page=rss -c /qbleech -inf 1080p|mkv or mp4 -exf batch|DVD

This auto-leeches new anime releases in 1080p (mkv or mp4), excluding batch packs and DVDs.

🔑 User Roles & Permissions

Role	How to Assign	Capabilities
Owner	Set `OWNER_ID` in config	Full access: all commands, shell, exec, bot settings, user management
Sudo	`/addsudo [user_id]` or set `SUDO_USERS` in config	Admin commands: bot settings, authorize, restart, broadcast, logs
Authorized	`/authorize [chat_id]` or set `AUTHORIZED_CHATS` in config	All download, leech, search, and user commands
Unauthorized	Default	Only `/start` and `/login` (if password is set)

❓ FAQ & Troubleshooting

The bot starts but doesn't respond to commands

Verify BOT_TOKEN is correct.
Check that your chat is authorized (add your chat ID to AUTHORIZED_CHATS).
Ensure CMD_SUFFIX matches what you're typing (e.g., if CMD_SUFFIX = "1", use /mirror1).
Review logs: sudo docker-compose logs -f

Google Drive upload fails with "Permission Denied"

Make sure token.pickle is valid and not expired.
If using Service Accounts, verify the SA email has Editor access to your Drive folder.
Set IS_TEAM_DRIVE = True if your GDRIVE_ID is a Shared Drive.
Drive purge requires delete permission for every selected item. Google requires organizer permission on the parent folder for Shared Drive deletion (normally granted through Manager access).
Use Dry Run Preview first when validating a new Drive or Service Account.

Files larger than 2 GB fail to upload to Telegram

You need USER_SESSION_STRING from a Telegram Premium account.

"Unclosed client session" errors in logs

These are cosmetic warnings from aiohttp when the bot shuts down abruptly (e.g., due to a crash or container restart). They do not affect functionality. Fix the root cause of the crash (check for SyntaxError or ImportError above the warning).

Torrent downloads stuck at 0%

Ensure your server's firewall allows incoming connections on the torrent port.
Try switching between Aria2c (/mirror) and qBittorrent (/qbmirror).
Set TORRENT_TIMEOUT to auto-cancel stalled downloads.

JDownloader not connecting

Verify JD_EMAIL and JD_PASS match your MyJDownloader account.
The JDownloader headless instance takes ~30 seconds to boot inside Docker. Check logs for "JDownloader connected" message.

TeraBox account browsing says a cookie is required

Export cookies while signed in to TeraBox using Netscape cookies.txt format.
Confirm the file contains the ndus cookie.
Upload it through /usetting, or install the owner fallback as terabox.txt through /bsetting → Private Files.
Amaterasu automatically derives the page tokens and follows regional TeraBox account hosts; you do not need to copy those values manually.
Re-export the cookie if TeraBox reports that the session was rejected. Never post cookie contents in chat or logs.

The TeraBox or Rclone web selector does not open

Set BASE_URL to a reachable public http:// or https:// address for Amaterasu's web server.
Keep AMATERASU_WEB_SECRET stable across restarts.
For public TeraBox folders, include -s; account browsing can fall back to Telegram buttons when BASE_URL is unavailable.
Verify the reverse proxy forwards requests to the configured PORT.

FileToLink stream URLs not working

Set BASE_URL to your public URL, for example https://stream.example.com.
Set PORT to the local web server port Amaterasu should bind.

MongoDB DNS timeout on Docker or Podman startup

ConfigurationError: The resolution lifetime expired means a DNS lookup timed out. A mongodb+srv:// connection needs SRV and TXT lookups before it can contact MongoDB. This does not prove the saved config is missing or the MongoDB password is wrong.

Check the SRV lookup on the VPS, replacing YOUR_CLUSTER.mongodb.net with the hostname from your MongoDB connection string (without credentials):

nslookup -type=SRV _mongodb._tcp.YOUR_CLUSTER.mongodb.net

Both Compose files default to 1.1.1.1 and 8.8.8.8 for container DNS. If these are blocked by your VPS provider, set AMATERASU_DNS_PRIMARY and AMATERASU_DNS_SECONDARY in .env to provider/private resolver IPs that are reachable from the container. Recreate the bot to apply DNS changes:

docker compose up -d --force-recreate amaterasu
docker compose logs --tail=100 amaterasu

For Podman, replace docker compose with podman compose; keep sudo if using rootful containers. For a source build, add -f docker-compose.dev.yml after the Compose command. If the container lookup still fails while the host succeeds, compare their /etc/resolv.conf files and check bridge routing, NAT, and firewall access to the resolver on UDP/TCP port 53. A resolver bound only to the host's loopback address is not directly reachable from a bridge container. An inherited Tailscale resolver such as 100.100.100.100 can time out even while public resolvers work. Test each resolver from inside the container before selecting an override.

Verify SRV resolution inside the recreated container:

docker compose exec amaterasu python -c "import dns.resolver; print(dns.resolver.resolve('_mongodb._tcp.YOUR_CLUSTER.mongodb.net', 'SRV'))"

When MongoDB is unreachable at connection time, Amaterasu keeps local credential files and starts using local config. Database-backed settings, /tokengen, and /sessiongen remain unavailable for that boot. After fixing DNS, restart the bot to reload MongoDB settings. If DNS works but connection still fails, check MongoDB reachability and the Atlas IP access list.

How to generate a WZGram String Session?

Send /sessiongen, open the private link, and complete Telegram sign-in. The encrypted session replaces your previous database record and is sent to your Telegram Saved Messages.

🙏 Acknowledgments & Credits

Amaterasu stands on the shoulders of giants. We want to express our deepest gratitude to the following legendary projects that paved the way and served as the foundational inspiration for this bot:

Important

🌟 WZML-X
The undisputed core architecture and pioneering codebase that heavily influenced Amaterasu's powerful mirroring and leeching ecosystem.

Important

🌟 Auto-Rename-Bot
An incredible source of inspiration for our advanced auto-renaming and file manipulation algorithms.

Please check out their repositories and drop them a star!

🌟 Star History

If Amaterasu powers your workflow, please consider giving it a ⭐!

[ ☀️ Awaken the Sun. Deploy Amaterasu Today. ☀️ ]

Built with ❤️ by its-niloy

Name		Name	Last commit message	Last commit date
.github		.github
bot		bot
configs		configs
gen_scripts		gen_scripts
myjd		myjd
plugins		plugins
sabnzbdapi		sabnzbdapi
scripts		scripts
terabox		terabox
tests		tests
web		web
.dockerignore		.dockerignore
.gitignore		.gitignore
Dockerfile		Dockerfile
Dockerfile.base		Dockerfile.base
LICENSE		LICENSE
README.md		README.md
build.sh		build.sh
captain-definition		captain-definition
config_sample.py		config_sample.py
cron_boot.py		cron_boot.py
docker-compose.dev.yml		docker-compose.dev.yml
docker-compose.yml		docker-compose.yml
git_runtime.py		git_runtime.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setpkgs.sh		setpkgs.sh
start.sh		start.sh
tunnel.Dockerfile		tunnel.Dockerfile
tunnel.sh		tunnel.sh
update.py		update.py

Latest commit

History

Folders and files

Repository files navigation

☀️ A M A T E R A S U ☀️

📑 Table of Contents

🔮 Overview

💎 Features

🌐 FileToLink Gateway

🎭 Auto-Rename Engine

🌩️ Multi-Engine Downloads

🛡️ Enterprise Resilience

Full Feature List

🧬 Architecture

Technology Stack

⚙️ Prerequisites

🚀 Deployment

Step 1: Prepare Your Server

Step 2: Clone & Configure

Step 3: Optional Files Setup

Step 4: Build & Launch

Method A: Docker Compose ⭐ (Recommended)

Method B: Docker (Manual)

Method C: Podman

Method D: Cloud Platforms (Heroku / Railway / Render / CapRover)

🔄 What Happens on Boot?

🌐 Reverse Proxy Setup (Optional)

Cloudflare Tunnel Setup

🛠️ Maintenance & Operations

🔧 Configuration Reference

1. Required (Mandatory)

2. Telegram Client & Sessions

3. Chat & Permissions

4. Leech & Upload Settings

HyperDL / HyperUP Setup

5. Google Drive

6. Rclone

TeraBox

7. Download Size Limits

8. Torrent / Aria2c / qBittorrent

9. JDownloader & Usenet

10. Media & Search

11. YouTube Tools

12. Log Channels & Notifications

13. FileToLink Streaming

14. Web Server

Web UI Access

14b. Self-Update

Self-Update from a Custom Fork

SABnzbd.ini Patcher Bypass

15. Miscellaneous

🆕 Native TeraBox Download & Selector Update

TeraBox Setup & Cookies

TeraBox Command Recipes

Secure Web Selectors

TeraBox selection

Rclone selection

Compatibility & Reliability

Verification

📖 Command Reference

☁️ Mirror Commands (Download → Cloud Drive)

📥 Leech Commands (Download → Telegram)

📤 Upload Hoster Commands

🔍 Search & Info Commands

⚙️ Task Management

👤 User Commands

🎬 Media & File Tools

🔐 Admin / Sudo Commands

🧹 Drive Purge Manager

Safety and operation

🎞️ Encoding & Metadata

1. Encode Profiles

2. Supported Codecs

3. Track Mapping & Metadata Injection

A. In your Encode Profile (JSON)

B. On the Fly (Command Line)

4. Cover Art Embedding

🎭 Auto-Rename Engine

1. Setting Up Your Template

2. How to Use Auto-Rename