Automated sync from GitHub

.dockerignore

@@ -0,0 +1,9 @@
+.git
+.env
+*.db
+__pycache__
+*.pyc
+.pytest_cache
+tests
+venv
+.venv

.env.example

@@ -0,0 +1,36 @@
+# ---- required ---------------------------------------------------------------
+API_ID=1234567
+API_HASH=0123456789abcdef0123456789abcdef
+BOT_TOKEN=123456789:replace-with-your-bot-token
+OWNER_ID=123456789
+
+# ---- strongly recommended -----------------------------------------------------
+# Hugging Face has no persistent disk. Point this at a free Postgres (Neon, Supabase, ...)
+# so settings, thumbnails, admins and the login session survive restarts.
+# Without it the bot uses a local SQLite file that is wiped on every restart.
+DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require
+
+# ---- optional -------------------------------------------------------------------
+# Extra allowed users (comma separated). The owner can also use /addadmin and /deladmin.
+ADMIN_IDS=
+# Numeric chat id of a channel/group where the bot posts start-up, job and error notices.
+LOG_CHANNEL=
+# Banner for /start: an https image URL or a file path.
+START_IMAGE=
+# Optional Telethon StringSession to log in with (otherwise stored in the database).
+SESSION_STRING=
+
+# Parallel MTProto connections per transfer (1-16).
+TRANSFER_CONNECTIONS=8
+# Files processed at the same time (1-4).
+MAX_CONCURRENT_JOBS=1
+# Largest file accepted, in MB (Telegram's upload limit for bots is 2000).
+MAX_FILE_MB=2000
+# 1 = parallel chunked transfers (falls back to the standard path on any error), 0 = standard only.
+FAST_TRANSFER=1
+# Seconds between progress-message edits (minimum 2).
+PROGRESS_INTERVAL=4
+
+# Set by the Dockerfile; only change for local runs.
+# PORT=7860
+# TEMP_DIR=/tmp/rename

.gitattributes

@@ -1,35 +1,8 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,7 @@
+.env
+*.db
+__pycache__/
+*.pyc
+.pytest_cache/
+venv/
+.venv/

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+# ffmpeg/ffprobe: metadata + track keep/reorder (stream copy, no re-encoding)
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends ffmpeg ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Hugging Face Spaces run Docker containers as user 1000
+RUN useradd -m -u 1000 user
+USER user
+
+ENV HOME=/home/user \
+    PATH=/home/user/.local/bin:$PATH \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    PORT=7860 \
+    TEMP_DIR=/tmp/rename
+
+WORKDIR /home/user/app
+
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY --chown=user bot ./bot
+
+EXPOSE 7860
+CMD ["python", "-m", "bot"]

bot/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.0"

bot/__main__.py

@@ -0,0 +1,3 @@
+from .main import main
+
+main()

bot/app.py

@@ -0,0 +1,774 @@
+"""Telegram handlers: commands, inline menus and the job entry points."""
+from __future__ import annotations
+
+import asyncio
+import html
+import io
+import logging
+import random
+import re
+import shutil
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
+
+import telethon
+from telethon import errors, events, functions, types
+
+from . import fasttransfer as transfer
+from . import media, panels, sysinfo
+from .config import Config
+from .db import Database
+from .parser import build_manual_name, compute_new_name
+from .pipeline import Renamer, original_name_of, source_ext
+from .queue import Job, JobQueue
+from .settings_ops import META_COMMANDS, apply_setting, parse_channel, preview_template
+from .utils import clip, esc, human_size
+
+log = logging.getLogger(__name__)
+
+COMMANDS = [
+    ("start", "Open the main menu"),
+    ("help", "How to use the bot"),
+    ("rename", "Reply to a file with a new name"),
+    ("mode", "Choose Filename or Caption mode"),
+    ("template", "Set the filename template"),
+    ("caption", "Set the caption template"),
+    ("filetype", "Choose how files are sent"),
+    ("metadata", "Metadata and track settings"),
+    ("keepaudio", "Keep audio tracks by language or number"),
+    ("keepsubtitle", "Keep subtitle tracks by language or number"),
+    ("tracks", "List the tracks of a file (reply to it)"),
+    ("thumb", "View your thumbnail"),
+    ("delthumb", "Delete your thumbnail"),
+    ("queue", "Show your queued files"),
+    ("cancel", "Cancel your current job"),
+    ("status", "Show basic bot uptime, ping, and version information."),
+    ("stats", "Show detailed system stats such as users, CPU, RAM, and disk usage."),
+]
+OWNER_COMMANDS = {"addadmin", "deladmin", "admins"}
+BACK = {
+    "template": "rename", "remove": "rename", "caption": "cap",
+    "mt_title": "meta", "mt_author": "meta", "mt_artist": "meta",
+    "mt_audio": "meta", "mt_subtitle": "meta", "mt_video": "meta",
+    "keep_audio": "tool", "keep_subtitle": "tool",
+}
+PANEL_NAMES = {"home", "rename", "cap", "meta", "tool", "ftype", "help", "admin"}
+TRACKS_PROBE_BYTES = 12 * 1024 * 1024
+TRACKS_FULL_LIMIT = 700 * 1024 * 1024
+
+
+@dataclass
+class Pending:
+    kind: str
+    chat_id: int
+    msg_id: int
+    back: str
+    is_photo: bool
+    expires: float
+
+
+def cmd_pattern(name: str) -> "re.Pattern[str]":
+    return re.compile(rf"(?is)^/{name}(?:@\w+)?(?:\s+(.*))?$")
+
+
+def visible_len(html_text: str) -> int:
+    return len(html.unescape(re.sub(r"<[^>]+>", "", html_text)))
+
+
+def plain(html_text: str) -> str:
+    return html.unescape(re.sub(r"<[^>]+>", "", html_text))
+
+
+def is_renameable(message: Any) -> bool:
+    return (
+        getattr(message, "document", None) is not None
+        and not (message.sticker or message.gif or message.voice or message.video_note)
+    )
+
+
+class App:
+    PENDING_TTL = 300
+
+    def __init__(self, client: Any, cfg: Config, db: Database):
+        self.client = client
+        self.cfg = cfg
+        self.db = db
+        self.admins: Set[int] = set(cfg.admin_ids)
+        self.pending: Dict[int, Pending] = {}
+        self.renamer = Renamer(client, cfg, db, self._log_send)
+        self.queue = JobQueue(self.renamer.process, workers=cfg.max_jobs, on_cancelled=self._on_job_cancelled)
+        self._warned: Set[int] = set()
+
+    # ------------------------------------------------------------------ auth
+    def is_owner(self, uid: Optional[int]) -> bool:
+        return uid is not None and uid == self.cfg.owner_id
+
+    def is_allowed(self, uid: Optional[int]) -> bool:
+        return uid is not None and (uid == self.cfg.owner_id or uid in self.admins)
+
+    # ----------------------------------------------------------------- setup
+    async def setup(self) -> None:
+        self.admins |= set(await self.db.list_admins())
+        self.client.parse_mode = "html"
+        self._register()
+        await self._set_commands()
+        if self.cfg.log_channel:
+            try:
+                await self.client.get_input_entity(self.cfg.log_channel)
+            except Exception as exc:  # noqa: BLE001
+                log.warning("cannot access LOG_CHANNEL %s: %s (add the bot there as an admin)", self.cfg.log_channel, exc)
+        self.queue.start()
+
+    async def shutdown(self) -> None:
+        await self.queue.stop()
+
+    async def _set_commands(self) -> None:
+        try:
+            await self.client(
+                functions.bots.SetBotCommandsRequest(
+                    scope=types.BotCommandScopeDefault(),
+                    lang_code="",
+                    commands=[types.BotCommand(command=c, description=d) for c, d in COMMANDS],
+                )
+            )
+        except Exception as exc:  # noqa: BLE001
+            log.warning("could not set the bot command menu: %s", exc)
+
+    async def _log_send(self, text: str) -> None:
+        if self.cfg.log_channel:
+            await self.client.send_message(self.cfg.log_channel, text, parse_mode="html", link_preview=False)
+
+    # --------------------------------------------------------------- plumbing
+    def _guard(self, fn: Callable[[Any], Awaitable[None]], *, owner_only: bool = False):
+        async def wrapper(event: Any) -> None:
+            uid = event.sender_id
+            allowed = self.is_owner(uid) if owner_only else self.is_allowed(uid)
+            if not allowed:
+                if owner_only and self.is_allowed(uid):  # a known user trying an owner command
+                    try:
+                        if hasattr(event, "data"):
+                            await event.answer("Owner only.", alert=True)
+                        else:
+                            await event.respond("⛔ Only the owner can do that.")
+                    except Exception:  # noqa: BLE001
+                        pass
+                else:
+                    await self._stranger(uid)
+                return
+            try:
+                await fn(event)
+            except events.StopPropagation:
+                raise
+            except errors.MessageNotModifiedError:
+                pass
+            except Exception:  # noqa: BLE001
+                log.exception("handler %s failed", getattr(fn, "__name__", fn))
+                try:
+                    if hasattr(event, "data"):
+                        await event.answer("⚠️ Something went wrong.", alert=True)
+                    else:
+                        await event.respond("⚠️ Something went wrong. Please try again.")
+                except Exception:  # noqa: BLE001
+                    pass
+
+        return wrapper
+
+    async def _stranger(self, uid: Optional[int]) -> None:
+        if uid is None or uid in self._warned:
+            return
+        self._warned.add(uid)
+        log.info("ignored unauthorised user %s", uid)
+        try:
+            await self._log_send(f"🚫 Ignored a message from <code>{uid}</code>. Use /addadmin {uid} to allow them.")
+        except Exception:  # noqa: BLE001
+            pass
+
+    def _register(self) -> None:
+        add = self.client.add_event_handler
+        for name, handler in self._command_table().items():
+            add(
+                self._guard(handler, owner_only=name in OWNER_COMMANDS),
+                events.NewMessage(incoming=True, pattern=cmd_pattern(name), func=lambda e: e.is_private),
+            )
+        add(self._guard(self.on_media), events.NewMessage(incoming=True, func=lambda e: e.is_private and is_renameable(e.message)))
+        add(self._guard(self.on_photo), events.NewMessage(incoming=True, func=lambda e: e.is_private and e.message.photo is not None))
+        add(self._guard(self.on_text), events.NewMessage(incoming=True, func=self._wants_text))
+        add(self._guard(self.on_callback), events.CallbackQuery())
+        add(self._on_stranger, events.NewMessage(incoming=True, func=lambda e: e.is_private and not self.is_allowed(e.sender_id)))
+
+    async def _on_stranger(self, event: Any) -> None:
+        await self._stranger(event.sender_id)
+
+    def _wants_text(self, e: Any) -> bool:
+        text = e.raw_text or ""
+        return bool(e.is_private and text and not text.startswith("/") and e.sender_id in self.pending and not e.message.media)
+
+    def _command_table(self) -> Dict[str, Callable[[Any], Awaitable[None]]]:
+        table: Dict[str, Callable[[Any], Awaitable[None]]] = {
+            "start": self.cmd_start, "help": self.cmd_help, "rename": self.cmd_rename, "mode": self.cmd_mode,
+            "template": self.cmd_template, "caption": self.cmd_caption, "filetype": self.cmd_filetype,
+            "metadata": self.cmd_metadata, "keepaudio": self._cmd_keep("keep_audio", "Keep Audio", "/keepaudio English Japanese"),
+            "keepsubtitle": self._cmd_keep("keep_subtitle", "Keep Subtitle", "/keepsubtitle English"),
+            "tracks": self.cmd_tracks, "thumb": self.cmd_thumb, "delthumb": self.cmd_delthumb,
+            "removewords": self.cmd_remove, "setchannel": self.cmd_setchannel, "queue": self.cmd_queue,
+            "cancel": self.cmd_cancel, "status": self.cmd_status, "stats": self.cmd_stats,
+            "addadmin": self.cmd_addadmin, "deladmin": self.cmd_deladmin, "admins": self.cmd_admins,
+        }
+        for command, kind in META_COMMANDS.items():
+            table[command] = self._cmd_meta_field(command, kind)
+        return table
+
+    @staticmethod
+    def _args(event: Any) -> str:
+        return (event.pattern_match.group(1) or "").strip() if event.pattern_match else ""
+
+    async def _reply(self, event: Any, text: str, rows: Optional[List[panels.Row]] = None) -> Any:
+        buttons = panels.to_buttons(rows) if rows else None
+        return await event.respond(text, buttons=buttons, parse_mode="html", link_preview=False)
+
+    # ----------------------------------------------------------------- panels
+    async def panel(self, uid: int, name: str) -> panels.Panel:
+        s = await self.db.get_settings(uid)
+        if name == "home":
+            return panels.home(s, owner=self.is_owner(uid))
+        if name == "rename":
+            return panels.rename(s)
+        if name == "cap":
+            return panels.caption(s, await self.db.has_thumb(uid))
+        if name == "meta":
+            return panels.metadata(s)
+        if name == "tool":
+            return panels.tool(s)
+        if name == "ftype":
+            return panels.filetype(s)
+        if name == "help":
+            return panels.help_panel()
+        if name == "admin":
+            return panels.admin(
+                self.cfg.owner_id, sorted(self.admins), self.queue.running, self.queue.waiting, self.cfg.log_channel
+            )
+        raise KeyError(name)
+
+    @staticmethod
+    async def _remove_message(event: Any) -> None:
+        try:
+            await event.delete()
+        except Exception:  # noqa: BLE001 - Telegram refuses to delete messages older than 48 hours
+            try:
+                await event.edit("Closed.", buttons=None)
+            except Exception:  # noqa: BLE001
+                pass
+
+    async def _edit_panel(self, event: Any, text: str, rows: List[panels.Row]) -> None:
+        try:
+            await event.edit(text, buttons=panels.to_buttons(rows), parse_mode="html")
+        except errors.MessageNotModifiedError:
+            pass
+
+    # --------------------------------------------------------------- commands
+    async def cmd_start(self, event: Any) -> None:
+        self.pending.pop(event.sender_id, None)
+        text, rows = await self.panel(event.sender_id, "home")
+        if self.cfg.start_image:
+            try:
+                await self.client.send_file(
+                    event.chat_id, self.cfg.start_image, caption=text, buttons=panels.to_buttons(rows), parse_mode="html"
+                )
+                return
+            except Exception as exc:  # noqa: BLE001
+                log.warning("could not send START_IMAGE (%s); sending text only", exc)
+        await self._reply(event, text, rows)
+
+    async def cmd_help(self, event: Any) -> None:
+        text, _ = panels.help_panel()
+        await self._reply(event, text, [[("✖ Close", "x:close")]])
+
+    async def cmd_mode(self, event: Any) -> None:
+        arg = self._args(event).lower()
+        uid = event.sender_id
+        if arg in ("filename", "caption"):
+            await self.db.update_settings(uid, mode=arg)
+            await self._reply(event, f"✅ Rename mode: <code>{arg.upper()}</code>")
+            return
+        text, rows = await self.panel(uid, "rename")
+        await self._reply(event, text, rows)
+
+    async def cmd_filetype(self, event: Any) -> None:
+        arg = self._args(event).lower()
+        uid = event.sender_id
+        aliases = {"original": "same", "file": "document", "doc": "document"}
+        arg = aliases.get(arg, arg)
+        if arg in ("same", "document", "video", "audio"):
+            await self.db.update_settings(uid, file_type=arg)
+            label = "same as original" if arg == "same" else arg
+            await self._reply(event, f"✅ Files will be sent as: <code>{label}</code>")
+            return
+        text, rows = await self.panel(uid, "ftype")
+        await self._reply(event, text, rows)
+
+    async def cmd_metadata(self, event: Any) -> None:
+        arg = self._args(event).lower()
+        uid = event.sender_id
+        if arg in ("on", "off"):
+            await self.db.update_settings(uid, metadata_on=(arg == "on"))
+            await self._reply(event, f"✅ Metadata is now <b>{arg.upper()}</b>")
+            return
+        text, rows = await self.panel(uid, "meta")
+        await self._reply(event, text, rows)
+
+    async def cmd_template(self, event: Any) -> None:
+        arg = self._args(event)
+        uid = event.sender_id
+        if arg:
+            _ok, msg = await apply_setting(self.db, uid, "template", arg)
+            await self._reply(event, msg)
+            return
+        s = await self.db.get_settings(uid)
+        await self._reply(
+            event,
+            f"<b>Current template:</b>\n<code>{esc(s['template'])}</code>\n\n{preview_template(s['template'])}\n\n"
+            "Variables: <code>{title} {season} {episode} {quality} {year} {codec} {filename} {ext}</code>\n"
+            "A [bracket] group is dropped when a variable inside it is empty.\n\n"
+            "Change it: <code>/template [S{season}E{episode}] {title} [{quality}]</code>",
+        )
+
+    async def cmd_caption(self, event: Any) -> None:
+        arg = self._args(event)
+        uid = event.sender_id
+        if arg:
+            _ok, msg = await apply_setting(self.db, uid, "caption", arg)
+            await self._reply(event, msg)
+            return
+        s = await self.db.get_settings(uid)
+        await self._reply(
+            event,
+            f"<b>Current caption template:</b>\n<code>{esc(s['caption'])}</code>\n\n"
+            "Variables: <code>{filename} {original} {title} {season} {episode} {quality} {year} {codec} {size} {duration}</code>\n"
+            "Change it: <code>/caption &lt;b&gt;{filename}&lt;/b&gt;</code> · restore: <code>/caption reset</code>",
+        )
+
+    async def cmd_remove(self, event: Any) -> None:
+        arg = self._args(event)
+        uid = event.sender_id
+        if arg:
+            _ok, msg = await apply_setting(self.db, uid, "remove", arg)
+            await self._reply(event, msg)
+            return
+        s = await self.db.get_settings(uid)
+        words = ", ".join(s["remove_words"]) or "none"
+        await self._reply(event, f"<b>Words stripped from names:</b> {esc(words)}\n\nSet: <code>/removewords @Channel, [Group]</code> · clear: <code>/removewords off</code>")
+
+    def _cmd_meta_field(self, command: str, kind: str) -> Callable[[Any], Awaitable[None]]:
+        async def handler(event: Any) -> None:
+            arg = self._args(event)
+            if not arg:
+                s = await self.db.get_settings(event.sender_id)
+                field = kind[3:]
+                current = s["meta"].get(field) or "—"
+                await self._reply(event, f"<b>{field.title()}:</b> <code>{esc(current)}</code>\n\nSet it: <code>/{command} value</code> · clear: <code>/{command} off</code>")
+                return
+            _ok, msg = await apply_setting(self.db, event.sender_id, kind, arg)
+            await self._reply(event, msg)
+
+        handler.__name__ = f"cmd_{command}"
+        return handler
+
+    def _cmd_keep(self, kind: str, label: str, example: str) -> Callable[[Any], Awaitable[None]]:
+        async def handler(event: Any) -> None:
+            arg = self._args(event)
+            uid = event.sender_id
+            if not arg:
+                s = await self.db.get_settings(uid)
+                await self._reply(
+                    event,
+                    f"<b>{label}:</b> {esc(panels.fmt_tokens(s[kind]))}\n\n"
+                    f"Set it with language names or track numbers:\n<code>{example}</code>\n<code>{example.split()[0]} 2 1</code>\n"
+                    f"Only the listed tracks are kept, in that order. <code>{example.split()[0]} off</code> keeps everything.\n"
+                    "Reply to a file with /tracks to see its track numbers.",
+                )
+                return
+            _ok, msg = await apply_setting(self.db, uid, kind, arg)
+            await self._reply(event, msg)
+
+        handler.__name__ = f"cmd_{kind}"
+        return handler
+
+    async def cmd_setchannel(self, event: Any) -> None:
+        arg = self._args(event)
+        uid = event.sender_id
+        if not arg:
+            s = await self.db.get_settings(uid)
+            current = f"<code>{s['target_channel']}</code>" if s["target_channel"] else "not set (files come back to this chat)"
+            await self._reply(event, f"<b>Send renamed files to:</b> {current}\n\nSet: <code>/setchannel -1001234567890</code> (add me to the channel as an admin first) · clear: <code>/setchannel off</code>")
+            return
+        ok, cid, err = parse_channel(arg)
+        if not ok:
+            await self._reply(event, err)
+            return
+        if cid is not None:
+            try:
+                await self.client.get_input_entity(cid)
+            except Exception:  # noqa: BLE001
+                await self._reply(event, "❌ I can't access that chat. Add me to the channel as an admin that can post, then send the id again.")
+                return
+        await self.db.update_settings(uid, target_channel=cid)
+        await self._reply(event, f"✅ Renamed files will go to <code>{cid}</code>." if cid else "✅ Renamed files will come back to this chat.")
+
+    async def cmd_thumb(self, event: Any) -> None:
+        data = await self.db.get_thumb(event.sender_id)
+        if not data:
+            await self._reply(event, "You have no thumbnail. Send me a photo to set one.")
+            return
+        await self._send_thumb(event.chat_id, data)
+
+    async def _send_thumb(self, chat_id: int, data: bytes) -> None:
+        bio = io.BytesIO(data)
+        bio.name = "thumbnail.jpg"
+        await self.client.send_file(
+            chat_id, bio, caption="Your thumbnail", buttons=panels.to_buttons([[("🗑 Delete", "th:rm"), ("✖ Close", "x:close")]])
+        )
+
+    async def cmd_delthumb(self, event: Any) -> None:
+        if await self.db.has_thumb(event.sender_id):
+            await self.db.set_thumb(event.sender_id, None)
+            await self._reply(event, "🗑 Thumbnail deleted.")
+        else:
+            await self._reply(event, "You have no thumbnail.")
+
+    async def on_photo(self, event: Any) -> None:
+        raw = await event.download_media(bytes)
+        if not raw:
+            await self._reply(event, "❌ I couldn't download that photo.")
+            return
+        try:
+            thumb = await asyncio.to_thread(media.prepare_thumb, raw)
+        except Exception:  # noqa: BLE001
+            await self._reply(event, "❌ I couldn't read that image.")
+            return
+        await self.db.set_thumb(event.sender_id, thumb)
+        await self._reply(event, "✅ Thumbnail saved. It will be used for the files I send back.", [[("🗑 Delete", "th:rm"), ("✖ Close", "x:close")]])
+
+    # ------------------------------------------------------------ rename flow
+    async def cmd_rename(self, event: Any) -> None:
+        arg = self._args(event)
+        reply = await event.get_reply_message()
+        if reply is None or not is_renameable(reply) or not arg:
+            await self._reply(event, "Reply to a file with <code>/rename New Name</code>.\nThe extension always stays the same.")
+            return
+        await self.enqueue(event, reply, manual=arg)
+
+    async def on_media(self, event: Any) -> None:
+        await self.enqueue(event, event.message)
+
+    async def enqueue(self, event: Any, msg: Any, manual: Optional[str] = None) -> None:
+        uid = event.sender_id
+        size = int(msg.file.size or 0) if msg.file is not None else 0
+        if size > self.cfg.max_file_bytes:
+            await self._reply(event, f"❌ That file is {human_size(size)}; the limit is {human_size(self.cfg.max_file_bytes)}.")
+            return
+        s = await self.db.get_settings(uid)
+        orig = original_name_of(msg)
+        ext = source_ext(msg, orig)
+        if manual:
+            new_name = build_manual_name(manual, ext)
+        else:
+            new_name, _info = compute_new_name(
+                template=s["template"], mode=s["mode"], original_name=orig, original_ext=ext,
+                caption=msg.raw_text or "", remove_words=s["remove_words"],
+            )
+        job = Job(
+            id=self.queue.new_id(), user_id=uid, chat_id=event.chat_id, msg_id=msg.id,
+            file_name=orig, size=size, new_name=new_name, manual=bool(manual),
+        )
+        ahead = self.queue.running + self.queue.waiting
+        where = "starting soon" if ahead == 0 else f"{ahead} ahead of it"
+        job.status_msg = await event.reply(
+            f"📥 <b>Queued</b> ({where})\n<code>{esc(clip(new_name, 120))}</code>",
+            buttons=panels.to_buttons([[("✖ Cancel", f"job:x:{job.id}")]]),
+            parse_mode="html",
+        )
+        self.queue.add(job)
+
+    async def _on_job_cancelled(self, job: Job) -> None:
+        if job.status_msg is not None:
+            await self.client.edit_message(
+                job.status_msg, f"❌ <b>Cancelled</b>\n<code>{esc(clip(job.new_name, 120))}</code>", buttons=None, parse_mode="html"
+            )
+
+    async def cmd_queue(self, event: Any) -> None:
+        uid = event.sender_id
+        jobs = sorted(self.queue.jobs.values(), key=lambda j: j.id) if self.is_owner(uid) else self.queue.for_user(uid)
+        if not jobs:
+            await self._reply(event, "Nothing in the queue.")
+            return
+        lines = ["<b>Queue</b>"]
+        for j in jobs[:20]:
+            icon = "⚙️" if j.state == "running" else "⏳"
+            who = f" · <code>{j.user_id}</code>" if self.is_owner(uid) else ""
+            lines.append(f"{icon} #{j.id}{who} · <code>{esc(clip(j.new_name, 60))}</code>")
+        if len(jobs) > 20:
+            lines.append(f"… and {len(jobs) - 20} more")
+        lines.append("\n/cancel — cancel yours · <code>/cancel 3</code> — cancel job #3")
+        await self._reply(event, "\n".join(lines))
+
+    async def cmd_cancel(self, event: Any) -> None:
+        uid = event.sender_id
+        arg = self._args(event).lower()
+        if not arg and self.pending.pop(uid, None) is not None:
+            await self._reply(event, "Cancelled — nothing was changed.")
+            return
+        owner_scope = None if self.is_owner(uid) else uid
+        if arg.isdigit():
+            ok = self.queue.cancel(int(arg), user_id=owner_scope)
+            await self._reply(event, "🛑 Cancelling…" if ok else "I couldn't find an active job with that number.")
+            return
+        count = self.queue.cancel_all() if (arg == "all" and self.is_owner(uid)) else self.queue.cancel_user(uid)
+        await self._reply(event, f"🛑 Cancelling {count} job(s)…" if count else "You have no active jobs.")
+
+    # ------------------------------------------------------------------ tracks
+    async def cmd_tracks(self, event: Any) -> None:
+        reply = await event.get_reply_message()
+        if reply is None or not is_renameable(reply):
+            await self._reply(event, "Reply to a video or audio file with /tracks to list its audio and subtitle tracks.")
+            return
+        status = await self._reply(event, "🔎 Reading the tracks…")
+        name = original_name_of(reply)
+        ext = source_ext(reply, name)
+        tmp_dir = Path(self.cfg.temp_dir) / f"tracks{event.chat_id}_{event.id}"
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            path = tmp_dir / f"probe{ext}"
+            size = int(reply.file.size or 0)
+            info = None
+            await transfer.download(
+                self.client, reply, path, fast=self.cfg.fast_transfer, connections=2, max_bytes=TRACKS_PROBE_BYTES
+            )
+            try:
+                info = await media.probe(path)
+            except media.MediaError:
+                info = None
+            if (info is None or not info.streams) and 0 < size <= TRACKS_FULL_LIMIT and size > TRACKS_PROBE_BYTES:
+                await self.client.edit_message(status, "🔎 Reading the tracks (this one needs the whole file)…", parse_mode="html")
+                await transfer.download(self.client, reply, path, fast=self.cfg.fast_transfer, connections=self.cfg.connections)
+                try:
+                    info = await media.probe(path)
+                except media.MediaError:
+                    info = None
+            if info is None or not info.streams:
+                await self.client.edit_message(status, "❌ I couldn't read any tracks from that file.", parse_mode="html")
+                return
+            text = f"<b>{esc(clip(name, 80))}</b>\n\n{media.format_tracks(info)}"
+            await self.client.edit_message(status, text[:3900], parse_mode="html")
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
+    # ----------------------------------------------------------- status/stats
+    async def cmd_status(self, event: Any) -> None:
+        ping_ms: Optional[float] = None
+        try:
+            t0 = time.perf_counter()
+            await self.client(functions.PingRequest(ping_id=random.getrandbits(62)))
+            ping_ms = (time.perf_counter() - t0) * 1000
+        except Exception as exc:  # noqa: BLE001
+            log.debug("ping failed: %s", exc)
+        await self._reply(event, sysinfo.format_status(ping_ms, getattr(self.client.session, "dc_id", None), telethon.__version__))
+
+    async def cmd_stats(self, event: Any) -> None:
+        await self._reply(event, await self._stats_text())
+
+    async def _stats_text(self) -> str:
+        users = await self.db.count_users()
+        files, total = await self.db.totals()
+        return await sysinfo.format_stats(users, files, total, self.queue.running, self.queue.waiting, self.cfg.temp_dir)
+
+    # ------------------------------------------------------------------ admins
+    async def cmd_addadmin(self, event: Any) -> None:
+        arg = self._args(event)
+        if not re.fullmatch(r"\d{4,15}", arg):
+            await self._reply(event, "Usage: <code>/addadmin 123456789</code> (a numeric user id; they can find theirs with @userinfobot).")
+            return
+        uid = int(arg)
+        if uid == self.cfg.owner_id or uid in self.admins:
+            await self._reply(event, "They already have access.")
+            return
+        await self.db.add_admin(uid, event.sender_id)
+        self.admins.add(uid)
+        await self._reply(event, f"✅ <code>{uid}</code> can now use the bot.")
+
+    async def cmd_deladmin(self, event: Any) -> None:
+        arg = self._args(event)
+        if not re.fullmatch(r"\d{4,15}", arg):
+            await self._reply(event, "Usage: <code>/deladmin 123456789</code>")
+            return
+        uid = int(arg)
+        removed = await self.db.del_admin(uid)
+        if uid in self.cfg.admin_ids:
+            await self._reply(event, "That id is listed in the ADMIN_IDS setting; remove it there.")
+            return
+        self.admins.discard(uid)
+        await self._reply(event, f"✅ <code>{uid}</code> was removed." if removed else "That id wasn't in the list.")
+
+    async def cmd_admins(self, event: Any) -> None:
+        ids = ", ".join(f"<code>{a}</code>" for a in sorted(self.admins)) or "none"
+        await self._reply(event, f"<b>Owner:</b> <code>{self.cfg.owner_id}</code>\n<b>Allowed users:</b> {ids}")
+
+    # --------------------------------------------------------------- text input
+    async def on_text(self, event: Any) -> None:
+        uid = event.sender_id
+        p = self.pending.get(uid)
+        if p is None or p.expires < time.time():
+            self.pending.pop(uid, None)
+            return
+        ok, msg = await apply_setting(self.db, uid, p.kind, event.raw_text)
+        if not ok:
+            await self._reply(event, msg + "\n\nTry again, or tap Cancel.")
+            return
+        self.pending.pop(uid, None)
+        try:
+            await event.delete()
+        except Exception:  # noqa: BLE001
+            pass
+        text, rows = await self.panel(uid, p.back)
+        limit = 1000 if p.is_photo else 3900
+        full = f"{msg}\n\n{text}" if visible_len(msg) + visible_len(text) < limit else f"{msg}\n\n(Open the menu to see the update.)"
+        try:
+            await self.client.edit_message(p.chat_id, p.msg_id, full, buttons=panels.to_buttons(rows), parse_mode="html")
+        except Exception:  # noqa: BLE001
+            await self._reply(event, full, rows)
+
+    # ---------------------------------------------------------------- callbacks
+    async def on_callback(self, event: Any) -> None:
+        uid = event.sender_id
+        data = event.data.decode("utf-8", "ignore")
+        parts = data.split(":")
+        head = parts[0]
+
+        if data == "x:close":
+            self.pending.pop(uid, None)
+            await event.answer()
+            await self._remove_message(event)
+            return
+
+        if head == "m" and len(parts) == 2 and parts[1] in PANEL_NAMES:
+            self.pending.pop(uid, None)
+            if parts[1] == "admin" and not self.is_owner(uid):
+                await event.answer("Owner only.", alert=True)
+                return
+            text, rows = await self.panel(uid, parts[1])
+            await self._edit_panel(event, text, rows)
+            await event.answer()
+            return
+
+        if head == "set" and len(parts) == 3:
+            await self._cb_set(event, uid, parts[1], parts[2])
+            return
+
+        if head == "in":
+            await self._cb_input(event, uid, parts)
+            return
+
+        if head == "clr" and len(parts) == 2:
+            if parts[1] == "caption":
+                _ok, msg = await apply_setting(self.db, uid, "caption", "reset")
+                panel = "cap"
+            elif parts[1] in ("keep_audio", "keep_subtitle"):
+                _ok, msg = await apply_setting(self.db, uid, parts[1], "off")
+                panel = "tool"
+            else:
+                await event.answer()
+                return
+            text, rows = await self.panel(uid, panel)
+            await self._edit_panel(event, text, rows)
+            await event.answer(clip(plain(msg), 190))
+            return
+
+        if head == "th" and len(parts) == 2:
+            if parts[1] in ("del", "rm"):
+                await self.db.set_thumb(uid, None)
+                if parts[1] == "rm":  # button on a standalone thumbnail message
+                    await event.answer("Thumbnail deleted.")
+                    await self._remove_message(event)
+                else:  # button inside the Caption & Thumbnail panel
+                    text, rows = await self.panel(uid, "cap")
+                    await self._edit_panel(event, text, rows)
+                    await event.answer("Thumbnail deleted.")
+                return
+            if parts[1] == "view":
+                data_bytes = await self.db.get_thumb(uid)
+                if not data_bytes:
+                    await event.answer("You have no thumbnail yet — send me a photo.", alert=True)
+                    return
+                await event.answer()
+                await self._send_thumb(event.chat_id, data_bytes)
+                return
+
+        if data == "help:meta":
+            text, rows = panels.metadata_help()
+            await self._edit_panel(event, text, rows)
+            await event.answer()
+            return
+
+        if head == "adm" and len(parts) == 2:
+            if not self.is_owner(uid):
+                await event.answer("Owner only.", alert=True)
+                return
+            if parts[1] == "stats":
+                await event.answer()
+                await self.client.send_message(event.chat_id, await self._stats_text(), parse_mode="html")
+            elif parts[1] == "status":
+                await event.answer()
+                await self.client.send_message(
+                    event.chat_id, sysinfo.format_status(None, getattr(self.client.session, "dc_id", None), telethon.__version__),
+                    parse_mode="html",
+                )
+            elif parts[1] == "clear":
+                count = self.queue.cancel_all()
+                await event.answer(f"Cancelling {count} job(s).", alert=True)
+            return
+
+        if head == "job" and len(parts) == 3 and parts[1] == "x" and parts[2].isdigit():
+            ok = self.queue.cancel(int(parts[2]), user_id=None if self.is_owner(uid) else uid)
+            await event.answer("Cancelling…" if ok else "That job already finished.")
+            return
+
+        await event.answer()
+
+    async def _cb_set(self, event: Any, uid: int, field: str, value: str) -> None:
+        if field == "mode" and value in ("filename", "caption"):
+            await self.db.update_settings(uid, mode=value)
+            panel, toast = "rename", f"Mode: {value.title()}"
+        elif field == "ftype" and value in ("same", "document", "video", "audio"):
+            await self.db.update_settings(uid, file_type=value)
+            panel, toast = "ftype", "File type: " + ("Same as original" if value == "same" else value.title())
+        elif field == "meta" and value in ("on", "off"):
+            await self.db.update_settings(uid, metadata_on=(value == "on"))
+            panel, toast = "meta", f"Metadata {value.upper()}"
+        else:
+            await event.answer()
+            return
+        text, rows = await self.panel(uid, panel)
+        await self._edit_panel(event, text, rows)
+        await event.answer(toast)
+
+    async def _cb_input(self, event: Any, uid: int, parts: List[str]) -> None:
+        if len(parts) == 3 and parts[1] == "cancel":
+            self.pending.pop(uid, None)
+            back = parts[2] if parts[2] in PANEL_NAMES else "home"
+            text, rows = await self.panel(uid, back)
+            await self._edit_panel(event, text, rows)
+            await event.answer("Cancelled.")
+            return
+        kind = parts[1] if len(parts) == 2 else ""
+        if kind not in panels.PROMPTS:
+            await event.answer()
+            return
+        msg_obj = await event.get_message()
+        self.pending[uid] = Pending(
+            kind=kind, chat_id=event.chat_id, msg_id=event.message_id, back=BACK[kind],
+            is_photo=bool(msg_obj is not None and msg_obj.photo is not None), expires=time.time() + self.PENDING_TTL,
+        )
+        text, rows = panels.input_prompt(kind, BACK[kind])
+        await self._edit_panel(event, text, rows)
+        await event.answer()

bot/config.py

@@ -0,0 +1,102 @@
+"""Environment-driven configuration."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Mapping, Optional, Tuple
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+def _parse_ids(value: Optional[str]) -> Tuple[int, ...]:
+    ids = []
+    for chunk in (value or "").replace(";", ",").replace(" ", ",").split(","):
+        chunk = chunk.strip()
+        if not chunk:
+            continue
+        try:
+            ids.append(int(chunk))
+        except ValueError as exc:
+            raise ConfigError(f"Invalid id {chunk!r} in ADMIN_IDS") from exc
+    return tuple(ids)
+
+
+def _get_int(env: Mapping[str, str], name: str, default: int) -> int:
+    raw = env.get(name, "").strip()
+    if not raw:
+        return default
+    try:
+        return int(raw)
+    except ValueError as exc:
+        raise ConfigError(f"{name} must be an integer, got {raw!r}") from exc
+
+
+def _get_bool(env: Mapping[str, str], name: str, default: bool) -> bool:
+    raw = env.get(name, "").strip().lower()
+    if not raw:
+        return default
+    return raw in {"1", "true", "yes", "on"}
+
+
+@dataclass(frozen=True)
+class Config:
+    api_id: int
+    api_hash: str
+    bot_token: str
+    owner_id: int
+    admin_ids: Tuple[int, ...]
+    database_url: str
+    session_string: str
+    log_channel: Optional[int]
+    start_image: Optional[str]
+    port: int
+    temp_dir: str
+    max_jobs: int
+    connections: int
+    max_file_mb: int
+    fast_transfer: bool
+    progress_interval: float
+
+    @property
+    def max_file_bytes(self) -> int:
+        return self.max_file_mb * 1024 * 1024
+
+
+def load_config(env: Optional[Mapping[str, str]] = None) -> Config:
+    env = os.environ if env is None else env
+
+    missing = [k for k in ("API_ID", "API_HASH", "BOT_TOKEN", "OWNER_ID") if not env.get(k, "").strip()]
+    if missing:
+        raise ConfigError("Missing required environment variables: " + ", ".join(missing))
+
+    log_channel_raw = env.get("LOG_CHANNEL", "").strip()
+    log_channel = None
+    if log_channel_raw:
+        try:
+            log_channel = int(log_channel_raw)
+        except ValueError as exc:
+            raise ConfigError("LOG_CHANNEL must be a numeric chat id like -1001234567890") from exc
+
+    connections = max(1, min(_get_int(env, "TRANSFER_CONNECTIONS", 8), 16))
+    max_jobs = max(1, min(_get_int(env, "MAX_CONCURRENT_JOBS", 1), 4))
+
+    return Config(
+        api_id=_get_int(env, "API_ID", 0),
+        api_hash=env["API_HASH"].strip(),
+        bot_token=env["BOT_TOKEN"].strip(),
+        owner_id=_get_int(env, "OWNER_ID", 0),
+        admin_ids=_parse_ids(env.get("ADMIN_IDS")),
+        database_url=env.get("DATABASE_URL", "").strip() or "sqlite+aiosqlite:///bot.db",
+        session_string=env.get("SESSION_STRING", "").strip(),
+        log_channel=log_channel,
+        start_image=env.get("START_IMAGE", "").strip() or None,
+        port=_get_int(env, "PORT", 7860),
+        temp_dir=env.get("TEMP_DIR", "").strip() or "/tmp/rename",
+        max_jobs=max_jobs,
+        connections=connections,
+        max_file_mb=max(1, _get_int(env, "MAX_FILE_MB", 2000)),
+        fast_transfer=_get_bool(env, "FAST_TRANSFER", True),
+        progress_interval=max(2.0, float(env.get("PROGRESS_INTERVAL", "4") or 4)),
+    )

bot/db.py

@@ -0,0 +1,232 @@
+"""Async persistence (SQLAlchemy 2.x).
+
+Hugging Face Spaces have no persistent disk, so point ``DATABASE_URL`` at an
+external Postgres (Neon, Supabase, ...).  SQLite works for local testing.
+"""
+from __future__ import annotations
+
+import copy
+import json
+import os
+from datetime import datetime, timezone
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from sqlalchemy import BigInteger, DateTime, Integer, LargeBinary, String, Text, func, select
+from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+from .parser import DEFAULT_TEMPLATE
+
+DEFAULT_SETTINGS: Dict[str, Any] = {
+    "mode": "filename",  # filename | caption
+    "template": DEFAULT_TEMPLATE,
+    "caption": "{filename}",
+    "file_type": "same",  # same | document | video | audio
+    "remove_words": [],
+    "metadata_on": False,
+    "meta": {"title": "", "author": "", "artist": "", "audio": "", "subtitle": "", "video": ""},
+    "keep_audio": [],
+    "keep_subtitle": [],
+    "target_channel": None,
+}
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class User(Base):
+    __tablename__ = "users"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
+    settings: Mapped[str] = mapped_column(Text, default="{}")
+    thumb: Mapped[Optional[bytes]] = mapped_column(LargeBinary, nullable=True)
+    files_renamed: Mapped[int] = mapped_column(Integer, default=0)
+    bytes_processed: Mapped[int] = mapped_column(BigInteger, default=0)
+    first_seen: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+
+
+class Admin(Base):
+    __tablename__ = "admins"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
+    added_by: Mapped[int] = mapped_column(BigInteger, default=0)
+    added_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+
+
+class KV(Base):
+    __tablename__ = "kv"
+
+    key: Mapped[str] = mapped_column(String(64), primary_key=True)
+    value: Mapped[str] = mapped_column(Text, default="")
+
+
+def normalize_database_url(url: str) -> Tuple[str, Dict[str, Any]]:
+    """Turn a provider URL into something SQLAlchemy's async drivers accept."""
+    connect_args: Dict[str, Any] = {}
+    if url.startswith("postgres://"):
+        url = "postgresql://" + url[len("postgres://"):]
+    if url.startswith("postgresql://"):
+        url = "postgresql+asyncpg://" + url[len("postgresql://"):]
+    if url.startswith("postgresql+asyncpg://"):
+        parts = urlsplit(url)
+        query = dict(parse_qsl(parts.query))
+        sslmode = query.pop("sslmode", None)
+        query.pop("channel_binding", None)  # Neon adds this; asyncpg rejects it
+        if sslmode and sslmode != "disable":
+            connect_args["ssl"] = "require"
+        url = urlunsplit(parts._replace(query=urlencode(query)))
+    return url, connect_args
+
+
+def _merge_settings(stored: Dict[str, Any]) -> Dict[str, Any]:
+    merged = copy.deepcopy(DEFAULT_SETTINGS)
+    for key, value in stored.items():
+        if key == "meta" and isinstance(value, dict):
+            merged["meta"].update({k: v for k, v in value.items() if k in merged["meta"]})
+        elif key in merged:
+            merged[key] = value
+    return merged
+
+
+class Database:
+    def __init__(self, url: str):
+        self.url, connect_args = normalize_database_url(url)
+        if self.url.startswith("sqlite"):
+            path = self.url.split("///", 1)[-1]
+            directory = os.path.dirname(path)
+            if directory:
+                os.makedirs(directory, exist_ok=True)
+        self.engine: AsyncEngine = create_async_engine(self.url, pool_pre_ping=True, connect_args=connect_args)
+        self._sessions = async_sessionmaker(self.engine, expire_on_commit=False)
+        self._cache: Dict[int, Dict[str, Any]] = {}
+
+    async def init(self) -> None:
+        async with self.engine.begin() as conn:
+            await conn.run_sync(Base.metadata.create_all)
+
+    async def close(self) -> None:
+        await self.engine.dispose()
+
+    # ----- users / settings ---------------------------------------------------
+    async def _get_or_create(self, session, uid: int) -> User:
+        row = await session.get(User, uid)
+        if row is None:
+            row = User(id=uid, settings="{}")
+            session.add(row)
+            await session.flush()
+        return row
+
+    async def get_settings(self, uid: int) -> Dict[str, Any]:
+        if uid not in self._cache:
+            async with self._sessions() as session:
+                row = await self._get_or_create(session, uid)
+                await session.commit()
+                try:
+                    stored = json.loads(row.settings or "{}")
+                except ValueError:
+                    stored = {}
+            self._cache[uid] = _merge_settings(stored if isinstance(stored, dict) else {})
+        return copy.deepcopy(self._cache[uid])
+
+    async def update_settings(self, uid: int, **changes: Any) -> Dict[str, Any]:
+        """Update top-level keys; a ``meta`` dict is merged field by field."""
+        current = await self.get_settings(uid)
+        for key, value in changes.items():
+            if key not in DEFAULT_SETTINGS:
+                raise KeyError(key)
+            if key == "meta":
+                current["meta"].update(value)
+            else:
+                current[key] = value
+        async with self._sessions() as session:
+            row = await self._get_or_create(session, uid)
+            row.settings = json.dumps(current, ensure_ascii=False)
+            await session.commit()
+        self._cache[uid] = current
+        return copy.deepcopy(current)
+
+    async def set_thumb(self, uid: int, data: Optional[bytes]) -> None:
+        async with self._sessions() as session:
+            row = await self._get_or_create(session, uid)
+            row.thumb = data
+            await session.commit()
+
+    async def get_thumb(self, uid: int) -> Optional[bytes]:
+        async with self._sessions() as session:
+            row = await session.get(User, uid)
+            return bytes(row.thumb) if row is not None and row.thumb else None
+
+    async def has_thumb(self, uid: int) -> bool:
+        async with self._sessions() as session:
+            result = await session.execute(select(User.thumb.isnot(None)).where(User.id == uid))
+            return bool(result.scalar())
+
+    async def record_job(self, uid: int, size: int) -> None:
+        async with self._sessions() as session:
+            row = await self._get_or_create(session, uid)
+            row.files_renamed = (row.files_renamed or 0) + 1
+            row.bytes_processed = (row.bytes_processed or 0) + int(size)
+            await session.commit()
+
+    async def count_users(self) -> int:
+        async with self._sessions() as session:
+            return int((await session.execute(select(func.count()).select_from(User))).scalar() or 0)
+
+    async def totals(self) -> Tuple[int, int]:
+        async with self._sessions() as session:
+            row = (
+                await session.execute(
+                    select(func.coalesce(func.sum(User.files_renamed), 0), func.coalesce(func.sum(User.bytes_processed), 0))
+                )
+            ).one()
+            return int(row[0]), int(row[1])
+
+    # ----- admins ------------------------------------------------------------------
+    async def list_admins(self) -> List[int]:
+        async with self._sessions() as session:
+            return [int(r) for r in (await session.execute(select(Admin.id).order_by(Admin.added_at))).scalars()]
+
+    async def add_admin(self, uid: int, added_by: int = 0) -> bool:
+        async with self._sessions() as session:
+            if await session.get(Admin, uid) is not None:
+                return False
+            session.add(Admin(id=uid, added_by=added_by))
+            await session.commit()
+            return True
+
+    async def del_admin(self, uid: int) -> bool:
+        async with self._sessions() as session:
+            row = await session.get(Admin, uid)
+            if row is None:
+                return False
+            await session.delete(row)
+            await session.commit()
+            return True
+
+    # ----- key/value (session string etc.) ---------------------------------------------
+    async def kv_get(self, key: str) -> Optional[str]:
+        async with self._sessions() as session:
+            row = await session.get(KV, key)
+            return row.value if row is not None else None
+
+    async def kv_set(self, key: str, value: str) -> None:
+        async with self._sessions() as session:
+            row = await session.get(KV, key)
+            if row is None:
+                session.add(KV(key=key, value=value))
+            else:
+                row.value = value
+            await session.commit()
+
+    async def kv_delete(self, key: str) -> None:
+        async with self._sessions() as session:
+            row = await session.get(KV, key)
+            if row is not None:
+                await session.delete(row)
+                await session.commit()

bot/errors.py

@@ -0,0 +1,6 @@
+class Cancelled(Exception):
+    """Raised inside a job when the user cancels it."""
+
+
+class MediaError(RuntimeError):
+    """ffprobe / ffmpeg failed."""

bot/fasttransfer.py

@@ -0,0 +1,430 @@
+"""Parallel (multi-connection) transfers over MTProto.
+
+The part-scheduling logic (``download_parts`` / ``upload_parts``) only talks to a
+tiny ``Transport`` interface, so it is tested offline with fakes.  The Telethon
+specific glue (``open_transports`` and friends) uses a few private Telethon
+helpers; if anything in the fast path fails the wrappers ``download`` /
+``upload`` fall back to Telethon's stock implementation, so the bot keeps
+working (just slower).
+"""
+from __future__ import annotations
+
+import asyncio
+import itertools
+import logging
+import math
+import os
+import threading
+from pathlib import Path
+from typing import Any, Awaitable, Callable, List, Optional, Protocol, Sequence
+
+from .errors import Cancelled
+
+log = logging.getLogger(__name__)
+
+DOWNLOAD_PART = 1024 * 1024  # upload.getFile allows up to 1 MiB per request
+UPLOAD_PART = 512 * 1024  # upload.saveBigFilePart parts are at most 512 KiB
+BIG_FILE_THRESHOLD = 10 * 1024 * 1024  # Telegram wants saveBigFilePart above 10 MB
+PART_TIMEOUT = 120.0
+MAX_RETRIES = 5
+RETRY_BASE_DELAY = 1.0
+
+# Errors that retrying cannot fix: fail fast and let the caller fall back.
+_FATAL_ERROR_NAMES = {
+    "FileReferenceExpiredError", "FileReferenceInvalidError", "FileIdInvalidError", "LocationInvalidError",
+    "OffsetInvalidError", "LimitInvalidError", "FilePartsInvalidError", "FilePartSizeInvalidError",
+    "FileMigrateError", "AuthKeyUnregisteredError", "AuthKeyInvalidError", "SessionRevokedError",
+    "UserDeactivatedError", "UserDeactivatedBanError",
+}
+
+ProgressCb = Callable[[int, int], None]
+
+
+class Transport(Protocol):
+    async def get_file(self, location: Any, offset: int, limit: int) -> bytes: ...
+
+    async def save_part(self, file_id: int, part: int, total_parts: int, data: bytes) -> None: ...
+
+    async def close(self) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# positional file I/O that also works where os.pread/os.pwrite are missing
+# ---------------------------------------------------------------------------
+
+
+class _File:
+    def __init__(self, path: Path | str, mode: str):
+        flags = {"r": os.O_RDONLY, "w": os.O_RDWR | os.O_CREAT | os.O_TRUNC}[mode]
+        flags |= getattr(os, "O_BINARY", 0)
+        self.fd = os.open(str(path), flags, 0o644)
+        self._lock = threading.Lock()
+        self._positional = hasattr(os, "pwrite") and hasattr(os, "pread")
+
+    def pwrite(self, data: bytes, offset: int) -> None:
+        view = memoryview(data)
+        if self._positional:
+            written = 0
+            while written < len(view):
+                written += os.pwrite(self.fd, view[written:], offset + written)
+            return
+        with self._lock:
+            os.lseek(self.fd, offset, os.SEEK_SET)
+            written = 0
+            while written < len(view):
+                written += os.write(self.fd, view[written:])
+
+    def pread(self, size: int, offset: int) -> bytes:
+        if self._positional:
+            return os.pread(self.fd, size, offset)
+        with self._lock:
+            os.lseek(self.fd, offset, os.SEEK_SET)
+            return os.read(self.fd, size)
+
+    def close(self) -> None:
+        os.close(self.fd)
+
+
+# ---------------------------------------------------------------------------
+# generic engines
+# ---------------------------------------------------------------------------
+
+
+async def _retry(op: Callable[[], Awaitable[Any]], *, cancel: Optional[asyncio.Event], what: str) -> Any:
+    delay = RETRY_BASE_DELAY
+    for attempt in range(MAX_RETRIES + 1):
+        if cancel is not None and cancel.is_set():
+            raise Cancelled()
+        try:
+            return await asyncio.wait_for(op(), PART_TIMEOUT)
+        except (asyncio.CancelledError, Cancelled):
+            raise
+        except Exception as exc:  # noqa: BLE001 - classified below
+            if type(exc).__name__ in _FATAL_ERROR_NAMES or attempt >= MAX_RETRIES:
+                raise
+            log.warning("%s failed (%s: %s) - retry %d/%d", what, type(exc).__name__, exc, attempt + 1, MAX_RETRIES)
+            await asyncio.sleep(delay)
+            delay = min(delay * 2, 8.0)
+    raise RuntimeError("unreachable")  # pragma: no cover
+
+
+async def _run_workers(workers: Sequence[Callable[[], Awaitable[None]]]) -> None:
+    tasks = [asyncio.ensure_future(w()) for w in workers]
+    try:
+        pending = set(tasks)
+        while pending:
+            done, pending = await asyncio.wait(pending, return_when=asyncio.FIRST_EXCEPTION)
+            for task in done:
+                if not task.cancelled() and task.exception() is not None:
+                    raise task.exception()  # type: ignore[misc]
+    finally:
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+
+
+async def download_parts(
+    transports: Sequence[Transport],
+    location: Any,
+    size: int,
+    dest: Path | str,
+    *,
+    part_size: int = DOWNLOAD_PART,
+    progress: Optional[ProgressCb] = None,
+    cancel: Optional[asyncio.Event] = None,
+    max_bytes: Optional[int] = None,
+) -> int:
+    """Download ``size`` bytes (or the first ``max_bytes``) into ``dest``; returns bytes written."""
+    total = size if max_bytes is None else min(size, max_bytes)
+    out = _File(dest, "w")
+    try:
+        if total <= 0:
+            return 0
+        n_parts = math.ceil(total / part_size)
+        counter = itertools.count()
+        done = 0
+
+        async def worker(transport: Transport) -> None:
+            nonlocal done
+            while True:
+                if cancel is not None and cancel.is_set():
+                    raise Cancelled()
+                idx = next(counter)
+                if idx >= n_parts:
+                    return
+                offset = idx * part_size
+                want = min(part_size, total - offset)
+
+                async def fetch() -> bytes:
+                    data = await transport.get_file(location, offset, part_size)
+                    if len(data) < want:
+                        raise IOError(f"short read: got {len(data)} of {want} bytes at offset {offset}")
+                    return data
+
+                data = await _retry(fetch, cancel=cancel, what=f"download part {idx + 1}/{n_parts}")
+                await asyncio.to_thread(out.pwrite, data[:want], offset)
+                done += want
+                if progress is not None:
+                    progress(done, total)
+
+        await _run_workers([lambda t=t: worker(t) for t in transports])
+        if done != total:
+            raise IOError(f"download incomplete: {done} of {total} bytes")
+        return total
+    finally:
+        out.close()
+
+
+async def upload_parts(
+    transports: Sequence[Transport],
+    path: Path | str,
+    size: int,
+    file_id: int,
+    *,
+    part_size: int = UPLOAD_PART,
+    progress: Optional[ProgressCb] = None,
+    cancel: Optional[asyncio.Event] = None,
+) -> int:
+    """Upload ``path`` with ``saveBigFilePart``; returns the number of parts."""
+    n_parts = max(1, math.ceil(size / part_size))
+    src = _File(path, "r")
+    try:
+        counter = itertools.count()
+        done = 0
+
+        async def worker(transport: Transport) -> None:
+            nonlocal done
+            while True:
+                if cancel is not None and cancel.is_set():
+                    raise Cancelled()
+                idx = next(counter)
+                if idx >= n_parts:
+                    return
+                offset = idx * part_size
+                want = min(part_size, size - offset)
+                data = await asyncio.to_thread(src.pread, want, offset)
+                if len(data) != want:
+                    raise IOError(f"read {len(data)} of {want} bytes at offset {offset}; was the file modified?")
+                await _retry(
+                    lambda d=data, i=idx: transport.save_part(file_id, i, n_parts, d),
+                    cancel=cancel,
+                    what=f"upload part {idx + 1}/{n_parts}",
+                )
+                done += want
+                if progress is not None:
+                    progress(done, size)
+
+        await _run_workers([lambda t=t: worker(t) for t in transports])
+        if done != size:
+            raise IOError(f"upload incomplete: {done} of {size} bytes")
+        return n_parts
+    finally:
+        src.close()
+
+
+async def close_all(transports: Sequence[Transport]) -> None:
+    await asyncio.gather(*(t.close() for t in transports), return_exceptions=True)
+
+
+# ---------------------------------------------------------------------------
+# Telethon glue
+# ---------------------------------------------------------------------------
+
+
+class TelethonTransport:
+    def __init__(self, client: Any, sender: Any):
+        self._client = client
+        self._sender = sender
+
+    async def get_file(self, location: Any, offset: int, limit: int) -> bytes:
+        from telethon.tl.functions.upload import GetFileRequest
+
+        result = await self._client._call(self._sender, GetFileRequest(location=location, offset=offset, limit=limit))
+        if not hasattr(result, "bytes"):
+            raise IOError(f"unexpected upload.getFile result: {type(result).__name__}")
+        return result.bytes
+
+    async def save_part(self, file_id: int, part: int, total_parts: int, data: bytes) -> None:
+        from telethon.tl.functions.upload import SaveBigFilePartRequest
+
+        ok = await self._client._call(self._sender, SaveBigFilePartRequest(file_id, part, total_parts, data))
+        if not ok:
+            raise IOError("upload.saveBigFilePart returned False")
+
+    async def close(self) -> None:
+        await self._sender.disconnect()
+
+
+async def _open_sender(client: Any, dc_id: int, auth_key: Any) -> Any:
+    from telethon.network import MTProtoSender
+
+    dc = await client._get_dc(dc_id)
+    sender = MTProtoSender(auth_key, loggers=client._log)
+    await sender.connect(
+        client._connection(
+            dc.ip_address, dc.port, dc.id, loggers=client._log, proxy=client._proxy, local_addr=client._local_addr
+        )
+    )
+    return sender
+
+
+async def open_transports(client: Any, dc_id: int, connections: int) -> List[TelethonTransport]:
+    """Open up to ``connections`` extra MTProto connections to ``dc_id``."""
+    from telethon.tl.alltlobjects import LAYER
+    from telethon.tl.functions import InvokeWithLayerRequest
+    from telethon.tl.functions.auth import ExportAuthorizationRequest, ImportAuthorizationRequest
+
+    if dc_id == client.session.dc_id:
+        auth_key = client.session.auth_key
+        first = await _open_sender(client, dc_id, auth_key)
+    else:
+        # a different DC needs its own key, plus our authorization exported/imported once
+        first = await _open_sender(client, dc_id, None)
+        try:
+            exported = await client(ExportAuthorizationRequest(dc_id))
+            client._init_request.query = ImportAuthorizationRequest(id=exported.id, bytes=exported.bytes)
+            await first.send(InvokeWithLayerRequest(LAYER, client._init_request))
+        except BaseException:
+            await first.disconnect()
+            raise
+        auth_key = first.auth_key
+    senders = [first]
+    if connections > 1:
+        results = await asyncio.gather(
+            *(_open_sender(client, dc_id, auth_key) for _ in range(connections - 1)), return_exceptions=True
+        )
+        for res in results:
+            if isinstance(res, BaseException):
+                log.warning("could not open an extra connection to DC %s: %s", dc_id, res)
+            else:
+                senders.append(res)
+    log.info("opened %d connection(s) to DC %s", len(senders), dc_id)
+    return [TelethonTransport(client, s) for s in senders]
+
+
+async def fast_download(
+    client: Any,
+    document: Any,
+    dest: Path | str,
+    *,
+    connections: int = 8,
+    progress: Optional[ProgressCb] = None,
+    cancel: Optional[asyncio.Event] = None,
+    max_bytes: Optional[int] = None,
+) -> int:
+    from telethon import utils
+
+    dc_id, location = utils.get_input_location(document)
+    transports = await open_transports(client, dc_id, connections)
+    try:
+        return await download_parts(
+            transports, location, int(document.size), dest, progress=progress, cancel=cancel, max_bytes=max_bytes
+        )
+    finally:
+        await close_all(transports)
+
+
+async def fast_upload(
+    client: Any,
+    path: Path | str,
+    file_name: str,
+    *,
+    connections: int = 8,
+    progress: Optional[ProgressCb] = None,
+    cancel: Optional[asyncio.Event] = None,
+) -> Any:
+    from telethon.tl.types import InputFileBig
+
+    size = os.path.getsize(path)
+    if size <= BIG_FILE_THRESHOLD:
+        return await client.upload_file(str(path), file_name=file_name, progress_callback=_checked(progress, cancel))
+    file_id = int.from_bytes(os.urandom(8), "big", signed=True)
+    transports = await open_transports(client, client.session.dc_id, connections)
+    try:
+        parts = await upload_parts(transports, path, size, file_id, progress=progress, cancel=cancel)
+    finally:
+        await close_all(transports)
+    return InputFileBig(id=file_id, parts=parts, name=file_name)
+
+
+# ---------------------------------------------------------------------------
+# public wrappers with fallback
+# ---------------------------------------------------------------------------
+
+
+def _checked(progress: Optional[ProgressCb], cancel: Optional[asyncio.Event]) -> ProgressCb:
+    """Progress callback for Telethon's own transfers; raising aborts them."""
+
+    def cb(current: int, total: int) -> None:
+        if cancel is not None and cancel.is_set():
+            raise Cancelled()
+        if progress is not None:
+            progress(current, total)
+
+    return cb
+
+
+def _unlink(path: Path | str) -> None:
+    try:
+        os.unlink(path)
+    except FileNotFoundError:
+        pass
+
+
+async def download(
+    client: Any,
+    message: Any,
+    dest: Path | str,
+    *,
+    fast: bool = True,
+    connections: int = 8,
+    progress: Optional[ProgressCb] = None,
+    cancel: Optional[asyncio.Event] = None,
+    max_bytes: Optional[int] = None,
+) -> None:
+    """Download a message's media to ``dest`` (optionally only the first ``max_bytes``)."""
+    if fast and getattr(message, "document", None) is not None:
+        try:
+            await fast_download(
+                client, message.document, dest, connections=connections, progress=progress, cancel=cancel,
+                max_bytes=max_bytes,
+            )
+            return
+        except Cancelled:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            log.warning("fast download failed (%s: %s); using Telethon's standard download", type(exc).__name__, exc)
+            _unlink(dest)
+    if max_bytes is not None:
+        request = 512 * 1024
+        with open(dest, "wb") as fh:
+            async for chunk in client.iter_download(
+                message.document, request_size=request, limit=max(1, math.ceil(max_bytes / request))
+            ):
+                fh.write(chunk)
+                if cancel is not None and cancel.is_set():
+                    raise Cancelled()
+            fh.truncate(min(fh.tell(), max_bytes))
+        return
+    await client.download_media(message, file=str(dest), progress_callback=_checked(progress, cancel))
+
+
+async def upload(
+    client: Any,
+    path: Path | str,
+    file_name: str,
+    *,
+    fast: bool = True,
+    connections: int = 8,
+    progress: Optional[ProgressCb] = None,
+    cancel: Optional[asyncio.Event] = None,
+) -> Any:
+    """Upload ``path``; returns an ``InputFile``/``InputFileBig`` for ``send_file``."""
+    if fast:
+        try:
+            return await fast_upload(client, path, file_name, connections=connections, progress=progress, cancel=cancel)
+        except Cancelled:
+            raise
+        except Exception as exc:  # noqa: BLE001
+            log.warning("fast upload failed (%s: %s); using Telethon's standard upload", type(exc).__name__, exc)
+    return await client.upload_file(str(path), file_name=file_name, progress_callback=_checked(progress, cancel))

bot/main.py

@@ -0,0 +1,121 @@
+"""Entry point: ``python -m bot``."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+import signal
+import sys
+from pathlib import Path
+from typing import Awaitable, Callable
+
+from . import __version__
+from .config import Config, ConfigError, load_config
+from .db import Database
+
+log = logging.getLogger("bot")
+
+
+def clean_temp_dir(path: str) -> None:
+    """Remove leftovers of a crashed run; only touches our own job folders."""
+    root = Path(path)
+    root.mkdir(parents=True, exist_ok=True)
+    for child in root.iterdir():
+        if child.is_dir() and (child.name.startswith("job") or child.name.startswith("tracks")):
+            shutil.rmtree(child, ignore_errors=True)
+
+
+async def build_client(cfg: Config, db: Database):
+    from telethon import TelegramClient
+    from telethon.sessions import StringSession
+
+    token_id = cfg.bot_token.split(":")[0]
+    session = cfg.session_string
+    if not session and await db.kv_get("session_bot") == token_id:
+        session = await db.kv_get("session") or ""  # keeps the login across Space restarts
+    client = TelegramClient(
+        StringSession(session or None), cfg.api_id, cfg.api_hash,
+        connection_retries=-1, retry_delay=2, auto_reconnect=True, flood_sleep_threshold=60,
+    )
+    await client.start(bot_token=cfg.bot_token)
+    await db.kv_set("session", client.session.save())
+    await db.kv_set("session_bot", token_id)
+    return client
+
+
+async def amain() -> int:
+    from .app import App
+    from .web import start_web
+
+    cfg = load_config()
+    logging.basicConfig(level=logging.INFO, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    logging.getLogger("telethon").setLevel(logging.WARNING)
+    logging.getLogger("sqlalchemy.engine").setLevel(logging.WARNING)
+    log.info("Auto Rename Bot v%s starting", __version__)
+
+    clean_temp_dir(cfg.temp_dir)
+    db = Database(cfg.database_url)
+    await db.init()
+    if db.url.startswith("sqlite"):
+        log.warning("DATABASE_URL is not set: using local SQLite, so settings are lost when the Space restarts")
+
+    runner = await start_web(cfg.port)  # up first: the Space must answer its health check while we log in
+    client = await build_client(cfg, db)
+    me = await client.get_me()
+    app = App(client, cfg, db)
+    await app.setup()
+    log.info("@%s is online (DC %s, %d connection(s) per transfer, fast transfer %s)",
+             me.username, client.session.dc_id, cfg.connections, "on" if cfg.fast_transfer else "off")
+    if cfg.log_channel:
+        try:
+            await app._log_send(f"✅ <b>Bot started</b> · v{__version__} · DC {client.session.dc_id}")
+        except Exception as exc:  # noqa: BLE001
+            log.warning("could not post to LOG_CHANNEL: %s", exc)
+
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, stop.set)
+        except NotImplementedError:  # Windows
+            pass
+    disconnected = asyncio.ensure_future(client.run_until_disconnected())
+    stopper = asyncio.ensure_future(stop.wait())
+    await asyncio.wait({disconnected, stopper}, return_when=asyncio.FIRST_COMPLETED)
+    crashed = disconnected.done() and not stop.is_set()
+
+    log.info("shutting down")
+    await app.shutdown()
+    await runner.cleanup()
+    try:
+        await client.disconnect()
+    except Exception:  # noqa: BLE001
+        pass
+    await db.close()
+    return 1 if crashed else 0
+
+
+def _run(main: Callable[[], Awaitable[int]]) -> int:
+    try:
+        import uvloop
+    except ImportError:
+        return asyncio.run(main())
+    if sys.version_info >= (3, 12):
+        return asyncio.run(main(), loop_factory=uvloop.new_event_loop)
+    uvloop.install()
+    return asyncio.run(main())
+
+
+def main() -> None:
+    try:
+        code = _run(amain)
+    except ConfigError as exc:
+        print(f"Configuration error: {exc}", file=sys.stderr)
+        sys.exit(2)
+    except KeyboardInterrupt:
+        code = 0
+    sys.exit(code)
+
+
+if __name__ == "__main__":
+    main()

bot/media.py

@@ -0,0 +1,442 @@
+"""ffprobe / ffmpeg helpers: probing, track selection, metadata, thumbnails."""
+from __future__ import annotations
+
+import asyncio
+import io
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from .errors import Cancelled, MediaError
+from .utils import esc
+
+VIDEO_CONTAINERS = {".mkv", ".mp4", ".m4v", ".mov", ".webm", ".mka"}
+AUDIO_TAG_EXTS = {".mp3", ".m4a", ".flac", ".ogg", ".opus"}
+
+# canonical name -> accepted aliases (ISO 639-1, 639-2/B, 639-2/T, common names)
+LANGUAGES: Dict[str, Tuple[str, ...]] = {
+    "english": ("en", "eng"),
+    "japanese": ("ja", "jpn", "jap", "jp"),
+    "hindi": ("hi", "hin"),
+    "tamil": ("ta", "tam"),
+    "telugu": ("te", "tel"),
+    "malayalam": ("ml", "mal"),
+    "kannada": ("kn", "kan"),
+    "bengali": ("bn", "ben", "bangla"),
+    "marathi": ("mr", "mar"),
+    "punjabi": ("pa", "pan"),
+    "gujarati": ("gu", "guj"),
+    "urdu": ("ur", "urd"),
+    "korean": ("ko", "kor"),
+    "chinese": ("zh", "zho", "chi", "mandarin", "cantonese", "cmn", "yue"),
+    "spanish": ("es", "spa", "esp"),
+    "portuguese": ("pt", "por", "ptbr"),
+    "french": ("fr", "fra", "fre"),
+    "german": ("de", "deu", "ger"),
+    "italian": ("it", "ita"),
+    "russian": ("ru", "rus"),
+    "arabic": ("ar", "ara"),
+    "turkish": ("tr", "tur"),
+    "indonesian": ("id", "ind"),
+    "thai": ("th", "tha"),
+    "vietnamese": ("vi", "vie"),
+    "malay": ("ms", "msa", "may"),
+    "filipino": ("fil", "tl", "tgl", "tagalog"),
+    "polish": ("pl", "pol"),
+    "dutch": ("nl", "nld", "dut"),
+    "swedish": ("sv", "swe"),
+}
+_ALIAS: Dict[str, str] = {}
+for _name, _aliases in LANGUAGES.items():
+    _ALIAS[_name] = _name
+    for _a in _aliases:
+        _ALIAS[_a] = _name
+_UNDETERMINED = {"", "und", "unk", "zxx", "mul", "mis"}
+
+
+def canonical_lang(code: str) -> Optional[str]:
+    code = (code or "").strip().lower()
+    code = re.split(r"[-_]", code)[0]
+    if code in _UNDETERMINED:
+        return None
+    return _ALIAS.get(code)
+
+
+# ---------------------------------------------------------------------------
+# probing
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Stream:
+    index: int
+    kind: str  # video | audio | subtitle | attachment | data
+    codec: str = ""
+    lang: str = ""
+    title: str = ""
+    default: bool = False
+    forced: bool = False
+    attached_pic: bool = False
+    channels: int = 0
+    width: int = 0
+    height: int = 0
+
+
+@dataclass
+class MediaInfo:
+    duration: float = 0.0
+    width: int = 0
+    height: int = 0
+    format_name: str = ""
+    tags: Dict[str, str] = field(default_factory=dict)
+    streams: List[Stream] = field(default_factory=list)
+
+    def of(self, kind: str) -> List[Stream]:
+        return [s for s in self.streams if s.kind == kind]
+
+    @property
+    def audio(self) -> List[Stream]:
+        return self.of("audio")
+
+    @property
+    def subtitles(self) -> List[Stream]:
+        return self.of("subtitle")
+
+    @property
+    def video(self) -> List[Stream]:
+        return [s for s in self.of("video") if not s.attached_pic]
+
+
+def _parse_hms(value: str) -> float:
+    m = re.fullmatch(r"(\d+):(\d+):(\d+(?:\.\d+)?)", value or "")
+    if not m:
+        return 0.0
+    return int(m.group(1)) * 3600 + int(m.group(2)) * 60 + float(m.group(3))
+
+
+def parse_probe(data: Dict[str, Any]) -> MediaInfo:
+    fmt = data.get("format", {}) or {}
+    info = MediaInfo(
+        format_name=fmt.get("format_name", ""),
+        tags={k.lower(): str(v) for k, v in (fmt.get("tags") or {}).items()},
+    )
+    stream_durations: List[float] = []
+    for raw in data.get("streams", []) or []:
+        tags = {k.lower(): str(v) for k, v in (raw.get("tags") or {}).items()}
+        disp = raw.get("disposition") or {}
+        kind = raw.get("codec_type") or "data"
+        stream = Stream(
+            index=int(raw.get("index", len(info.streams))),
+            kind=kind if kind in {"video", "audio", "subtitle", "attachment", "data"} else "data",
+            codec=raw.get("codec_name", ""),
+            lang=tags.get("language", ""),
+            title=tags.get("title", ""),
+            default=bool(disp.get("default")),
+            forced=bool(disp.get("forced")),
+            attached_pic=bool(disp.get("attached_pic")),
+            channels=int(raw.get("channels") or 0),
+            width=int(raw.get("width") or 0),
+            height=int(raw.get("height") or 0),
+        )
+        info.streams.append(stream)
+        for cand in (raw.get("duration"), tags.get("duration")):
+            try:
+                value = float(cand) if cand and ":" not in str(cand) else _parse_hms(str(cand))
+            except ValueError:
+                value = 0.0
+            if value:
+                stream_durations.append(value)
+                break
+    try:
+        info.duration = float(fmt.get("duration") or 0)
+    except ValueError:
+        info.duration = 0.0
+    if not info.duration and stream_durations:
+        info.duration = max(stream_durations)
+    for s in info.video:
+        info.width, info.height = s.width, s.height
+        break
+    return info
+
+
+async def _run(cmd: Sequence[str], cancel: Optional[asyncio.Event] = None) -> Tuple[int, bytes, bytes]:
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+    except FileNotFoundError as exc:
+        raise MediaError(f"{cmd[0]} is not installed") from exc
+    comm = asyncio.ensure_future(proc.communicate())
+    waiters = [comm]
+    cancel_task = None
+    if cancel is not None:
+        cancel_task = asyncio.ensure_future(cancel.wait())
+        waiters.append(cancel_task)
+    try:
+        await asyncio.wait(waiters, return_when=asyncio.FIRST_COMPLETED)
+        if not comm.done():
+            proc.kill()
+            await proc.wait()
+            comm.cancel()
+            raise Cancelled()
+        out, err = comm.result()
+        return proc.returncode or 0, out, err
+    finally:
+        if cancel_task is not None:
+            cancel_task.cancel()
+        if not comm.done():
+            comm.cancel()
+        if proc.returncode is None:
+            try:
+                proc.kill()
+            except ProcessLookupError:
+                pass
+
+
+async def probe(path: Path | str, cancel: Optional[asyncio.Event] = None) -> MediaInfo:
+    code, out, err = await _run(
+        ["ffprobe", "-v", "error", "-print_format", "json", "-show_format", "-show_streams", str(path)], cancel
+    )
+    try:
+        data = json.loads(out.decode("utf-8", "replace") or "{}")
+    except ValueError:
+        data = {}
+    if not data.get("streams") and code != 0:
+        raise MediaError("ffprobe failed: " + err.decode("utf-8", "replace").strip()[-300:])
+    return parse_probe(data)
+
+
+# ---------------------------------------------------------------------------
+# track selection
+# ---------------------------------------------------------------------------
+
+
+def parse_track_tokens(text: str) -> List[str]:
+    """``"English, Japanese"`` / ``"2 1"`` -> ``["english", "japanese"]`` / ``["2", "1"]``."""
+    tokens: List[str] = []
+    for raw in re.split(r"[\s,;>]+", (text or "").strip().lower()):
+        if raw and raw not in tokens:
+            tokens.append(raw)
+    return tokens
+
+
+def validate_track_tokens(tokens: Sequence[str]) -> Optional[str]:
+    """Return an error message when a token is not a number or a language word."""
+    for token in tokens:
+        if token.isdigit():
+            if int(token) < 1:
+                return f"Track numbers start at 1 (got {token})."
+        elif not re.fullmatch(r"[a-z][a-z\-_]{0,23}", token):
+            return f"“{token}” is not a track number or language name."
+    return None
+
+
+def _matches_language(stream: Stream, token: str) -> bool:
+    wanted = _ALIAS.get(token)
+    have = canonical_lang(stream.lang)
+    if wanted is None:  # a language we do not know by name: compare raw codes / title words
+        raw = re.split(r"[-_]", stream.lang.lower())[0]
+        return raw == token or bool(re.search(rf"\b{re.escape(token)}\b", stream.title.lower()))
+    if have is not None:
+        return have == wanted
+    # untagged track: fall back to words in its title ("English [Dub]")
+    names = (wanted,) + tuple(a for a in LANGUAGES[wanted] if len(a) > 3)
+    title = stream.title.lower()
+    return any(re.search(rf"\b{re.escape(n)}\b", title) for n in names)
+
+
+def resolve_tokens(streams: Sequence[Stream], tokens: Sequence[str]) -> List[Stream]:
+    """Pick streams for ``tokens`` in token order.
+
+    Numbers are 1-based positions among ``streams``; language words select every
+    matching stream (file order).  A stream is only returned once.
+    """
+    chosen: List[Stream] = []
+    for token in tokens:
+        if token.isdigit():
+            pos = int(token)
+            matches = [streams[pos - 1]] if 1 <= pos <= len(streams) else []
+        else:
+            matches = [s for s in streams if _matches_language(s, token)]
+        for s in matches:
+            if s not in chosen:
+                chosen.append(s)
+    return chosen
+
+
+def lang_label(stream: Stream, position: int) -> str:
+    canon = canonical_lang(stream.lang)
+    if canon:
+        return canon.title()
+    return stream.lang.upper() if stream.lang and stream.lang.lower() not in _UNDETERMINED else f"Track {position}"
+
+
+# ---------------------------------------------------------------------------
+# ffmpeg command planning
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Plan:
+    args: List[str]
+    kept_audio: List[Stream] = field(default_factory=list)
+    kept_subtitles: List[Stream] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+
+
+def _stream_title(template: str, stream: Stream, position: int) -> str:
+    return template.replace("{lang}", lang_label(stream, position))
+
+
+def build_plan(info: MediaInfo, settings: Dict[str, Any], ext: str) -> Optional[Plan]:
+    """Work out the ffmpeg options for a file.  ``None`` means "nothing to do"."""
+    if not settings.get("metadata_on"):
+        return None
+    ext = (ext or "").lower()
+    meta = settings.get("meta") or {}
+    keep_audio = list(settings.get("keep_audio") or [])
+    keep_subs = list(settings.get("keep_subtitle") or [])
+
+    if ext in AUDIO_TAG_EXTS:
+        args = ["-map", "0", "-c", "copy", "-map_metadata", "0"]
+        if meta.get("title"):
+            args += ["-metadata", f"title={meta['title']}"]
+        artist = meta.get("artist") or meta.get("author")
+        if artist:
+            args += ["-metadata", f"artist={artist}"]
+        return Plan(args) if len(args) > 6 else None
+
+    if ext not in VIDEO_CONTAINERS:
+        return None
+
+    audio, subs = info.of("audio"), info.of("subtitle")
+    warnings: List[str] = []
+
+    if keep_audio:
+        sel_a = resolve_tokens(audio, keep_audio)
+        if not sel_a and audio:
+            warnings.append("No audio track matched your Keep Audio list, so the original audio was kept.")
+            sel_a = list(audio)
+    else:
+        sel_a = list(audio)
+    sel_s = resolve_tokens(subs, keep_subs) if keep_subs else list(subs)
+
+    filtering = bool(keep_audio or keep_subs)
+    has_edits = filtering or any(meta.get(k) for k in ("title", "author", "artist", "audio", "subtitle", "video"))
+    if not has_edits:
+        return None
+
+    out_video = info.of("video")
+    maps = out_video + sel_a + sel_s + info.of("attachment")
+    if not filtering:
+        maps += info.of("data")
+
+    args: List[str] = ["-map_metadata", "0", "-map_chapters", "0"]
+    for s in maps:
+        args += ["-map", f"0:{s.index}"]
+    args += ["-c", "copy"]
+
+    for key in ("title", "author", "artist"):
+        if meta.get(key):
+            args += ["-metadata", f"{key}={meta[key]}"]
+    if meta.get("video"):
+        for j, s in enumerate(out_video):
+            if not s.attached_pic:
+                args += [f"-metadata:s:v:{j}", f"title={meta['video']}"]
+    if meta.get("audio"):
+        for j, s in enumerate(sel_a):
+            args += [f"-metadata:s:a:{j}", f"title={_stream_title(meta['audio'], s, j + 1)}"]
+    if meta.get("subtitle"):
+        for j, s in enumerate(sel_s):
+            args += [f"-metadata:s:s:{j}", f"title={_stream_title(meta['subtitle'], s, j + 1)}"]
+
+    if keep_audio and sel_a:
+        for j in range(len(sel_a)):
+            args += [f"-disposition:a:{j}", "+default" if j == 0 else "-default"]
+    if keep_subs and sel_s:
+        for j in range(len(sel_s)):
+            args += [f"-disposition:s:{j}", "+default" if j == 0 else "-default"]
+
+    return Plan(args, kept_audio=sel_a, kept_subtitles=sel_s, warnings=warnings)
+
+
+async def apply_plan(src: Path, dst: Path, plan: Plan, cancel: Optional[asyncio.Event] = None) -> None:
+    cmd = [
+        "ffmpeg", "-hide_banner", "-nostdin", "-y", "-loglevel", "error",
+        "-i", str(src), *plan.args, "-max_muxing_queue_size", "9999", str(dst),
+    ]
+    code, _out, err = await _run(cmd, cancel)
+    if code != 0 or not dst.exists() or dst.stat().st_size == 0:
+        raise MediaError("ffmpeg failed: " + err.decode("utf-8", "replace").strip()[-500:])
+
+
+# ---------------------------------------------------------------------------
+# thumbnails
+# ---------------------------------------------------------------------------
+
+
+async def make_video_thumbnail(src: Path, dst: Path, duration: float, cancel: Optional[asyncio.Event] = None) -> bool:
+    """Grab a frame (~10% in) as a small JPEG.  Failure is non-fatal."""
+    seek = 1.0 if duration <= 0 else min(max(duration * 0.1, 0.0), 60.0)
+    cmd = [
+        "ffmpeg", "-hide_banner", "-nostdin", "-y", "-loglevel", "error", "-ss", f"{seek:.2f}", "-i", str(src),
+        "-frames:v", "1", "-vf", "scale='min(320,iw)':-2", "-q:v", "4", str(dst),
+    ]
+    try:
+        code, _o, _e = await _run(cmd, cancel)
+    except MediaError:
+        return False
+    return code == 0 and dst.exists() and dst.stat().st_size > 0
+
+
+def prepare_thumb(data: bytes) -> bytes:
+    """Resize/re-encode an image to Telegram's thumbnail limits (<=320px, <=200 KB JPEG)."""
+    from PIL import Image
+
+    with Image.open(io.BytesIO(data)) as img:
+        img = img.convert("RGB")
+        img.thumbnail((320, 320))
+        for quality in (88, 80, 70, 60, 50, 40):
+            buf = io.BytesIO()
+            img.save(buf, "JPEG", quality=quality, optimize=True)
+            if buf.tell() <= 200 * 1024:
+                break
+        return buf.getvalue()
+
+
+# ---------------------------------------------------------------------------
+# /tracks output
+# ---------------------------------------------------------------------------
+
+
+def format_tracks(info: MediaInfo) -> str:
+    lines: List[str] = []
+    vids = info.video
+    if vids:
+        v = vids[0]
+        res = f" {v.width}x{v.height}" if v.width and v.height else ""
+        lines.append(f"🎞 <b>Video</b>: {esc(v.codec)}{res}")
+    for label, icon, streams in (("Audio", "🔊", info.audio), ("Subtitles", "💬", info.subtitles)):
+        lines.append("")
+        if not streams:
+            lines.append(f"{icon} <b>{label}</b>: none")
+            continue
+        lines.append(f"{icon} <b>{label}</b> (use these numbers)")
+        for pos, s in enumerate(streams, start=1):
+            bits = [lang_label(s, pos)]
+            if s.lang and s.lang.lower() not in _UNDETERMINED:
+                bits[0] += f" ({esc(s.lang)})"
+            if s.codec:
+                bits.append(esc(s.codec))
+            if s.kind == "audio" and s.channels:
+                bits.append(f"{s.channels}ch")
+            if s.title:
+                bits.append(f"“{esc(s.title)}”")
+            if s.default:
+                bits.append("default")
+            if s.forced:
+                bits.append("forced")
+            lines.append(f"{pos}. " + " · ".join(bits))
+    return "\n".join(lines).strip()

bot/panels.py

@@ -0,0 +1,265 @@
+"""Inline-menu panels: pure functions returning ``(html_text, button_rows)``.
+
+Button rows are lists of ``(label, callback_data)``; ``to_buttons`` converts them
+for Telethon.  Panel texts stay well below Telegram's 1024-character caption
+limit because the home banner makes every panel a photo caption.
+"""
+from __future__ import annotations
+
+from typing import Any, Dict, Iterable, List, Sequence, Tuple
+
+from .media import LANGUAGES, canonical_lang
+from .utils import clip, esc
+
+Row = List[Tuple[str, str]]
+Panel = Tuple[str, List[Row]]
+
+DOT = "◈"
+
+
+def to_buttons(rows: Sequence[Row]):
+    from telethon.tl.custom import Button
+
+    return [[Button.inline(label, data.encode()) for label, data in row] for row in rows]
+
+
+def nav(back: str = "", *, home: bool = True) -> List[Row]:
+    row: Row = []
+    if back:
+        row.append(("◀ Back", f"m:{back}"))
+    if home and back != "home":
+        row.append(("🏠 Home", "m:home"))
+    row.append(("✖ Close", "x:close"))
+    return [row]
+
+
+def _check(label: str, active: bool) -> str:
+    return f"{label} ✅" if active else label
+
+
+def _code(value: str, limit: int = 100) -> str:
+    return f"<code>{esc(clip(value, limit))}</code>" if value else "—"
+
+
+def fmt_tokens(tokens: Iterable[str]) -> str:
+    """``["english", "2"]`` -> ``English, 2``"""
+    out = []
+    for t in tokens:
+        out.append(t if t.isdigit() else (canonical_lang(t) or t).title())
+    return ", ".join(out) if out else "—"
+
+
+# ---------------------------------------------------------------------------
+# panels
+# ---------------------------------------------------------------------------
+
+
+def home(s: Dict[str, Any], *, owner: bool) -> Panel:
+    channel = f"channel <code>{s['target_channel']}</code>" if s.get("target_channel") else "this chat"
+    text = (
+        "<b>🏷 Auto Rename Bot</b>\n\n"
+        "Send me a file (document, video or audio) and I'll rename it with your template and send it back.\n\n"
+        f"<b>Mode:</b> <code>{s['mode'].upper()}</code> · <b>Type:</b> <code>{s['file_type'].upper()}</code>"
+        f" · <b>Metadata:</b> <code>{'ON' if s['metadata_on'] else 'OFF'}</code>\n"
+        f"<b>Template:</b> {_code(s['template'], 120)}\n"
+        f"<b>Send to:</b> {channel}"
+    )
+    rows: List[Row] = [
+        [("Rename", "m:rename"), ("Caption & Thumbnail", "m:cap")],
+        [("Metadata", "m:meta"), ("File Type", "m:ftype")],
+        [("Help", "m:help")] + ([("Admin", "m:admin")] if owner else []),
+        [("✖ Close", "x:close")],
+    ]
+    return text, rows
+
+
+def rename(s: Dict[str, Any]) -> Panel:
+    words = ", ".join(s["remove_words"]) or "—"
+    text = (
+        "<b>RENAME MODE</b>\n\n"
+        "Filename mode reads details from the file name.\n"
+        "Caption mode reads details from the message caption.\n\n"
+        f"Current mode: <code>{s['mode'].upper()}</code>\n"
+        "Command: /mode\n\n"
+        f"<b>Template:</b> {_code(s['template'], 120)}\n"
+        f"<b>Remove words:</b> {esc(clip(words, 100))}"
+    )
+    rows: List[Row] = [
+        [(_check("Filename", s["mode"] == "filename"), "set:mode:filename"),
+         (_check("Caption", s["mode"] == "caption"), "set:mode:caption")],
+        [("Template", "in:template"), ("Remove words", "in:remove")],
+    ] + nav("home")
+    return text, rows
+
+
+def caption(s: Dict[str, Any], has_thumb: bool) -> Panel:
+    text = (
+        "<b>CAPTION &amp; THUMBNAIL</b>\n\n"
+        f"<b>Caption template:</b> {_code(s['caption'], 160)}\n"
+        "Variables: <code>{filename} {original} {title} {season} {episode} {quality} {year} {codec} {size} {duration}</code>\n"
+        "Telegram HTML works, e.g. <code>&lt;b&gt;{filename}&lt;/b&gt;</code>\n\n"
+        f"<b>Thumbnail:</b> {'✅ saved' if has_thumb else '❌ none (a frame of the video is used)'}\n"
+        "Send me a photo to set your thumbnail."
+    )
+    rows: List[Row] = [
+        [("Set Caption", "in:caption"), ("Reset Caption", "clr:caption")],
+        [("View Thumb", "th:view"), ("Delete Thumb", "th:del")],
+    ] + nav("home")
+    return text, rows
+
+
+def metadata(s: Dict[str, Any]) -> Panel:
+    m = s["meta"]
+    on = s["metadata_on"]
+    lines = [f"<b>🏷 Your metadata is currently: {'On' if on else 'Off'}</b>", ""]
+    for label, key in (("Title", "title"), ("Author", "author"), ("Artist", "artist"),
+                       ("Audio", "audio"), ("Subtitle", "subtitle"), ("Video", "video")):
+        lines.append(f"{DOT} <b>{label}</b> ▸ {_code(m.get(key, ''), 60)}")
+    lines.append(f"{DOT} <b>Keep Audio</b> ▸ {esc(fmt_tokens(s['keep_audio']))}")
+    lines.append(f"{DOT} <b>Keep Subtitle</b> ▸ {esc(fmt_tokens(s['keep_subtitle']))}")
+    rows: List[Row] = [
+        [(_check("On", on), "set:meta:on"), (_check("Off", not on), "set:meta:off")],
+        [("Title", "in:mt_title"), ("Author", "in:mt_author"), ("Artist", "in:mt_artist")],
+        [("Audio", "in:mt_audio"), ("Subtitle", "in:mt_subtitle"), ("Video", "in:mt_video")],
+        [("Tool", "m:tool")],
+        [("How to Set Metadata", "help:meta")],
+    ] + nav("home")
+    return "\n".join(lines), rows
+
+
+def tool(s: Dict[str, Any]) -> Panel:
+    text = (
+        "<b>🛠 TOOL — keep tracks</b>\n\n"
+        "Only the tracks you list are kept, in the order you list them. Everything else is dropped.\n\n"
+        f"{DOT} <b>Keep Audio</b> ▸ {esc(fmt_tokens(s['keep_audio']))}\n"
+        f"{DOT} <b>Keep Subtitle</b> ▸ {esc(fmt_tokens(s['keep_subtitle']))}\n\n"
+        "Use language names (<code>English Japanese</code>) or track numbers (<code>2 1</code>).\n"
+        "Commands: /keepaudio · /keepsubtitle · /tracks (reply to a file)\n"
+        "Needs metadata to be On."
+    )
+    rows: List[Row] = [
+        [("Keep Audio", "in:keep_audio"), ("Keep Subtitle", "in:keep_subtitle")],
+        [("Clear Audio", "clr:keep_audio"), ("Clear Subtitle", "clr:keep_subtitle")],
+    ] + nav("meta")
+    return text, rows
+
+
+def metadata_help() -> Panel:
+    text = (
+        "<b>How to set metadata</b>\n\n"
+        "Tap a field, then send the value — or use a command:\n"
+        "/settitle Tokyo Revengers\n"
+        "/setauthor @MyChannel\n"
+        "/setartist @MyChannel\n"
+        "/setaudio {lang} Audio\n"
+        "/setsubtitle {lang}\n"
+        "/setvideo @MyChannel\n\n"
+        "Send <code>off</code> instead of a value to clear a field. "
+        "<code>{lang}</code> becomes each track's language name.\n"
+        "Then switch metadata On. Works for mkv, mp4, m4v, mov and webm (title/artist tags for mp3, m4a, flac, ogg, opus)."
+    )
+    return text, nav("meta")
+
+
+def filetype(s: Dict[str, Any]) -> Panel:
+    cur = s["file_type"]
+    text = (
+        "<b>FILE TYPE</b>\n\n"
+        "How renamed files are sent:\n"
+        "• <b>Same as original</b> — video stays video, audio stays audio, a document stays a document\n"
+        "• <b>Document / Video / Audio</b> — always send it that way\n\n"
+        "The file extension always stays the same.\n\n"
+        f"Current: <code>{cur.upper()}</code>\nCommand: /filetype"
+    )
+    rows: List[Row] = [
+        [(_check("Same as original", cur == "same"), "set:ftype:same"),
+         (_check("Document", cur == "document"), "set:ftype:document")],
+        [(_check("Video", cur == "video"), "set:ftype:video"), (_check("Audio", cur == "audio"), "set:ftype:audio")],
+    ] + nav("home")
+    return text, rows
+
+
+def help_panel() -> Panel:
+    text = (
+        "<b>How to use</b>\n\n"
+        "1. Send a file — I rename it with your template and send it back.\n"
+        "2. <code>/rename New Name</code> — reply to a file for a one-off name.\n"
+        "3. /template and /caption — set the naming and caption templates.\n"
+        "4. /mode — read details from the file name or the caption.\n"
+        "5. /metadata, /keepaudio, /keepsubtitle — tags and track clean-up.\n"
+        "6. /filetype — send as document, video or audio.\n"
+        "7. Send a photo — it becomes your thumbnail.\n"
+        "8. /queue and /cancel — manage running jobs.\n\n"
+        "Template variables: <code>{title} {season} {episode} {quality} {year} {codec} {filename} {ext}</code>\n"
+        "A [bracket] group is dropped when a variable inside it is empty."
+    )
+    return text, nav("home")
+
+
+def admin(owner_id: int, admins: Sequence[int], running: int, waiting: int, log_channel: Any) -> Panel:
+    shown = ", ".join(f"<code>{a}</code>" for a in list(admins)[:10]) or "none"
+    more = f" (+{len(admins) - 10} more)" if len(admins) > 10 else ""
+    text = (
+        "<b>ADMIN</b>\n\n"
+        f"<b>Owner:</b> <code>{owner_id}</code>\n"
+        f"<b>Allowed users:</b> {shown}{more}\n"
+        f"<b>Queue:</b> {running} running · {waiting} waiting\n"
+        f"<b>Log channel:</b> {('<code>%s</code>' % log_channel) if log_channel else 'not set (LOG_CHANNEL)'}\n\n"
+        "Commands: /addadmin &lt;id&gt; · /deladmin &lt;id&gt; · /admins"
+    )
+    rows: List[Row] = [
+        [("📊 Stats", "adm:stats"), ("🟢 Status", "adm:status")],
+        [("🛑 Cancel all jobs", "adm:clear")],
+    ] + nav("home")
+    return text, rows
+
+
+# ---------------------------------------------------------------------------
+# input prompts
+# ---------------------------------------------------------------------------
+
+PROMPTS: Dict[str, str] = {
+    "template": (
+        "<b>Send the new filename template.</b>\n\n"
+        "Variables: <code>{title} {season} {episode} {quality} {year} {codec} {filename} {ext}</code>\n"
+        "A [bracket] or (paren) group disappears when a variable inside it is empty.\n"
+        "If only an episode number is found, the season defaults to 01.\n\n"
+        "Example: <code>[S{season}E{episode}] {title} [{quality}]</code>"
+    ),
+    "caption": (
+        "<b>Send the new caption template.</b>\n\n"
+        "Variables: <code>{filename} {original} {title} {season} {episode} {quality} {year} {codec} {size} {duration}</code>\n"
+        "Telegram HTML works (<code>&lt;b&gt;</code>, <code>&lt;i&gt;</code>, <code>&lt;code&gt;</code>)."
+    ),
+    "remove": (
+        "<b>Send the words to strip from names.</b>\n\n"
+        "Separate them with commas, e.g. <code>@SomeChannel, [Group], www.site.com</code>\n"
+        "Send <code>off</code> to clear the list."
+    ),
+    "mt_title": "<b>Send the Title</b> to write into the file's metadata (or <code>off</code> to clear).",
+    "mt_author": "<b>Send the Author</b> to write into the file's metadata (or <code>off</code> to clear).",
+    "mt_artist": "<b>Send the Artist</b> to write into the file's metadata (or <code>off</code> to clear).",
+    "mt_audio": "<b>Send the title for audio tracks</b> (or <code>off</code> to clear).\n<code>{lang}</code> becomes each track's language, e.g. <code>{lang} Audio</code>.",
+    "mt_subtitle": "<b>Send the title for subtitle tracks</b> (or <code>off</code> to clear).\n<code>{lang}</code> becomes each track's language.",
+    "mt_video": "<b>Send the title for the video track</b> (or <code>off</code> to clear).",
+    "keep_audio": (
+        "<b>Which audio tracks should I keep?</b>\n\n"
+        "Send language names (<code>English Japanese</code>) or track numbers (<code>2 1</code>). "
+        "The order you give is the output order; all other tracks are dropped.\n"
+        "Send <code>off</code> to keep everything."
+    ),
+    "keep_subtitle": (
+        "<b>Which subtitle tracks should I keep?</b>\n\n"
+        "Send language names (<code>English</code>) or track numbers (<code>2</code>). "
+        "The order you give is the output order; all other tracks are dropped.\n"
+        "Send <code>off</code> to keep everything."
+    ),
+}
+
+
+def input_prompt(kind: str, back: str) -> Panel:
+    return PROMPTS[kind], [[("✖ Cancel", f"in:cancel:{back}")]]
+
+
+def known_languages() -> str:
+    return ", ".join(sorted(LANGUAGES))

bot/parser.py

@@ -0,0 +1,396 @@
+"""Filename parsing, template rendering and file-name sanitising.
+
+Everything here is pure (no I/O) so it is easy to test.
+"""
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import Dict, Iterable, List, Optional, Tuple
+
+DEFAULT_TEMPLATE = "[S{season}E{episode}] {title} [{quality}]"
+TEMPLATE_VARS = ("title", "season", "episode", "quality", "year", "codec", "filename", "ext")
+MAX_NAME_BYTES = 200
+
+KNOWN_EXTS = {
+    "mkv", "mp4", "m4v", "mov", "avi", "webm", "ts", "flv", "wmv", "mpg", "mpeg", "3gp",
+    "mp3", "m4a", "flac", "ogg", "opus", "wav", "aac", "wma", "mka",
+    "srt", "ass", "ssa", "vtt", "sub",
+    "zip", "rar", "7z", "tar", "gz", "pdf", "epub", "cbz", "cbr", "apk", "iso",
+    "jpg", "jpeg", "png", "webp", "gif", "txt",
+}
+
+_ILLEGAL_RE = re.compile(r'[\x00-\x1f\x7f<>:"/\\|?*]')
+_MULTISPACE_RE = re.compile(r"\s+")
+# tokens that look like an extension but are really part of a release name
+_NOT_EXT_RE = re.compile(r"^(?:\d{3,4}[pi]|[xh]26[45]|hevc|av1|s\d{1,2}e\d{1,4}|e\d{1,4})$", re.I)
+
+# ---------------------------------------------------------------------------
+# extension handling
+# ---------------------------------------------------------------------------
+
+
+def split_ext(name: str, known_only: bool = False) -> Tuple[str, str]:
+    """Split ``name`` into ``(stem, ".ext")``.  ``ext`` is "" when there is none.
+
+    ``known_only`` restricts extensions to a whitelist; it is used for names the
+    user typed, where something like ``Season 1.5`` must not lose its ``.5``.
+    """
+    stem, ext = os.path.splitext(name)
+    if not ext:
+        return name, ""
+    body = ext[1:]
+    if body.lower() in KNOWN_EXTS:
+        return stem, ext
+    if (
+        not known_only
+        and 1 <= len(body) <= 5
+        and body.isalnum()
+        and re.search(r"[A-Za-z]", body)
+        and not _NOT_EXT_RE.match(body)
+    ):
+        return stem, ext
+    return name, ""
+
+
+def finalize_name(stem: str, ext: str, max_bytes: int = MAX_NAME_BYTES) -> str:
+    """Join stem and extension, truncating the stem so the result fits ``max_bytes``."""
+    stem = stem.strip()
+    if ext and stem.lower().endswith(ext.lower()):
+        stem = stem[: -len(ext)].rstrip(" .")
+    ext_bytes = len(ext.encode("utf-8"))
+    while stem and len(stem.encode("utf-8")) + ext_bytes > max_bytes:
+        stem = stem[:-1]
+    stem = stem.rstrip(" .-_") or "file"
+    return stem + ext
+
+
+def sanitize(text: str) -> str:
+    """Remove characters that are illegal in file names and tidy whitespace."""
+    text = _ILLEGAL_RE.sub(" ", text)
+    text = _MULTISPACE_RE.sub(" ", text).strip()
+    return text.lstrip(".").strip()
+
+
+# ---------------------------------------------------------------------------
+# parsing
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class Info:
+    title: str = ""
+    season: str = ""
+    episode: str = ""
+    quality: str = ""
+    year: str = ""
+    codec: str = ""
+
+    @property
+    def structured(self) -> bool:
+        return bool(self.season or self.episode or self.quality or self.year)
+
+
+_Q = r"(?<![A-Za-z0-9])"
+_QUALITY_RE = re.compile(_Q + r"(?:(2160|1440|1080|720|576|540|480|360|240)[pi]|(4k|uhd))(?![A-Za-z0-9])", re.I)
+_RES_RE = re.compile(_Q + r"\d{3,4}x(\d{3,4})(?![A-Za-z0-9])", re.I)
+_SE_RE = re.compile(_Q + r"S(\d{1,2})[ ._\-]?E(\d{1,4})(?!\d)", re.I)
+_NXN_RE = re.compile(_Q + r"(\d{1,2})x(\d{2,3})(?![A-Za-z0-9])", re.I)
+_SEASON_RE = re.compile(_Q + r"(?:Season|S)[ ._\-]?(\d{1,2})(?![A-Za-z0-9])", re.I)
+_EP_WORD_RE = re.compile(_Q + r"(?:Episode|Ep)[ ._\-]?(\d{1,4})(?!\d)", re.I)
+_E_RE = re.compile(_Q + r"E(\d{1,4})(?![A-Za-z0-9])", re.I)
+_DASH_EP_RE = re.compile(r"\s-\s?(\d{1,4})(?:v\d+)?(?=[\s\[\(._\-]|$)")
+_HASH_EP_RE = re.compile(r"#(\d{1,4})(?!\d)")
+_YEAR_PAREN_RE = re.compile(r"[\(\[]((?:19|20)\d{2})[\)\]]")
+_YEAR_BARE_RE = re.compile(_Q + r"((?:19|20)\d{2})(?![A-Za-z0-9])")
+_CODEC_RE = re.compile(_Q + r"(HEVC|[xh]\.?26[45]|AV1|AVC|VP9)(?![A-Za-z0-9])", re.I)
+_SOURCE_RE = re.compile(_Q + r"(?:WEB[ .\-]?DL|WEB[ .\-]?Rip|Blu[ .\-]?Ray|BDRip|BRRip|HDTV|DVDRip|HDRip|REMUX)(?![A-Za-z0-9])", re.I)
+_LEADING_GROUPS_RE = re.compile(r"^(?:\s*[\[\(][^\]\)]*[\]\)])+\s*")
+
+_CODEC_NAMES = {
+    "hevc": "HEVC", "x265": "x265", "x264": "x264", "h265": "H265",
+    "h264": "H264", "av1": "AV1", "avc": "AVC", "vp9": "VP9",
+}
+_COMMON_HEIGHTS = {240, 360, 480, 540, 576, 720, 1080, 1440, 2160}
+
+
+def _normalize(text: str) -> str:
+    text = text.replace("_", " ")
+    if " " not in text.strip():
+        text = text.replace(".", " ")
+    return _MULTISPACE_RE.sub(" ", text).strip()
+
+
+def _strip_markup(text: str) -> str:
+    return re.sub(r"[*`~​-‏⁠]", "", text)
+
+
+def _clean_title(text: str) -> str:
+    text = re.sub(r"[\[\(]\s*$", "", text.strip())
+    text = _MULTISPACE_RE.sub(" ", text.replace("_", " ")).strip(" -._[]()")
+    return text
+
+
+def _fmt_num(value: str) -> str:
+    return f"{int(value):02d}"
+
+
+def parse_info(text: str) -> Info:
+    """Extract title / season / episode / quality / year / codec from a release name."""
+    raw = _strip_markup(text or "")
+    # only strip a *known* extension: callers usually pass a stem already
+    stem, _ext = split_ext(raw.strip().splitlines()[0] if raw.strip() else "", known_only=True)
+    raw = stem
+    norm = _normalize(raw)
+    info = Info()
+    spans: List[Tuple[int, int]] = []  # marker spans inside `norm`
+
+    # --- season / episode ---------------------------------------------------
+    season = episode = ""
+    m = _SE_RE.search(norm)
+    if m:
+        season, episode = m.group(1), m.group(2)
+        spans.append(m.span())
+    else:
+        m = _NXN_RE.search(norm)
+        if m:
+            season, episode = m.group(1), m.group(2)
+            spans.append(m.span())
+        else:
+            ms = _SEASON_RE.search(norm)
+            if ms:
+                season = ms.group(1)
+                spans.append(ms.span())
+            for rx in (_EP_WORD_RE, _E_RE, _DASH_EP_RE, _HASH_EP_RE):
+                me = rx.search(norm)
+                if me:
+                    episode = me.group(1)
+                    spans.append(me.span())
+                    break
+    if episode and not season:
+        season = "1"
+    if episode:
+        info.episode = _fmt_num(episode)
+    if season:
+        info.season = _fmt_num(season)
+
+    # --- quality --------------------------------------------------------------
+    mq = _QUALITY_RE.search(norm)
+    if mq:
+        info.quality = "2160p" if mq.group(2) else f"{mq.group(1)}p"
+        spans.append(mq.span())
+    else:
+        mr = _RES_RE.search(norm)
+        if mr and int(mr.group(1)) in _COMMON_HEIGHTS:
+            info.quality = f"{int(mr.group(1))}p"
+            spans.append(mr.span())
+
+    # --- year -------------------------------------------------------------------
+    year_span: Optional[Tuple[int, int]] = None
+    paren_years = list(_YEAR_PAREN_RE.finditer(norm))
+    if paren_years:
+        mp = paren_years[-1]
+        info.year = mp.group(1)
+        year_span = mp.span()
+    else:
+        candidates = []
+        for my in _YEAR_BARE_RE.finditer(norm):
+            if my.start() == 0:
+                continue
+            if any(a <= my.start() < b for a, b in spans):
+                continue
+            candidates.append(my)
+        if mq:
+            before = [c for c in candidates if c.start() < mq.start()]
+            candidates = before or candidates
+        if candidates:
+            chosen = candidates[-1]
+            info.year = chosen.group(1)
+            year_span = chosen.span()
+    if year_span:
+        spans.append(year_span)
+
+    # --- codec --------------------------------------------------------------------
+    mc = _CODEC_RE.search(raw) or _CODEC_RE.search(norm)
+    if mc:
+        info.codec = _CODEC_NAMES.get(mc.group(1).lower().replace(".", ""), mc.group(1))
+    mcn = _CODEC_RE.search(norm)
+    if mcn:
+        spans.append(mcn.span())
+    ms2 = _SOURCE_RE.search(norm)
+    if ms2:
+        spans.append(ms2.span())
+
+    # --- title ------------------------------------------------------------------------
+    body = _LEADING_GROUPS_RE.sub("", norm)
+    shift = len(norm) - len(body)
+    local = [(a - shift, b - shift) for a, b in spans if b - shift > 0]
+    # markers sitting at the very start ("S01E05 Some Title") are dropped first
+    while True:
+        trimmed = body.lstrip(" -._")
+        lead = len(body) - len(trimmed)
+        if lead:
+            body = trimmed
+            local = [(a - lead, b - lead) for a, b in local if b - lead > 0]
+            continue
+        hit = next(((a, b) for a, b in local if a <= 0 < b), None)
+        if hit is None:
+            break
+        body = body[hit[1]:]
+        local = [(a - hit[1], b - hit[1]) for a, b in local if b - hit[1] > 0]
+    cut = len(body)
+    for a, _b in local:
+        if 0 < a < cut:
+            cut = a
+    # generic bracket groups after the title also end it
+    mb = re.search(r"\s[\[\(]", body)
+    if mb and mb.start() < cut:
+        cut = mb.start()
+    info.title = _clean_title(body[:cut])
+    return info
+
+
+def parse_caption(caption: str) -> Info:
+    """Parse a message caption: title from the first line, details from anywhere."""
+    lines = [ln.strip() for ln in _strip_markup(caption or "").splitlines() if ln.strip()]
+    if not lines:
+        return Info()
+    first = parse_info(lines[0])
+    if len(lines) == 1:
+        return first
+    full = parse_info(" ".join(lines))
+    for field in ("season", "episode", "quality", "year", "codec"):
+        if not getattr(first, field) and getattr(full, field):
+            setattr(first, field, getattr(full, field))
+    return first
+
+
+# ---------------------------------------------------------------------------
+# templates
+# ---------------------------------------------------------------------------
+
+_TEMPLATE_RE = re.compile(r"\[[^\[\]]*\]|\([^()]*\)|\{(\w+)\}")
+_TOKEN_RE = re.compile(r"\{(\w+)\}")
+
+
+def render_template(template: str, values: Dict[str, str]) -> str:
+    """Render ``template``.
+
+    A bracketed ``[...]`` / ``(...)`` group is dropped completely when any known
+    variable inside it is empty, so ``[S{season}E{episode}]`` vanishes instead of
+    leaving ``[SE]`` behind.
+    """
+
+    def sub_tokens(text: str, group: bool) -> Optional[str]:
+        empty = False
+
+        def repl(m: "re.Match[str]") -> str:
+            nonlocal empty
+            name = m.group(1)
+            if name not in values:
+                return m.group(0)
+            val = values.get(name, "")
+            if not val:
+                empty = True
+            return val
+
+        out = _TOKEN_RE.sub(repl, text)
+        return None if (group and empty) else out
+
+    def repl_all(m: "re.Match[str]") -> str:
+        whole = m.group(0)
+        if m.group(1) is not None:  # bare {token}
+            return sub_tokens(whole, group=False) or ""
+        out = sub_tokens(whole, group=True)
+        return out if out is not None else ""
+
+    rendered = _TEMPLATE_RE.sub(repl_all, template)
+    rendered = re.sub(r"\[\s*\]|\(\s*\)", "", rendered)
+    return _MULTISPACE_RE.sub(" ", rendered).strip(" -._")
+
+
+def apply_remove_words(text: str, words: Iterable[str]) -> str:
+    for word in words:
+        word = word.strip()
+        if word:
+            text = re.sub(re.escape(word), "", text, flags=re.I)
+    text = re.sub(r"\[\s*\]|\(\s*\)", "", text)
+    return _MULTISPACE_RE.sub(" ", text).strip(" -._")
+
+
+def sample_values() -> Tuple[str, Dict[str, str]]:
+    sample = "[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234].mkv"
+    info = parse_info(sample)
+    return sample, build_values(info, "[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234]", ".mkv")
+
+
+def build_values(info: Info, original_stem: str, ext: str) -> Dict[str, str]:
+    return {
+        "title": info.title or _clean_title(original_stem),
+        "season": info.season,
+        "episode": info.episode,
+        "quality": info.quality,
+        "year": info.year,
+        "codec": info.codec,
+        "filename": original_stem,
+        "ext": ext.lstrip("."),
+    }
+
+
+def compute_new_name(
+    *,
+    template: str,
+    mode: str,
+    original_name: str,
+    original_ext: str,
+    caption: str = "",
+    remove_words: Iterable[str] = (),
+) -> Tuple[str, Info]:
+    """Return ``(new_file_name, info)`` for an incoming file."""
+    stem, ext = split_ext(original_name)
+    if not ext:
+        ext = original_ext or ""
+    info = parse_info(stem)
+    if mode == "caption" and caption.strip():
+        cinfo = parse_caption(caption)
+        if cinfo.structured:
+            for field in ("title", "season", "episode", "quality", "year", "codec"):
+                if not getattr(cinfo, field) and getattr(info, field):
+                    setattr(cinfo, field, getattr(info, field))
+            info = cinfo
+    values = build_values(info, stem, ext)
+    rendered = render_template(template or DEFAULT_TEMPLATE, values)
+    rendered = apply_remove_words(rendered, remove_words)
+    out_stem = sanitize(rendered) or sanitize(stem)
+    return finalize_name(out_stem, ext), info
+
+
+def build_manual_name(text: str, original_ext: str) -> str:
+    """Name typed by the user (``/rename``): the original extension is always kept."""
+    text = sanitize(text)
+    stem, typed_ext = split_ext(text, known_only=True)
+    ext = original_ext or typed_ext
+    return finalize_name(stem or "file", ext)
+
+
+# ---------------------------------------------------------------------------
+# captions
+# ---------------------------------------------------------------------------
+
+CAPTION_VARS = ("filename", "original", "title", "season", "episode", "quality", "year", "codec", "ext", "size", "duration")
+
+
+def render_caption(template: str, values: Dict[str, str]) -> str:
+    """Fill ``{variables}`` in a caption template.
+
+    The template is Telegram-HTML supplied by the user; the *values* are escaped.
+    Newlines are preserved, unknown ``{tokens}`` are left alone.
+    """
+    import html
+
+    def repl(m: "re.Match[str]") -> str:
+        name = m.group(1)
+        return html.escape(values[name], quote=False) if name in values else m.group(0)
+
+    return _TOKEN_RE.sub(repl, template)

bot/pipeline.py

@@ -0,0 +1,230 @@
+"""The rename pipeline: download -> (ffmpeg) -> upload."""
+from __future__ import annotations
+
+import logging
+import mimetypes
+import shutil
+import time
+import traceback
+from pathlib import Path
+from typing import Any, Awaitable, Callable, Dict, Optional
+
+from telethon import errors, types
+
+from . import fasttransfer as transfer
+from . import media
+from .config import Config
+from .db import Database
+from .errors import Cancelled, MediaError
+from .parser import build_values, parse_info, render_caption, split_ext
+from .progress import ProgressReporter
+from .queue import Job
+from .utils import clip, esc, human_duration, human_size
+
+log = logging.getLogger(__name__)
+
+MIME_OVERRIDES = {
+    ".mkv": "video/x-matroska", ".mka": "audio/x-matroska", ".webm": "video/webm", ".mp4": "video/mp4",
+    ".m4v": "video/x-m4v", ".mov": "video/quicktime", ".avi": "video/x-msvideo", ".ts": "video/mp2t",
+    ".mp3": "audio/mpeg", ".m4a": "audio/mp4", ".flac": "audio/flac", ".ogg": "audio/ogg", ".opus": "audio/ogg",
+    ".wav": "audio/x-wav", ".srt": "application/x-subrip", ".ass": "text/x-ssa", ".zip": "application/zip",
+}
+# containers worth running ffprobe on
+PROBE_EXTS = media.VIDEO_CONTAINERS | media.AUDIO_TAG_EXTS | {".avi", ".ts", ".flv", ".wmv", ".mpg", ".mpeg", ".3gp", ".wav", ".aac", ".wma"}
+
+
+def guess_mime(name: str, fallback: Optional[str]) -> str:
+    ext = split_ext(name)[1].lower()
+    return MIME_OVERRIDES.get(ext) or mimetypes.guess_type(name)[0] or fallback or "application/octet-stream"
+
+
+def decide_send_type(setting: str, message: Any) -> str:
+    """How the renamed file is sent: ``document`` | ``video`` | ``audio``."""
+    if setting in ("document", "video", "audio"):
+        return setting
+    if getattr(message, "video", None) is not None:
+        return "video"
+    if getattr(message, "audio", None) is not None:
+        return "audio"
+    return "document"
+
+
+def source_ext(message: Any, original_name: str) -> str:
+    ext = split_ext(original_name)[1]
+    if not ext:
+        ext = getattr(message.file, "ext", None) or ""
+    return ext
+
+
+def original_name_of(message: Any) -> str:
+    f = message.file
+    if f is not None and f.name:
+        return f.name
+    kind = "video" if getattr(message, "video", None) is not None else "audio" if getattr(message, "audio", None) is not None else "file"
+    return f"{kind}_{message.id}{(f.ext if f is not None else '') or ''}"
+
+
+class Renamer:
+    def __init__(self, client: Any, cfg: Config, db: Database, log_channel_send: Optional[Callable[[str], Awaitable[None]]] = None):
+        self.client = client
+        self.cfg = cfg
+        self.db = db
+        self._log_send = log_channel_send
+
+    # ------------------------------------------------------------------
+    async def _notify_log(self, text: str) -> None:
+        if self._log_send is not None:
+            try:
+                await self._log_send(text)
+            except Exception as exc:  # noqa: BLE001
+                log.warning("could not write to the log channel: %s", exc)
+
+    async def _fresh_message(self, job: Job) -> Any:
+        """Re-fetch the message so its file reference is valid even after a long queue wait."""
+        msg = await self.client.get_messages(job.chat_id, ids=job.msg_id)
+        if msg is None or msg.file is None:
+            raise RuntimeError("the original message was deleted")
+        return msg
+
+    def _check_space(self, work: Path, size: int, will_remux: bool) -> None:
+        need = int(size * (2.2 if will_remux else 1.1)) + 64 * 1024 * 1024
+        free = shutil.disk_usage(work).free
+        if free < need:
+            raise RuntimeError(f"not enough free disk space ({human_size(free)} free, about {human_size(need)} needed)")
+
+    # ------------------------------------------------------------------
+    async def process(self, job: Job) -> None:
+        s = await self.db.get_settings(job.user_id)
+        work = Path(self.cfg.temp_dir) / f"job{job.id}"
+        work.mkdir(parents=True, exist_ok=True)
+        reporter = ProgressReporter(self.client, job.status_msg, job.id, job.new_name, self.cfg.progress_interval)
+        started = time.monotonic()
+        try:
+            await self._run(job, s, work, reporter, started)
+        except Cancelled:
+            job.state = "cancelled"
+            await reporter.finish("❌ <b>Cancelled</b>\n<code>" + esc(clip(job.new_name, 120)) + "</code>")
+        except Exception as exc:  # noqa: BLE001
+            job.state = "failed"
+            log.exception("job %s failed", job.id)
+            reason = clip(f"{type(exc).__name__}: {exc}", 300)
+            await reporter.finish(f"❌ <b>Failed</b>\n<code>{esc(clip(job.new_name, 120))}</code>\n\n{esc(reason)}")
+            tb = "".join(traceback.format_exception_only(type(exc), exc)).strip()
+            await self._notify_log(f"❌ <b>Job failed</b> (user <code>{job.user_id}</code>)\n<code>{esc(clip(job.file_name, 100))}</code>\n<code>{esc(clip(tb, 600))}</code>")
+        finally:
+            shutil.rmtree(work, ignore_errors=True)
+
+    async def _run(self, job: Job, s: Dict[str, Any], work: Path, reporter: ProgressReporter, started: float) -> None:
+        client, cfg = self.client, self.cfg
+        msg = await self._fresh_message(job)
+        orig_name = original_name_of(msg)
+        ext = source_ext(msg, orig_name)
+        send_type = decide_send_type(s["file_type"], msg)
+        size = int(msg.file.size or job.size or 0)
+        src = work / f"src{ext}"
+
+        self._check_space(work, size, will_remux=bool(s["metadata_on"]))
+
+        # ---- download ------------------------------------------------------------
+        reporter.set_stage("⬇️ Downloading", size)
+        await transfer.download(
+            client, msg, src, fast=cfg.fast_transfer, connections=cfg.connections, progress=reporter, cancel=job.cancel
+        )
+        if job.cancel.is_set():
+            raise Cancelled()
+
+        # ---- probe / ffmpeg -----------------------------------------------------------
+        info: Optional[media.MediaInfo] = None
+        current = src
+        if ext.lower() in PROBE_EXTS or send_type in ("video", "audio"):
+            try:
+                info = await media.probe(src, job.cancel)
+            except MediaError as exc:
+                log.info("ffprobe could not read %s: %s", orig_name, exc)
+        warnings = []
+        plan = media.build_plan(info, s, ext) if (info is not None and s["metadata_on"]) else None
+        if s["metadata_on"] and plan is None and info is not None and ext.lower() not in (media.VIDEO_CONTAINERS | media.AUDIO_TAG_EXTS):
+            warnings.append(f"Metadata is not supported for {ext or 'this file type'}, so it was skipped.")
+        if plan is not None:
+            warnings.extend(plan.warnings)
+            reporter.set_stage("⚙️ Applying metadata & tracks", 0)
+            out = work / f"out{ext}"
+            await media.apply_plan(src, out, plan, job.cancel)
+            src.unlink(missing_ok=True)
+            current = out
+            info = await media.probe(current, job.cancel)
+
+        final_size = current.stat().st_size
+
+        # ---- how it will be sent -------------------------------------------------------
+        if send_type == "video" and (info is None or not info.of("video")):
+            send_type = "document"
+        if send_type == "audio" and (info is None or not info.of("audio")):
+            send_type = "document"
+        meta = s["meta"] if s["metadata_on"] else {}
+        attrs = [types.DocumentAttributeFilename(job.new_name)]
+        if send_type == "video":
+            attrs.append(
+                types.DocumentAttributeVideo(
+                    duration=info.duration or 0, w=info.width or 1, h=info.height or 1, supports_streaming=True
+                )
+            )
+        elif send_type == "audio":
+            attrs.append(
+                types.DocumentAttributeAudio(
+                    duration=int(info.duration or 0),
+                    title=(meta.get("title") or info.tags.get("title") or None),
+                    performer=(meta.get("artist") or meta.get("author") or info.tags.get("artist") or None),
+                )
+            )
+
+        thumb = await self.db.get_thumb(job.user_id)
+        if thumb is None and ext.lower() in media.VIDEO_CONTAINERS and info is not None and info.of("video"):
+            thumb_path = work / "thumb.jpg"
+            if await media.make_video_thumbnail(current, thumb_path, info.duration, job.cancel):
+                thumb = thumb_path.read_bytes()
+
+        # ---- caption ---------------------------------------------------------------------
+        parsed = parse_info(split_ext(orig_name)[0])
+        values = build_values(parsed, split_ext(orig_name)[0], ext)
+        values.update(
+            filename=split_ext(job.new_name)[0], original=orig_name, ext=ext.lstrip("."),
+            size=human_size(final_size), duration=human_duration(info.duration) if info and info.duration else "",
+        )
+        caption = render_caption(s["caption"], values)[:1000] or None
+
+        # ---- upload ---------------------------------------------------------------------------
+        reporter.set_stage("⬆️ Uploading", final_size)
+        input_file = await transfer.upload(
+            client, current, job.new_name, fast=cfg.fast_transfer, connections=cfg.connections,
+            progress=reporter, cancel=job.cancel,
+        )
+        if job.cancel.is_set():
+            raise Cancelled()
+        target = s.get("target_channel") or job.chat_id
+        kwargs: Dict[str, Any] = dict(
+            caption=caption, attributes=attrs, mime_type=guess_mime(job.new_name, getattr(msg.file, "mime_type", None)),
+            force_document=(send_type == "document"), thumb=thumb, parse_mode="html",
+        )
+        if target == job.chat_id:
+            kwargs["reply_to"] = job.msg_id
+        try:
+            await client.send_file(target, input_file, **kwargs)
+        except (errors.EntityBoundsInvalidError, errors.MediaCaptionTooLongError, errors.MessageTooLongError):
+            # the caption template produced something Telegram rejects: send the file without a caption
+            kwargs.update(caption=None)
+            await client.send_file(target, input_file, **kwargs)
+            warnings.append("The caption was rejected by Telegram (check your caption template), so it was left out.")
+
+        await self.db.record_job(job.user_id, final_size)
+        job.state = "done"
+        took = time.monotonic() - started
+        note = "".join(f"\n⚠️ {esc(w)}" for w in warnings)
+        where = "" if target == job.chat_id else "\n📣 Sent to your channel."
+        await reporter.finish(
+            f"✅ <b>Done</b> in {human_duration(took)}\n<code>{esc(clip(job.new_name, 120))}</code>\n{human_size(final_size)}{where}{note}"
+        )
+        await self._notify_log(
+            f"✅ <code>{job.user_id}</code>: <code>{esc(clip(job.file_name, 80))}</code> → "
+            f"<code>{esc(clip(job.new_name, 80))}</code> ({human_size(final_size)}, {human_duration(took)})"
+        )

bot/progress.py

@@ -0,0 +1,104 @@
+"""Throttled progress messages (speed, ETA, cancel button)."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import time
+from typing import Any, Optional
+
+from .utils import clip, esc, human_duration, human_size, progress_bar
+
+log = logging.getLogger(__name__)
+
+
+class ProgressReporter:
+    """Callable ``(current, total)`` that edits a status message at most every ``interval`` seconds."""
+
+    def __init__(self, client: Any, message: Any, job_id: int, name: str, interval: float = 4.0):
+        self.client = client
+        self.message = message
+        self.job_id = job_id
+        self.name = name
+        self.interval = interval
+        self.stage = ""
+        self._last_edit = 0.0
+        self._muted_until = 0.0
+        self._inflight: Optional[asyncio.Future] = None
+        self._speed = 0.0
+        self._last_t = 0.0
+        self._last_bytes = 0
+
+    # ---- helpers -------------------------------------------------------------
+    def _buttons(self):
+        from telethon.tl.custom import Button
+
+        return [[Button.inline("✖ Cancel", f"job:x:{self.job_id}".encode())]]
+
+    def render(self, current: int, total: int) -> str:
+        head = f"<b>{self.stage}</b>\n<code>{esc(clip(self.name, 120))}</code>\n"
+        if total <= 0:
+            return head + "\nWorking…"
+        frac = current / total
+        eta = (total - current) / self._speed if self._speed > 0 else 0
+        speed = f"{human_size(self._speed)}/s" if self._speed > 0 else "…"
+        eta_text = human_duration(eta) if self._speed > 0 else "…"
+        return (
+            f"{head}\n{progress_bar(frac)} {frac * 100:.1f}%\n"
+            f"{human_size(current)} / {human_size(total)} · {speed} · ETA {eta_text}"
+        )
+
+    async def _edit(self, text: str, buttons: Any, after: Optional[asyncio.Future] = None) -> None:
+        from telethon import errors
+
+        if after is not None:  # keep edits in order: wait for the one still in flight
+            try:
+                await after
+            except Exception:  # noqa: BLE001
+                pass
+        try:
+            await self.client.edit_message(self.message, text, buttons=buttons, parse_mode="html")
+        except errors.MessageNotModifiedError:
+            pass
+        except errors.FloodWaitError as exc:
+            self._muted_until = time.monotonic() + exc.seconds + 1
+        except Exception as exc:  # noqa: BLE001 - progress is best effort
+            log.debug("progress edit failed: %s", exc)
+
+    # ---- public API -----------------------------------------------------------
+    def set_stage(self, stage: str, total: int = 0) -> None:
+        """Switch stage and show it right away."""
+        self.stage = stage
+        self._speed = 0.0
+        self._last_t = time.monotonic()
+        self._last_bytes = 0
+        self._last_edit = time.monotonic()
+        self._schedule(self.render(0, total), force=True)
+
+    def _schedule(self, text: str, force: bool = False) -> None:
+        """Queue an edit; ordinary progress ticks are dropped while one is in flight, a stage change is not."""
+        busy = self._inflight is not None and not self._inflight.done()
+        if (busy and not force) or time.monotonic() < self._muted_until:
+            return
+        self._inflight = asyncio.ensure_future(self._edit(text, self._buttons(), after=self._inflight if busy else None))
+
+    def __call__(self, current: int, total: int) -> None:
+        now = time.monotonic()
+        dt = now - self._last_t
+        if dt >= 1.0:
+            inst = max(0, current - self._last_bytes) / dt
+            self._speed = inst if self._speed == 0 else self._speed * 0.6 + inst * 0.4
+            self._last_t, self._last_bytes = now, current
+        if now - self._last_edit < self.interval and current < total:
+            return
+        self._last_edit = now
+        self._schedule(self.render(current, total))
+
+    async def finish(self, text: str) -> None:
+        """Final text, buttons removed."""
+        if self._inflight is not None:
+            try:
+                await self._inflight
+            except Exception:  # noqa: BLE001
+                pass
+        self._muted_until = 0.0
+        await self._edit(text, None)

bot/queue.py

@@ -0,0 +1,136 @@
+"""FIFO job queue with a small pool of workers."""
+from __future__ import annotations
+
+import asyncio
+import itertools
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+log = logging.getLogger(__name__)
+
+
+@dataclass
+class Job:
+    id: int
+    user_id: int
+    chat_id: int
+    msg_id: int
+    file_name: str
+    size: int
+    new_name: str
+    manual: bool = False
+    status_msg: Any = None
+    state: str = "queued"  # queued | running | done | failed | cancelled
+    cancel: asyncio.Event = field(default_factory=asyncio.Event)
+    created: float = field(default_factory=time.time)
+    started: float = 0.0
+
+
+Runner = Callable[[Job], Awaitable[None]]
+
+
+class JobQueue:
+    def __init__(self, runner: Runner, workers: int = 1, on_cancelled: Optional[Runner] = None):
+        self._runner = runner
+        self._on_cancelled = on_cancelled
+        self._workers = max(1, workers)
+        self._queue: "asyncio.Queue[Job]" = asyncio.Queue()
+        self._ids = itertools.count(1)
+        self._tasks: List[asyncio.Task] = []
+        self.jobs: Dict[int, Job] = {}
+
+    def new_id(self) -> int:
+        return next(self._ids)
+
+    def start(self) -> None:
+        for _ in range(self._workers):
+            self._tasks.append(asyncio.ensure_future(self._worker()))
+
+    async def stop(self) -> None:
+        for job in list(self.jobs.values()):
+            job.cancel.set()
+        for task in self._tasks:
+            task.cancel()
+        await asyncio.gather(*self._tasks, return_exceptions=True)
+        self._tasks.clear()
+
+    def add(self, job: Job) -> int:
+        """Queue a job; returns how many jobs are ahead of it (running + waiting)."""
+        ahead = self.running + self.waiting
+        self.jobs[job.id] = job
+        self._queue.put_nowait(job)
+        return ahead
+
+    @property
+    def running(self) -> int:
+        return sum(1 for j in self.jobs.values() if j.state == "running")
+
+    @property
+    def waiting(self) -> int:
+        return sum(1 for j in self.jobs.values() if j.state == "queued")
+
+    def position(self, job: Job) -> int:
+        """0 = running now, 1 = next up, ..."""
+        if job.state == "running":
+            return 0
+        waiting = sorted((j for j in self.jobs.values() if j.state == "queued"), key=lambda j: j.id)
+        try:
+            return waiting.index(job) + 1
+        except ValueError:
+            return 0
+
+    def for_user(self, user_id: int) -> List[Job]:
+        return sorted((j for j in self.jobs.values() if j.user_id == user_id), key=lambda j: j.id)
+
+    def cancel(self, job_id: int, user_id: Optional[int] = None) -> bool:
+        job = self.jobs.get(job_id)
+        if job is None or (user_id is not None and job.user_id != user_id):
+            return False
+        return self._cancel_job(job)
+
+    def cancel_user(self, user_id: int) -> int:
+        return sum(self._cancel_job(j) for j in self.for_user(user_id))
+
+    def cancel_all(self) -> int:
+        return sum(self._cancel_job(j) for j in list(self.jobs.values()))
+
+    def _cancel_job(self, job: Job) -> bool:
+        if job.state in ("done", "failed", "cancelled") or job.cancel.is_set():
+            return False  # finished, or a cancel is already on its way
+        job.cancel.set()
+        if job.state == "queued":
+            job.state = "cancelled"
+            self.jobs.pop(job.id, None)
+            if self._on_cancelled is not None:
+                asyncio.ensure_future(self._safe(self._on_cancelled, job))
+        return True
+
+    async def _safe(self, fn: Runner, job: Job) -> None:
+        try:
+            await fn(job)
+        except Exception:  # noqa: BLE001
+            log.exception("job callback failed")
+
+    async def _worker(self) -> None:
+        while True:
+            job = await self._queue.get()
+            try:
+                if job.state != "queued":  # cancelled while waiting
+                    continue
+                job.state = "running"
+                job.started = time.time()
+                try:
+                    await self._runner(job)
+                except asyncio.CancelledError:
+                    raise
+                except Exception:  # noqa: BLE001 - the runner reports its own failures
+                    log.exception("job %s crashed", job.id)
+                    job.state = "failed"
+                finally:
+                    if job.state == "running":
+                        job.state = "done"
+                    self.jobs.pop(job.id, None)
+            finally:
+                self._queue.task_done()

bot/settings_ops.py

@@ -0,0 +1,134 @@
+"""Validation + persistence for every user-editable setting.
+
+Used by both the slash commands and the inline "send me the value" flow, so the
+two can never disagree.  Functions return ``(ok, html_message)``.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional, Tuple
+
+from .db import DEFAULT_SETTINGS, Database
+from .media import parse_track_tokens, validate_track_tokens
+from .parser import (
+    CAPTION_VARS,
+    TEMPLATE_VARS,
+    finalize_name,
+    render_template,
+    sample_values,
+    sanitize,
+)
+from .panels import fmt_tokens
+from .utils import clip, esc
+
+CLEAR_WORDS = {"off", "none", "clear", "reset", "-", "remove"}
+META_KINDS = {
+    "mt_title": "title", "mt_author": "author", "mt_artist": "artist",
+    "mt_audio": "audio", "mt_subtitle": "subtitle", "mt_video": "video",
+}
+META_COMMANDS = {
+    "settitle": "mt_title", "setauthor": "mt_author", "setartist": "mt_artist",
+    "setaudio": "mt_audio", "setsubtitle": "mt_subtitle", "setvideo": "mt_video",
+}
+_TOKEN_RE = re.compile(r"\{(\w+)\}")
+
+
+def preview_template(template: str) -> str:
+    sample, values = sample_values()
+    out = finalize_name(sanitize(render_template(template, values)), ".mkv")
+    return f"Preview for <code>{esc(sample)}</code>:\n<code>{esc(out)}</code>"
+
+
+def _is_clear(text: str) -> bool:
+    return text.strip().lower() in CLEAR_WORDS
+
+
+async def apply_setting(db: Database, uid: int, kind: str, text: str) -> Tuple[bool, str]:
+    text = (text or "").strip()
+
+    if kind == "template":
+        if not text:
+            return False, "❌ The template can't be empty."
+        if _is_clear(text):
+            text = DEFAULT_SETTINGS["template"]
+        if len(text) > 200:
+            return False, "❌ That template is too long (200 characters max)."
+        unknown = sorted(set(_TOKEN_RE.findall(text)) - set(TEMPLATE_VARS))
+        await db.update_settings(uid, template=text)
+        msg = "✅ Template saved.\n" + preview_template(text)
+        if unknown:
+            msg += "\n⚠️ Unknown variables (kept as plain text): " + ", ".join("{%s}" % u for u in unknown)
+        return True, msg
+
+    if kind == "caption":
+        if not text:
+            return False, "❌ The caption can't be empty. Send <code>reset</code> to restore the default."
+        if _is_clear(text):
+            text = DEFAULT_SETTINGS["caption"]
+        if len(text) > 800:
+            return False, "❌ That caption is too long (800 characters max)."
+        unknown = sorted(set(_TOKEN_RE.findall(text)) - set(CAPTION_VARS))
+        await db.update_settings(uid, caption=text)
+        msg = "✅ Caption template saved."
+        if unknown:
+            msg += "\n⚠️ Unknown variables (kept as plain text): " + ", ".join("{%s}" % u for u in unknown)
+        return True, msg
+
+    if kind == "remove":
+        if _is_clear(text):
+            await db.update_settings(uid, remove_words=[])
+            return True, "✅ Remove-words list cleared."
+        words = [w.strip() for w in re.split(r"[,\n]", text) if w.strip()]
+        if not words:
+            return False, "❌ Send at least one word, separated by commas."
+        if len(words) > 50 or any(len(w) > 60 for w in words):
+            return False, "❌ Up to 50 words of 60 characters each."
+        await db.update_settings(uid, remove_words=words)
+        return True, "✅ I'll strip: " + esc(", ".join(words))
+
+    if kind in META_KINDS:
+        field = META_KINDS[kind]
+        if not text:
+            return False, "❌ Send a value, or <code>off</code> to clear it."
+        if _is_clear(text):
+            await db.update_settings(uid, meta={field: ""})
+            return True, f"✅ {field.title()} cleared."
+        if len(text) > 200:
+            return False, "❌ That's too long (200 characters max)."
+        await db.update_settings(uid, meta={field: text})
+        note = ""
+        if not (await db.get_settings(uid))["metadata_on"]:
+            note = "\nℹ️ Metadata is Off — switch it On in /metadata for this to apply."
+        return True, f"✅ {field.title()} set to <code>{esc(clip(text, 80))}</code>.{note}"
+
+    if kind in ("keep_audio", "keep_subtitle"):
+        label = "Keep Audio" if kind == "keep_audio" else "Keep Subtitle"
+        if _is_clear(text):
+            await db.update_settings(uid, **{kind: []})
+            return True, f"✅ {label} cleared — all tracks are kept."
+        tokens = parse_track_tokens(text)
+        if not tokens:
+            return False, "❌ Send language names (<code>English Japanese</code>) or numbers (<code>2 1</code>)."
+        problem = validate_track_tokens(tokens)
+        if problem:
+            return False, "❌ " + esc(problem)
+        if len(tokens) > 12:
+            return False, "❌ That's too many tracks (12 max)."
+        await db.update_settings(uid, **{kind: tokens})
+        msg = f"✅ {label}: {esc(fmt_tokens(tokens))}"
+        if not (await db.get_settings(uid))["metadata_on"]:
+            await db.update_settings(uid, metadata_on=True)
+            msg += "\nℹ️ Metadata was Off, so I turned it On. Use /metadata to switch it off."
+        return True, msg
+
+    raise ValueError(f"unknown setting kind {kind!r}")
+
+
+def parse_channel(text: str) -> Tuple[bool, Optional[int], str]:
+    """``-1001234567890`` -> id; ``off`` -> None."""
+    text = text.strip()
+    if _is_clear(text):
+        return True, None, ""
+    if re.fullmatch(r"-?\d{5,20}", text):
+        return True, int(text), ""
+    return False, None, "❌ Send the numeric chat id, like <code>-1001234567890</code> (not @username)."

bot/sysinfo.py

@@ -0,0 +1,153 @@
+"""Uptime / ping / resource numbers for /status and /stats.
+
+Inside a container psutil reports the *host's* CPU and RAM, so the cgroup files
+are read first and psutil is only the fallback.
+"""
+from __future__ import annotations
+
+import asyncio
+import os
+import platform
+import shutil
+import time
+from typing import Optional, Tuple
+
+import psutil
+
+from . import __version__
+from .utils import human_size, human_uptime
+
+START_TIME = time.time()
+CGROUP_ROOT = "/sys/fs/cgroup"
+_NET_BASE = psutil.net_io_counters()
+
+
+def _read(path: str) -> Optional[str]:
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            return fh.read().strip()
+    except OSError:
+        return None
+
+
+def parse_cpu_max(text: Optional[str]) -> Optional[float]:
+    """cgroup v2 ``cpu.max`` -> number of cores, ``None`` when unlimited."""
+    if not text:
+        return None
+    parts = text.split()
+    if len(parts) != 2 or parts[0] == "max":
+        return None
+    try:
+        quota, period = int(parts[0]), int(parts[1])
+    except ValueError:
+        return None
+    return quota / period if quota > 0 and period > 0 else None
+
+
+def parse_mem_limit(text: Optional[str]) -> Optional[int]:
+    """cgroup ``memory.max`` / v1 ``limit_in_bytes`` -> bytes, ``None`` when unlimited."""
+    if not text or text.strip() == "max":
+        return None
+    try:
+        value = int(text.strip())
+    except ValueError:
+        return None
+    return value if value < 2 ** 60 else None
+
+
+def parse_stat_value(text: Optional[str], key: str) -> Optional[int]:
+    for line in (text or "").splitlines():
+        parts = line.split()
+        if len(parts) == 2 and parts[0] == key:
+            try:
+                return int(parts[1])
+            except ValueError:
+                return None
+    return None
+
+
+def cpu_cores() -> float:
+    quota = parse_cpu_max(_read(f"{CGROUP_ROOT}/cpu.max"))
+    return quota if quota else float(psutil.cpu_count() or 1)
+
+
+def _cgroup_cpu_usec() -> Optional[int]:
+    return parse_stat_value(_read(f"{CGROUP_ROOT}/cpu.stat"), "usage_usec")
+
+
+async def cpu_percent(interval: float = 0.5) -> float:
+    """CPU use of this container as a percentage of its own limit."""
+    first = _cgroup_cpu_usec()
+    if first is None:
+        return psutil.cpu_percent(interval=None)
+    t0 = time.monotonic()
+    await asyncio.sleep(interval)
+    second = _cgroup_cpu_usec()
+    elapsed = time.monotonic() - t0
+    if second is None or elapsed <= 0:
+        return psutil.cpu_percent(interval=None)
+    return max(0.0, min(100.0, (second - first) / (elapsed * 1_000_000) / cpu_cores() * 100))
+
+
+def memory_usage() -> Tuple[int, int]:
+    """(used, total) bytes for this container."""
+    current = _read(f"{CGROUP_ROOT}/memory.current")
+    limit = parse_mem_limit(_read(f"{CGROUP_ROOT}/memory.max"))
+    if current is None:  # cgroup v1
+        current = _read(f"{CGROUP_ROOT}/memory/memory.usage_in_bytes")
+        limit = parse_mem_limit(_read(f"{CGROUP_ROOT}/memory/memory.limit_in_bytes"))
+    host_total = psutil.virtual_memory().total
+    if current is None or not current.isdigit():
+        vm = psutil.virtual_memory()
+        return vm.used, vm.total
+    used = int(current)
+    inactive = parse_stat_value(_read(f"{CGROUP_ROOT}/memory.stat"), "inactive_file") or 0
+    used = max(0, used - inactive)  # do not count reclaimable page cache
+    return used, min(limit, host_total) if limit else host_total
+
+
+def disk_usage(path: str) -> Tuple[int, int, int]:
+    os.makedirs(path, exist_ok=True)
+    du = shutil.disk_usage(path)
+    return du.used, du.total, du.free
+
+
+def net_since_start() -> Tuple[int, int]:
+    now = psutil.net_io_counters()
+    return max(0, now.bytes_recv - _NET_BASE.bytes_recv), max(0, now.bytes_sent - _NET_BASE.bytes_sent)
+
+
+def uptime() -> float:
+    return time.time() - START_TIME
+
+
+def format_status(ping_ms: Optional[float], dc_id: Optional[int], telethon_version: str) -> str:
+    ping = f"{ping_ms:.0f} ms" if ping_ms is not None else "n/a"
+    dc = f" (DC {dc_id})" if dc_id else ""
+    return (
+        "🟢 <b>Bot status</b>\n\n"
+        f"⏱ <b>Uptime:</b> {human_uptime(uptime())}\n"
+        f"🏓 <b>Ping:</b> {ping}{dc}\n"
+        f"🤖 <b>Version:</b> v{__version__}\n"
+        f"🐍 Python {platform.python_version()} · Telethon {telethon_version}"
+    )
+
+
+async def format_stats(users: int, files: int, total_bytes: int, running: int, waiting: int, temp_dir: str) -> str:
+    cpu = await cpu_percent()
+    used, total = memory_usage()
+    d_used, d_total, d_free = disk_usage(temp_dir)
+    rx, tx = net_since_start()
+    rss = psutil.Process().memory_info().rss
+    ram_pct = used / total * 100 if total else 0.0
+    disk_pct = d_used / d_total * 100 if d_total else 0.0
+    return (
+        "📊 <b>System stats</b>\n\n"
+        f"👥 <b>Users:</b> {users}\n"
+        f"📁 <b>Files renamed:</b> {files} ({human_size(total_bytes)})\n"
+        f"🧵 <b>Queue:</b> {running} running · {waiting} waiting\n\n"
+        f"🖥 <b>CPU:</b> {cpu:.1f}% of {cpu_cores():g} core(s)\n"
+        f"🧠 <b>RAM:</b> {human_size(used)} / {human_size(total)} ({ram_pct:.1f}%) · bot {human_size(rss)}\n"
+        f"💾 <b>Disk:</b> {human_size(d_used)} / {human_size(d_total)} ({disk_pct:.1f}%) · {human_size(d_free)} free\n"
+        f"🌐 <b>Network since start:</b> ↓ {human_size(rx)} · ↑ {human_size(tx)}"
+    )

bot/utils.py

@@ -0,0 +1,49 @@
+"""Small formatting helpers."""
+from __future__ import annotations
+
+import html
+
+
+def esc(value: object) -> str:
+    return html.escape(str(value), quote=False)
+
+
+def human_size(num: float) -> str:
+    num = float(num)
+    for unit in ("B", "KB", "MB", "GB", "TB"):
+        if abs(num) < 1024.0 or unit == "TB":
+            return f"{num:.0f} {unit}" if unit == "B" else f"{num:.2f} {unit}"
+        num /= 1024.0
+    return f"{num:.2f} TB"
+
+
+def human_duration(seconds: float) -> str:
+    seconds = int(max(0, seconds))
+    h, rem = divmod(seconds, 3600)
+    m, s = divmod(rem, 60)
+    return f"{h}:{m:02d}:{s:02d}" if h else f"{m}:{s:02d}"
+
+
+def human_uptime(seconds: float) -> str:
+    seconds = int(max(0, seconds))
+    d, rem = divmod(seconds, 86400)
+    h, rem = divmod(rem, 3600)
+    m, s = divmod(rem, 60)
+    parts = []
+    if d:
+        parts.append(f"{d}d")
+    if d or h:
+        parts.append(f"{h}h")
+    parts.append(f"{m}m")
+    parts.append(f"{s}s")
+    return " ".join(parts)
+
+
+def progress_bar(fraction: float, width: int = 14) -> str:
+    fraction = min(1.0, max(0.0, fraction))
+    filled = int(round(fraction * width))
+    return "█" * filled + "░" * (width - filled)
+
+
+def clip(text: str, limit: int) -> str:
+    return text if len(text) <= limit else text[: max(0, limit - 1)] + "…"

bot/web.py

@@ -0,0 +1,36 @@
+"""Tiny health-check server.
+
+A Hugging Face Docker Space expects something listening on its app port; your
+cron pinger can hit ``/`` or ``/health`` to keep the Space awake.
+"""
+from __future__ import annotations
+
+import logging
+
+from aiohttp import web
+
+from . import __version__, sysinfo
+from .utils import human_uptime
+
+log = logging.getLogger(__name__)
+
+
+def make_app() -> web.Application:
+    async def index(_request: web.Request) -> web.Response:
+        return web.Response(text=f"Auto Rename Bot v{__version__} is running ✅\nuptime: {human_uptime(sysinfo.uptime())}\n")
+
+    async def health(_request: web.Request) -> web.Response:
+        return web.json_response({"status": "ok", "version": __version__, "uptime_seconds": int(sysinfo.uptime())})
+
+    app = web.Application()
+    app.router.add_get("/", index)
+    app.router.add_get("/health", health)
+    return app
+
+
+async def start_web(port: int, host: str = "0.0.0.0") -> web.AppRunner:
+    runner = web.AppRunner(make_app(), access_log=None)
+    await runner.setup()
+    await web.TCPSite(runner, host, port).start()
+    log.info("health server listening on %s:%s", host, port)
+    return runner

pytest.ini

@@ -0,0 +1,3 @@
+[pytest]
+asyncio_mode = auto
+testpaths = tests

requirements-dev.txt

@@ -0,0 +1,4 @@
+-r requirements.txt
+pytest>=8
+pytest-asyncio>=0.23
+pyflakes

requirements.txt

@@ -0,0 +1,9 @@
+telethon==1.45.0
+cryptg>=0.5
+SQLAlchemy[asyncio]>=2.0.30,<3
+aiosqlite>=0.20
+asyncpg>=0.29
+aiohttp>=3.9
+psutil>=5.9
+Pillow>=10.0
+uvloop>=0.19; sys_platform != "win32"

tests/conftest.py

@@ -0,0 +1,82 @@
+import json
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+HAVE_FFMPEG = shutil.which("ffmpeg") is not None and shutil.which("ffprobe") is not None
+needs_ffmpeg = pytest.mark.skipif(not HAVE_FFMPEG, reason="ffmpeg/ffprobe not installed")
+
+SRT_A = "1\n00:00:00,000 --> 00:00:01,000\nkonnichiwa\n\n"
+SRT_B = "1\n00:00:00,000 --> 00:00:01,000\nhello\n\n"
+FFMETA = """;FFMETADATA1
+title=Original Title
+[CHAPTER]
+TIMEBASE=1/1000
+START=0
+END=1000
+title=Intro
+[CHAPTER]
+TIMEBASE=1/1000
+START=1000
+END=2000
+title=Main
+"""
+
+
+def run(cmd):
+    subprocess.run(cmd, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE)
+
+
+def ffprobe_json(path, *extra):
+    out = subprocess.run(
+        ["ffprobe", "-v", "error", "-print_format", "json", "-show_format", "-show_streams", *extra, str(path)],
+        check=True, capture_output=True,
+    ).stdout
+    return json.loads(out)
+
+
+@pytest.fixture(scope="session")
+def media_dir(tmp_path_factory):
+    d = tmp_path_factory.mktemp("media")
+    if not HAVE_FFMPEG:
+        return d
+    (d / "a.srt").write_text(SRT_A)
+    (d / "b.srt").write_text(SRT_B)
+    (d / "meta.ffmeta").write_text(FFMETA)
+    (d / "font.ttf").write_bytes(os.urandom(2048))
+    lavfi_v = ["-f", "lavfi", "-i", "testsrc=duration=2:size=320x240:rate=15"]
+    lavfi_a = lambda f: ["-f", "lavfi", "-i", f"sine=frequency={f}:duration=2"]  # noqa: E731
+
+    # MKV: 1 video, 3 audio (jpn, eng, hin), 2 subs (jpn, eng), 1 font attachment, 2 chapters
+    run(
+        ["ffmpeg", "-y", "-loglevel", "error", *lavfi_v, *lavfi_a(440), *lavfi_a(880), *lavfi_a(220),
+         "-i", str(d / "a.srt"), "-i", str(d / "b.srt"), "-i", str(d / "meta.ffmeta"),
+         "-attach", str(d / "font.ttf"), "-metadata:s:t:0", "mimetype=application/x-truetype-font",
+         "-map", "0:v", "-map", "1:a", "-map", "2:a", "-map", "3:a", "-map", "4:s", "-map", "5:s",
+         "-map_metadata", "6", "-map_chapters", "6",
+         "-c:v", "libx264", "-preset", "ultrafast", "-c:a", "aac", "-c:s", "srt",
+         "-metadata:s:a:0", "language=jpn", "-metadata:s:a:0", "title=Japanese Original",
+         "-metadata:s:a:1", "language=eng", "-metadata:s:a:2", "language=hin",
+         "-metadata:s:s:0", "language=jpn", "-metadata:s:s:1", "language=eng",
+         "-disposition:a:0", "default", str(d / "sample.mkv")]
+    )
+    # MP4: 1 video, 2 audio (jpn, eng), 1 eng subtitle (mov_text)
+    run(
+        ["ffmpeg", "-y", "-loglevel", "error", *lavfi_v, *lavfi_a(440), *lavfi_a(880), "-i", str(d / "b.srt"),
+         "-map", "0:v", "-map", "1:a", "-map", "2:a", "-map", "3:s",
+         "-c:v", "libx264", "-preset", "ultrafast", "-pix_fmt", "yuv420p", "-c:a", "aac", "-c:s", "mov_text",
+         "-metadata:s:a:0", "language=jpn", "-metadata:s:a:1", "language=eng", "-metadata:s:s:0", "language=eng",
+         str(d / "sample.mp4")]
+    )
+    # MP3 with a title tag
+    run(
+        ["ffmpeg", "-y", "-loglevel", "error", *lavfi_a(440), "-c:a", "libmp3lame", "-metadata", "title=Old",
+         str(d / "sample.mp3")]
+    )
+    return d

tests/test_app.py

@@ -0,0 +1,822 @@
+"""Handler-level tests: real Telethon event builders, fake events and client."""
+import asyncio
+import dataclasses
+import io
+import shutil
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from PIL import Image
+from telethon import functions
+
+from bot import app as appmod
+from bot import panels
+from bot.app import COMMANDS, OWNER_COMMANDS, PANEL_NAMES, App, Pending, cmd_pattern, is_renameable
+from bot.config import load_config
+from bot.db import Database
+
+from .conftest import needs_ffmpeg
+from .tgfakes import (
+    FakeCallback, FakeClient, FakeEvent, FakeMessage, dispatch, document_message, flat_buttons, make_file,
+)
+
+OWNER, ADMIN_CFG, ADMIN_DB, STRANGER = 1000001, 1000002, 1000003, 1999999
+LOG = -1001111111111
+EPISODE = "[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234].mkv"
+EPISODE_NEW = "[S01E05] Tokyo Revengers [1080p].mkv"
+
+
+def env_for(tmp_path, **extra):
+    return {
+        "API_ID": "1", "API_HASH": "h", "BOT_TOKEN": "1:t", "OWNER_ID": str(OWNER), "ADMIN_IDS": str(ADMIN_CFG),
+        "LOG_CHANNEL": str(LOG), "TEMP_DIR": str(tmp_path / "work"), "FAST_TRANSFER": "0", "MAX_FILE_MB": "100",
+        **extra,
+    }
+
+
+@pytest.fixture
+async def ctx(tmp_path):
+    cfg = load_config(env_for(tmp_path))
+    db = Database(f"sqlite+aiosqlite:///{tmp_path}/app.db")
+    await db.init()
+    client = FakeClient()
+    app = App(client, cfg, db)
+    app._register()  # setup() minus the queue workers: jobs stay queued so they can be inspected
+    yield SimpleNamespace(app=app, client=client, db=db, cfg=cfg, tmp=tmp_path)
+    await app.queue.stop()
+    await db.close()
+
+
+async def say(ctx, sender, text="", **kw):
+    ev = FakeEvent(sender, text, **kw)
+    await dispatch(ctx.client, ev)
+    return ev
+
+
+async def send_doc(ctx, sender, name=EPISODE, size=50 * 1024 * 1024, **kw):
+    ev = FakeEvent(sender, message=document_message(name, size, **kw))
+    await dispatch(ctx.client, ev)
+    return ev
+
+
+async def click(ctx, sender, data, **kw):
+    cb = FakeCallback(sender, data, **kw)
+    await dispatch(ctx.client, cb)
+    return cb
+
+
+async def prefs(ctx, uid=OWNER):
+    return await ctx.db.get_settings(uid)
+
+
+def jpeg(size=(640, 480)):
+    buf = io.BytesIO()
+    Image.new("RGB", size, (200, 30, 30)).save(buf, "JPEG")
+    return buf.getvalue()
+
+
+def data_of(buttons):
+    return [d for _l, d in flat_buttons(buttons)]
+
+
+# ---------------------------------------------------------------------------
+# access control & routing
+# ---------------------------------------------------------------------------
+
+
+async def test_strangers_are_ignored_and_reported_once(ctx):
+    for text in ("/start", "hello", "/rename x", "/cancel"):
+        assert (await say(ctx, STRANGER, text)).out == []
+    assert (await send_doc(ctx, STRANGER)).out == []
+    cb = await click(ctx, STRANGER, "m:home")
+    assert cb.edits == [] and not ctx.app.queue.jobs
+    reports = [t for chat, t, _kw in ctx.client.sent if chat == LOG]
+    assert len(reports) == 1 and str(STRANGER) in reports[0] and f"/addadmin {STRANGER}" in reports[0]
+
+
+async def test_a_plain_message_from_a_stranger_is_also_reported(ctx):
+    await say(ctx, STRANGER, "hi there")
+    assert len([1 for chat, _t, _k in ctx.client.sent if chat == LOG]) == 1
+
+
+async def test_owner_and_admins_from_config_and_db_are_allowed(ctx):
+    await ctx.db.add_admin(ADMIN_DB, OWNER)
+    ctx.app.admins |= set(await ctx.db.list_admins())
+    for uid in (OWNER, ADMIN_CFG, ADMIN_DB):
+        assert (await say(ctx, uid, "/help")).out, uid
+    assert ctx.client.sent == []  # nobody was reported
+
+
+async def test_group_chats_are_ignored(ctx):
+    assert (await say(ctx, OWNER, "/start", private=False)).out == []
+    assert (await say(ctx, STRANGER, "/start", private=False)).out == []
+    assert ctx.client.sent == []
+
+
+async def test_owner_only_commands_are_refused_for_admins(ctx):
+    for text in ("/addadmin 123456", "/deladmin 123456", "/admins"):
+        ev = await say(ctx, ADMIN_CFG, text)
+        assert ev.texts == ["⛔ Only the owner can do that."], text
+    assert 123456 not in ctx.app.admins
+    assert (await click(ctx, ADMIN_CFG, "m:admin")).alerts == ["Owner only."]
+    assert (await click(ctx, ADMIN_CFG, "adm:stats")).alerts == ["Owner only."]
+    assert (await click(ctx, ADMIN_CFG, "adm:clear")).alerts == ["Owner only."]
+    assert ctx.client.sent == []
+
+
+def test_cmd_pattern_accepts_args_bot_suffix_and_any_case():
+    p = cmd_pattern("rename")
+    assert p.match("/rename New Name").group(1) == "New Name"
+    assert p.match("/rename@MyBot New Name").group(1) == "New Name"
+    assert p.match("/RENAME").group(1) is None
+    assert p.match("/rename\nline one\nline two").group(1) == "line one\nline two"
+    assert not p.match("/renamex") and not p.match("rename") and not p.match("/re")
+
+
+def test_every_menu_command_has_a_handler_and_telegram_compatible_text(ctx):
+    table = ctx.app._command_table()
+    for name, description in COMMANDS:
+        assert name in table
+        assert name.islower() and 1 <= len(name) <= 32
+        assert 3 <= len(description) <= 256
+    assert OWNER_COMMANDS <= set(table)
+    assert {"settitle", "setauthor", "setartist", "setaudio", "setsubtitle", "setvideo", "removewords", "setchannel"} <= set(table)
+    assert dict(COMMANDS)["status"] == "Show basic bot uptime, ping, and version information."
+    assert dict(COMMANDS)["stats"] == "Show detailed system stats such as users, CPU, RAM, and disk usage."
+
+
+async def test_setup_registers_command_menu_loads_admins_and_survives_log_channel_errors(tmp_path):
+    cfg = load_config(env_for(tmp_path))
+    db = Database(f"sqlite+aiosqlite:///{tmp_path}/setup.db")
+    await db.init()
+    await db.add_admin(ADMIN_DB, OWNER)
+    client = FakeClient()
+    client.bad_entities.add(LOG)
+    app = App(client, cfg, db)
+    await app.setup()
+    try:
+        assert client.parse_mode == "html"
+        assert ADMIN_DB in app.admins and ADMIN_CFG in app.admins
+        (request,) = [r for r in client.requests if isinstance(r, functions.bots.SetBotCommandsRequest)]
+        assert [c.command for c in request.commands] == [c for c, _ in COMMANDS]
+        assert len(client.handlers) > 10
+    finally:
+        await app.shutdown()
+        await db.close()
+
+
+# ---------------------------------------------------------------------------
+# /start, /help and the one-line settings commands
+# ---------------------------------------------------------------------------
+
+
+async def test_start_shows_the_home_panel_and_hides_admin_from_admins(ctx):
+    ev = await say(ctx, OWNER, "/start")
+    text, buttons, kw = ev.out[0]
+    assert "Auto Rename Bot" in text and kw["parse_mode"] == "html"
+    assert {"m:rename", "m:cap", "m:meta", "m:ftype", "m:help", "m:admin"} <= set(data_of(buttons))
+    assert "m:admin" not in data_of((await say(ctx, ADMIN_CFG, "/start")).out[0][1])
+
+
+@pytest.mark.parametrize("text", ["/start payload", "/start@SomeBot", "/START"])
+async def test_start_variants(ctx, text):
+    assert (await say(ctx, OWNER, text)).out
+
+
+async def test_start_image_is_sent_as_a_photo_with_the_panel_as_caption(ctx):
+    ctx.app.cfg = dataclasses.replace(ctx.cfg, start_image="https://example.com/banner.jpg")
+    ev = await say(ctx, OWNER, "/start")
+    assert ev.out == []
+    (chat, file, kw), = ctx.client.files
+    assert (chat, file) == (OWNER, "https://example.com/banner.jpg")
+    assert "Auto Rename Bot" in kw["caption"] and kw["buttons"] and kw["parse_mode"] == "html"
+    ctx.client.fail_send_file = True  # a broken banner must not break /start
+    ev = await say(ctx, OWNER, "/start")
+    assert "Auto Rename Bot" in ev.texts[0]
+
+
+async def test_start_and_help(ctx):
+    ctx.app.pending[OWNER] = Pending("template", OWNER, 1, "rename", False, time.time() + 100)
+    await say(ctx, OWNER, "/start")
+    assert OWNER not in ctx.app.pending
+    ev = await say(ctx, OWNER, "/help")
+    assert "How to use" in ev.texts[0] and "x:close" in data_of(ev.out[0][1])
+
+
+async def test_mode_command(ctx):
+    ev = await say(ctx, OWNER, "/mode caption")
+    assert (await prefs(ctx))["mode"] == "caption" and "CAPTION" in ev.texts[0]
+    for text in ("/mode", "/mode nonsense"):
+        ev = await say(ctx, OWNER, text)
+        assert "RENAME MODE" in ev.texts[0] and "set:mode:filename" in data_of(ev.out[0][1])
+    assert (await prefs(ctx))["mode"] == "caption"
+    await say(ctx, OWNER, "/mode FILENAME")
+    assert (await prefs(ctx))["mode"] == "filename"
+
+
+async def test_filetype_command_and_aliases(ctx):
+    for arg, expected in (("video", "video"), ("audio", "audio"), ("document", "document"), ("original", "same"),
+                          ("doc", "document"), ("file", "document"), ("same", "same")):
+        await say(ctx, OWNER, f"/filetype {arg}")
+        assert (await prefs(ctx))["file_type"] == expected, arg
+    ev = await say(ctx, OWNER, "/filetype")
+    assert "FILE TYPE" in ev.texts[0]
+    ev = await say(ctx, OWNER, "/filetype bogus")
+    assert "FILE TYPE" in ev.texts[0] and (await prefs(ctx))["file_type"] == "same"
+
+
+async def test_metadata_command(ctx):
+    await say(ctx, OWNER, "/metadata on")
+    assert (await prefs(ctx))["metadata_on"] is True
+    await say(ctx, OWNER, "/metadata off")
+    assert (await prefs(ctx))["metadata_on"] is False
+    ev = await say(ctx, OWNER, "/metadata")
+    assert "currently: Off" in ev.texts[0]
+
+
+async def test_template_caption_and_removewords_commands(ctx):
+    ev = await say(ctx, OWNER, "/template [S{season}E{episode}] {title} [{quality}]")
+    assert "Template saved" in ev.texts[0]
+    assert (await prefs(ctx))["template"] == "[S{season}E{episode}] {title} [{quality}]"
+    assert "Current template" in (await say(ctx, OWNER, "/template")).texts[0]
+
+    await say(ctx, OWNER, "/caption <b>{filename}</b> {size}")
+    assert (await prefs(ctx))["caption"] == "<b>{filename}</b> {size}"
+    assert "Current caption template" in (await say(ctx, OWNER, "/caption")).texts[0]
+
+    await say(ctx, OWNER, "/removewords @Chan, [Group]")
+    assert (await prefs(ctx))["remove_words"] == ["@Chan", "[Group]"]
+    assert "@Chan, [Group]" in (await say(ctx, OWNER, "/removewords")).texts[0]
+    await say(ctx, OWNER, "/removewords off")
+    assert (await prefs(ctx))["remove_words"] == []
+
+
+async def test_settings_are_per_user(ctx):
+    await say(ctx, OWNER, "/mode caption")
+    await say(ctx, ADMIN_CFG, "/filetype audio")
+    assert (await prefs(ctx, OWNER))["mode"] == "caption" and (await prefs(ctx, OWNER))["file_type"] == "same"
+    assert (await prefs(ctx, ADMIN_CFG))["mode"] == "filename" and (await prefs(ctx, ADMIN_CFG))["file_type"] == "audio"
+
+
+@pytest.mark.parametrize("command,field", [
+    ("settitle", "title"), ("setauthor", "author"), ("setartist", "artist"),
+    ("setaudio", "audio"), ("setsubtitle", "subtitle"), ("setvideo", "video"),
+])
+async def test_metadata_field_commands(ctx, command, field):
+    ev = await say(ctx, OWNER, f"/{command} {{lang}} Value")
+    assert (await prefs(ctx))["meta"][field] == "{lang} Value" and "✅" in ev.texts[0]
+    assert "{lang} Value" in (await say(ctx, OWNER, f"/{command}")).texts[0]
+    await say(ctx, OWNER, f"/{command} off")
+    assert (await prefs(ctx))["meta"][field] == ""
+
+
+async def test_keepaudio_by_language_and_by_number(ctx):
+    ev = await say(ctx, OWNER, "/keepaudio English Japanese")
+    s = await prefs(ctx)
+    assert s["keep_audio"] == ["english", "japanese"] and s["metadata_on"] is True and "turned it On" in ev.texts[0]
+    await say(ctx, OWNER, "/keepaudio 2 1")
+    assert (await prefs(ctx))["keep_audio"] == ["2", "1"]
+    assert "2, 1" in (await say(ctx, OWNER, "/keepaudio")).texts[0]
+    await say(ctx, OWNER, "/keepaudio off")
+    assert (await prefs(ctx))["keep_audio"] == []
+    ev = await say(ctx, OWNER, "/keepaudio 0")
+    assert ev.texts[0].startswith("❌")
+
+
+async def test_keepsubtitle_is_independent_of_keepaudio(ctx):
+    await say(ctx, OWNER, "/keepaudio 2 1")
+    await say(ctx, OWNER, "/keepsubtitle english")
+    s = await prefs(ctx)
+    assert s["keep_audio"] == ["2", "1"] and s["keep_subtitle"] == ["english"]
+    await say(ctx, OWNER, "/keepsubtitle off")
+    s = await prefs(ctx)
+    assert s["keep_audio"] == ["2", "1"] and s["keep_subtitle"] == []
+
+
+async def test_setchannel(ctx):
+    assert "not set" in (await say(ctx, OWNER, "/setchannel")).texts[0]
+    ev = await say(ctx, OWNER, "/setchannel -1002223334445")
+    assert (await prefs(ctx))["target_channel"] == -1002223334445 and "✅" in ev.texts[0]
+    ev = await say(ctx, OWNER, "/setchannel @name")
+    assert ev.texts[0].startswith("❌") and (await prefs(ctx))["target_channel"] == -1002223334445
+    ctx.client.bad_entities.add(-1005556667778)
+    ev = await say(ctx, OWNER, "/setchannel -1005556667778")
+    assert "can't access" in ev.texts[0] and (await prefs(ctx))["target_channel"] == -1002223334445
+    await say(ctx, OWNER, "/setchannel off")
+    assert (await prefs(ctx))["target_channel"] is None
+
+
+# ---------------------------------------------------------------------------
+# thumbnails
+# ---------------------------------------------------------------------------
+
+
+async def test_photo_becomes_the_thumbnail_and_can_be_viewed_and_deleted(ctx):
+    ev = FakeEvent(OWNER, message=FakeMessage("", mid=20, photo=True), photo_bytes=jpeg())
+    await dispatch(ctx.client, ev)
+    assert "Thumbnail saved" in ev.texts[0] and "th:rm" in data_of(ev.out[0][1])
+    stored = await ctx.db.get_thumb(OWNER)
+    assert stored[:2] == b"\xff\xd8"
+    assert await ctx.db.get_thumb(ADMIN_CFG) is None  # per user
+
+    await say(ctx, OWNER, "/thumb")
+    (chat, file, kw), = ctx.client.files
+    assert chat == OWNER and file.read() == stored and "th:rm" in data_of(kw["buttons"])
+
+    assert "deleted" in (await say(ctx, OWNER, "/delthumb")).texts[0]
+    assert await ctx.db.get_thumb(OWNER) is None
+    assert "no thumbnail" in (await say(ctx, OWNER, "/delthumb")).texts[0]
+    assert "no thumbnail" in (await say(ctx, OWNER, "/thumb")).texts[0]
+
+
+async def test_unreadable_photos_are_reported(ctx):
+    ev = FakeEvent(OWNER, message=FakeMessage("", photo=True), photo_bytes=b"not an image")
+    await dispatch(ctx.client, ev)
+    assert "couldn't read" in ev.texts[0]
+    ev = FakeEvent(OWNER, message=FakeMessage("", photo=True), photo_bytes=None)
+    await dispatch(ctx.client, ev)
+    assert "couldn't download" in ev.texts[0]
+    assert await ctx.db.get_thumb(OWNER) is None
+    stranger = FakeEvent(STRANGER, message=FakeMessage("", photo=True), photo_bytes=jpeg())
+    await dispatch(ctx.client, stranger)
+    assert stranger.out == [] and await ctx.db.get_thumb(STRANGER) is None
+
+
+async def test_thumbnail_buttons(ctx):
+    cb = await click(ctx, OWNER, "th:view")
+    assert cb.alerts and "no thumbnail" in cb.alerts[0]
+    await ctx.db.set_thumb(OWNER, b"\xff\xd8thumb")
+    cb = await click(ctx, OWNER, "th:view")
+    assert cb.answers == [(None, False)] and len(ctx.client.files) == 1
+
+    cb = await click(ctx, OWNER, "th:del")  # inside the Caption & Thumbnail panel
+    assert await ctx.db.get_thumb(OWNER) is None and "CAPTION" in cb.edits[-1][0] and "none" in cb.edits[-1][0]
+    assert cb.toasts == ["Thumbnail deleted."] and not cb.deleted
+
+    await ctx.db.set_thumb(OWNER, b"\xff\xd8thumb")
+    cb = await click(ctx, OWNER, "th:rm")  # under a standalone thumbnail message
+    assert await ctx.db.get_thumb(OWNER) is None and cb.deleted and cb.edits == []
+
+
+# ---------------------------------------------------------------------------
+# renaming
+# ---------------------------------------------------------------------------
+
+
+async def test_a_file_is_queued_with_the_template_name_and_a_cancel_button(ctx):
+    ev = await send_doc(ctx, OWNER, mid=10)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.new_name == EPISODE_NEW and (job.user_id, job.chat_id, job.msg_id) == (OWNER, OWNER, 10)
+    assert job.file_name == EPISODE and job.size == 50 * 1024 * 1024 and not job.manual and job.state == "queued"
+    text, buttons, kw = ev.out[0]
+    assert "Queued" in text and "starting soon" in text and EPISODE_NEW in text
+    assert flat_buttons(buttons) == [("✖ Cancel", f"job:x:{job.id}")]
+    assert job.status_msg is not None
+
+    ev = await send_doc(ctx, OWNER, "Another.File.mp4", mid=11)
+    assert "1 ahead of it" in ev.texts[0]
+
+
+async def test_caption_mode_reads_the_caption(ctx):
+    await say(ctx, OWNER, "/mode caption")
+    await send_doc(ctx, OWNER, "xyz123.mkv", caption="Tokyo Revengers S02E07 720p", mid=12)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.new_name.endswith(".mkv") and "Tokyo Revengers" in job.new_name and "S02E07" in job.new_name
+
+
+async def test_remove_words_are_applied_to_the_new_name(ctx):
+    await say(ctx, OWNER, "/removewords @SomeChannel")
+    await send_doc(ctx, OWNER, "[@SomeChannel] Tokyo Revengers - 05 (1080p).mkv")
+    (job,) = ctx.app.queue.jobs.values()
+    assert "SomeChannel" not in job.new_name and "Tokyo Revengers" in job.new_name
+
+
+async def test_rename_command_uses_the_given_name_and_keeps_the_extension(ctx):
+    reply = document_message("old.name.mkv", 10 * 1024 * 1024, mid=33)
+    ev = await say(ctx, OWNER, "/rename My Custom Name", reply=reply, mid=34)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.new_name == "My Custom Name.mkv" and job.manual and job.msg_id == 33
+    assert "My Custom Name.mkv" in ev.texts[0]
+
+    ev = await say(ctx, OWNER, "/rename Movie.2024.mp4", reply=reply, mid=35)  # a typed extension never wins
+    assert sorted(j.new_name for j in ctx.app.queue.jobs.values())[1].endswith(".mkv")
+
+
+async def test_rename_usage_messages(ctx):
+    for kwargs in (
+        {"reply": None},                                              # no reply
+        {"reply": FakeMessage("just text", mid=5)},                   # reply to text
+        {"reply": FakeMessage("", mid=6, file=make_file("s.webp"), sticker=True)},
+    ):
+        ev = await say(ctx, OWNER, "/rename New Name", **kwargs)
+        assert "Reply to a file" in ev.texts[0], kwargs
+    ev = await say(ctx, OWNER, "/rename", reply=document_message())  # reply but no name
+    assert "Reply to a file" in ev.texts[0]
+    assert not ctx.app.queue.jobs
+
+
+async def test_oversized_files_are_refused(ctx):
+    ev = await send_doc(ctx, OWNER, size=101 * 1024 * 1024)
+    assert "limit is 100.00 MB" in ev.texts[0] and not ctx.app.queue.jobs
+    ev = await send_doc(ctx, OWNER, size=100 * 1024 * 1024)  # exactly at the limit is fine
+    assert "Queued" in ev.texts[0]
+
+
+async def test_stickers_voice_notes_and_gifs_are_not_renamed(ctx):
+    for flags in ({"sticker": True}, {"voice": True}, {"gif": True}, {"video_note": True}):
+        ev = FakeEvent(OWNER, message=FakeMessage("", file=make_file("x.webm"), **flags))
+        await dispatch(ctx.client, ev)
+        assert ev.out == [], flags
+    assert not ctx.app.queue.jobs
+    assert is_renameable(document_message()) and not is_renameable(FakeMessage("text"))
+
+
+async def test_a_file_without_a_name_gets_a_generated_one(ctx):
+    ev = FakeEvent(OWNER, message=FakeMessage("", mid=77, file=make_file(None, 1024, "video/mp4", ext=".mp4"), video=True))
+    await dispatch(ctx.client, ev)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.file_name == "video_77.mp4" and job.new_name.endswith(".mp4")
+
+
+# ---------------------------------------------------------------------------
+# queue and cancel
+# ---------------------------------------------------------------------------
+
+
+async def test_queue_listing_is_scoped_to_the_user_unless_owner(ctx):
+    assert "Nothing in the queue" in (await say(ctx, OWNER, "/queue")).texts[0]
+    await send_doc(ctx, OWNER, "Owner.File.mkv")
+    await send_doc(ctx, ADMIN_CFG, "Admin.File.mkv")
+    admin_view = (await say(ctx, ADMIN_CFG, "/queue")).texts[0]
+    assert "Admin File" in admin_view and "Owner File" not in admin_view
+    owner_view = (await say(ctx, OWNER, "/queue")).texts[0]
+    assert "Admin File" in owner_view and "Owner File" in owner_view and str(ADMIN_CFG) in owner_view
+
+
+async def test_cancel_commands_respect_ownership(ctx):
+    await send_doc(ctx, OWNER, "Owner.File.mkv")      # job 1
+    await send_doc(ctx, ADMIN_CFG, "Admin.File.mkv")  # job 2
+    await send_doc(ctx, ADMIN_CFG, "Admin.Two.mkv")   # job 3
+
+    assert "couldn't find" in (await say(ctx, ADMIN_CFG, "/cancel 1")).texts[0]  # not theirs
+    assert ctx.app.queue.jobs[1].state == "queued"
+    assert "Cancelling 2 job(s)" in (await say(ctx, ADMIN_CFG, "/cancel all")).texts[0]  # only their own
+    assert set(ctx.app.queue.jobs) == {1}
+    assert "no active jobs" in (await say(ctx, ADMIN_CFG, "/cancel")).texts[0]
+
+    await send_doc(ctx, ADMIN_CFG, "Admin.Three.mkv")  # job 4
+    assert "Cancelling 2 job(s)" in (await say(ctx, OWNER, "/cancel all")).texts[0]  # owner: jobs 1 and 4
+    assert not ctx.app.queue.jobs
+
+
+async def test_cancelled_queued_jobs_update_their_status_message(ctx):
+    await send_doc(ctx, OWNER)
+    await say(ctx, OWNER, "/cancel 1")
+    for _ in range(5):
+        await asyncio.sleep(0)
+    (entity, text, kw), = ctx.client.edited
+    assert "Cancelled" in text and kw["buttons"] is None
+
+
+async def test_cancel_button_on_a_queued_file(ctx):
+    await send_doc(ctx, OWNER)
+    await send_doc(ctx, OWNER, "Second.mkv")
+    cb = await click(ctx, ADMIN_CFG, "job:x:1")  # somebody else's job
+    assert cb.toasts == ["That job already finished."] and 1 in ctx.app.queue.jobs
+    cb = await click(ctx, OWNER, "job:x:1")
+    assert cb.toasts == ["Cancelling…"] and 1 not in ctx.app.queue.jobs
+    assert (await click(ctx, OWNER, "job:x:1")).toasts == ["That job already finished."]
+    admin_doc = await send_doc(ctx, ADMIN_CFG, "Admin.mkv")
+    assert admin_doc.out
+    assert (await click(ctx, OWNER, "job:x:3")).toasts == ["Cancelling…"]  # the owner may cancel anything
+
+
+async def test_cancel_clears_a_pending_prompt_first(ctx):
+    ctx.app.pending[OWNER] = Pending("template", OWNER, 1, "rename", False, time.time() + 100)
+    await send_doc(ctx, OWNER)
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "nothing was changed" in ev.texts[0] and OWNER not in ctx.app.pending
+    assert ctx.app.queue.jobs  # the job is untouched
+    assert "Cancelling 1 job(s)" in (await say(ctx, OWNER, "/cancel")).texts[0]
+
+
+# ---------------------------------------------------------------------------
+# admin management, status and stats
+# ---------------------------------------------------------------------------
+
+
+async def test_owner_manages_admins(ctx):
+    ev = await say(ctx, OWNER, "/addadmin 555555")
+    assert "can now use the bot" in ev.texts[0] and 555555 in ctx.app.admins
+    assert 555555 in await ctx.db.list_admins()
+    assert (await say(ctx, 555555, "/help")).out  # works immediately
+    assert "already have access" in (await say(ctx, OWNER, "/addadmin 555555")).texts[0]
+    assert "already have access" in (await say(ctx, OWNER, f"/addadmin {OWNER}")).texts[0]
+    assert "already have access" in (await say(ctx, OWNER, f"/addadmin {ADMIN_CFG}")).texts[0]
+    for bad in ("/addadmin", "/addadmin abc", "/addadmin 12", "/addadmin @user"):
+        assert "Usage" in (await say(ctx, OWNER, bad)).texts[0], bad
+
+    listing = (await say(ctx, OWNER, "/admins")).texts[0]
+    assert str(OWNER) in listing and "555555" in listing and str(ADMIN_CFG) in listing
+
+    assert "was removed" in (await say(ctx, OWNER, "/deladmin 555555")).texts[0]
+    assert 555555 not in ctx.app.admins and 555555 not in await ctx.db.list_admins()
+    assert (await say(ctx, 555555, "/help")).out == []  # access gone
+    assert "wasn't in the list" in (await say(ctx, OWNER, "/deladmin 555555")).texts[0]
+    assert "ADMIN_IDS" in (await say(ctx, OWNER, f"/deladmin {ADMIN_CFG}")).texts[0]
+    assert ADMIN_CFG in ctx.app.admins
+    assert "Usage" in (await say(ctx, OWNER, "/deladmin")).texts[0]
+
+
+async def test_status_pings_telegram_and_reports_version_info(ctx):
+    ev = await say(ctx, OWNER, "/status")
+    text = ev.texts[0]
+    assert "Bot status" in text and "Uptime" in text and "Ping" in text and "Version" in text and "Telethon" in text
+    assert any(isinstance(r, functions.PingRequest) for r in ctx.client.requests)
+    assert (await say(ctx, ADMIN_CFG, "/status")).out  # admins may use it too
+
+
+async def test_status_survives_a_failed_ping(ctx):
+    async def broken(request):
+        raise ConnectionError("offline")
+
+    ctx.client.__class__ = type("Broken", (FakeClient,), {"__call__": lambda self, request: broken(request)})
+    assert "n/a" in (await say(ctx, OWNER, "/status")).texts[0]
+
+
+async def test_stats_reports_users_files_and_system_usage(ctx):
+    await say(ctx, ADMIN_CFG, "/help")
+    await ctx.db.record_job(OWNER, 3 * 1024 ** 3)
+    text = (await say(ctx, OWNER, "/stats")).texts[0]
+    for expected in ("System stats", "Users", "Files renamed", "3.00 GB", "Queue", "CPU", "RAM", "Disk"):
+        assert expected in text, expected
+    assert (await say(ctx, ADMIN_CFG, "/stats")).out
+    assert (await say(ctx, STRANGER, "/stats")).out == []
+
+
+# ---------------------------------------------------------------------------
+# /tracks
+# ---------------------------------------------------------------------------
+
+
+async def test_tracks_needs_a_reply_to_a_file(ctx):
+    for reply in (None, FakeMessage("text", mid=3)):
+        assert "Reply to a video or audio file" in (await say(ctx, OWNER, "/tracks", reply=reply)).texts[0]
+
+
+@needs_ffmpeg
+async def test_tracks_lists_numbered_audio_and_subtitles_and_cleans_up(ctx, media_dir, monkeypatch):
+    calls = []
+
+    async def fake_download(client, message, dest, **kw):
+        calls.append(kw)
+        shutil.copy(media_dir / "sample.mkv", dest)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    reply = document_message("Show.mkv", (media_dir / "sample.mkv").stat().st_size, mid=33)
+    ev = await say(ctx, OWNER, "/tracks", reply=reply, mid=34)
+    assert ev.texts == ["🔎 Reading the tracks…"]
+    (status, text, kw), = ctx.client.edited
+    assert status.id == 1001 and "Show.mkv" in text
+    assert "Audio" in text and "Subtitles" in text and "Japanese" in text and "English" in text and "use these numbers" in text
+    assert len(calls) == 1 and calls[0]["max_bytes"] == appmod.TRACKS_PROBE_BYTES
+    assert not list(Path(ctx.cfg.temp_dir).glob("tracks*"))
+
+
+@needs_ffmpeg
+async def test_tracks_downloads_the_whole_file_when_the_start_is_not_enough(ctx, media_dir, monkeypatch):
+    calls = []
+
+    async def fake_download(client, message, dest, **kw):
+        calls.append(kw)
+        if "max_bytes" in kw:
+            Path(dest).write_bytes(b"\x00" * 4096)  # e.g. an mp4 whose index is at the end
+        else:
+            shutil.copy(media_dir / "sample.mp4", dest)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    reply = document_message("Show.mp4", 40 * 1024 * 1024, mid=33)
+    await say(ctx, OWNER, "/tracks", reply=reply, mid=34)
+    assert len(calls) == 2 and "max_bytes" not in calls[1]
+    assert "Audio" in ctx.client.edited[-1][1] and "needs the whole file" in ctx.client.edited[0][1]
+
+
+@needs_ffmpeg
+async def test_tracks_gives_up_gracefully(ctx, monkeypatch):
+    async def junk_download(client, message, dest, **kw):
+        Path(dest).write_bytes(b"\x00" * 4096)
+
+    monkeypatch.setattr(appmod.transfer, "download", junk_download)
+    for size in (2 * 1024 * 1024, 900 * 1024 * 1024):  # small file / too big for a full download
+        ctx.client.edited.clear()
+        reply = document_message("Bad.mkv", size, mid=33)
+        await say(ctx, OWNER, "/tracks", reply=reply, mid=34)
+        assert "couldn't read any tracks" in ctx.client.edited[-1][1], size
+    assert not list(Path(ctx.cfg.temp_dir).glob("tracks*"))
+
+
+# ---------------------------------------------------------------------------
+# menus (callbacks)
+# ---------------------------------------------------------------------------
+
+
+async def test_menu_navigation_edits_the_message_in_place(ctx):
+    cb = await click(ctx, OWNER, "m:meta")
+    text, buttons = cb.edits[-1]
+    assert "metadata is currently" in text and "m:tool" in data_of(buttons)
+    assert cb.answers == [(None, False)]
+    cb = await click(ctx, OWNER, "m:tool")
+    assert "TOOL" in cb.edits[-1][0] and "m:meta" in data_of(cb.edits[-1][1])
+    cb = await click(ctx, OWNER, "m:home")
+    assert "Auto Rename Bot" in cb.edits[-1][0]
+    cb = await click(ctx, OWNER, "m:admin")
+    assert "ADMIN" in cb.edits[-1][0]
+    cb = await click(ctx, OWNER, "m:bogus")
+    assert cb.edits == [] and cb.answers == [(None, False)]
+
+
+async def test_toggles_update_settings_and_refresh_the_panel(ctx):
+    cb = await click(ctx, OWNER, "set:mode:caption")
+    assert (await prefs(ctx))["mode"] == "caption" and cb.toasts == ["Mode: Caption"]
+    assert "Caption ✅" in [label for label, _d in flat_buttons(cb.edits[-1][1])]
+    cb = await click(ctx, OWNER, "set:ftype:video")
+    assert (await prefs(ctx))["file_type"] == "video" and cb.toasts == ["File type: Video"]
+    cb = await click(ctx, OWNER, "set:ftype:same")
+    assert cb.toasts == ["File type: Same as original"]
+    cb = await click(ctx, OWNER, "set:meta:on")
+    assert (await prefs(ctx))["metadata_on"] is True and cb.toasts == ["Metadata ON"]
+    await click(ctx, OWNER, "set:meta:off")
+    assert (await prefs(ctx))["metadata_on"] is False
+
+    before = await prefs(ctx)
+    for junk in ("set:mode:bogus", "set:nothing:x", "set:ftype:zip", "set:meta:maybe", "set:mode"):
+        cb = await click(ctx, OWNER, junk)
+        assert cb.edits == [] and cb.answers == [(None, False)], junk
+    assert await prefs(ctx) == before
+
+
+async def test_clear_buttons(ctx):
+    await say(ctx, OWNER, "/caption custom {filename}")
+    cb = await click(ctx, OWNER, "clr:caption")
+    assert (await prefs(ctx))["caption"] == "{filename}" and "CAPTION" in cb.edits[-1][0]
+    await say(ctx, OWNER, "/keepaudio 2 1")
+    await say(ctx, OWNER, "/keepsubtitle 1")
+    cb = await click(ctx, OWNER, "clr:keep_audio")
+    s = await prefs(ctx)
+    assert s["keep_audio"] == [] and s["keep_subtitle"] == ["1"] and "TOOL" in cb.edits[-1][0]
+    await click(ctx, OWNER, "clr:keep_subtitle")
+    assert (await prefs(ctx))["keep_subtitle"] == []
+    cb = await click(ctx, OWNER, "clr:whatever")
+    assert cb.edits == []
+
+
+async def test_close_deletes_the_message_and_falls_back_to_editing(ctx):
+    ctx.app.pending[OWNER] = Pending("template", OWNER, 1, "rename", False, time.time() + 100)
+    cb = await click(ctx, OWNER, "x:close")
+    assert cb.deleted and OWNER not in ctx.app.pending
+    old = FakeCallback(OWNER, "x:close")
+    old.delete_error = RuntimeError("MESSAGE_DELETE_FORBIDDEN")
+    await dispatch(ctx.client, old)
+    assert old.edits == [("Closed.", None)] and not old.deleted
+
+
+async def test_metadata_help_and_unknown_callbacks(ctx):
+    cb = await click(ctx, OWNER, "help:meta")
+    assert "How to set metadata" in cb.edits[-1][0]
+    for junk in ("", "zzz", "adm", "th:what", "job:x:abc", "in:nope"):
+        cb = await click(ctx, OWNER, junk)
+        assert cb.answers and not cb.alerts, junk
+
+
+async def test_admin_panel_buttons(ctx):
+    await send_doc(ctx, OWNER)
+    await send_doc(ctx, OWNER, "Two.mkv")
+    cb = await click(ctx, OWNER, "adm:stats", chat=OWNER)
+    (chat, text, kw), = ctx.client.sent
+    assert chat == OWNER and "System stats" in text and "2 waiting" in text
+    await click(ctx, OWNER, "adm:status")
+    assert "Bot status" in ctx.client.sent[-1][1]
+    cb = await click(ctx, OWNER, "adm:clear")
+    assert cb.alerts == ["Cancelling 2 job(s)."] and not ctx.app.queue.jobs
+
+
+@pytest.mark.parametrize("panel", sorted(PANEL_NAMES))
+async def test_every_button_of_every_panel_is_handled(ctx, panel):
+    await ctx.db.set_thumb(OWNER, b"\xff\xd8thumb")
+    _text, rows = await ctx.app.panel(OWNER, panel)
+    clicked = 0
+    for row in rows:
+        for _label, data in row:
+            cb = await click(ctx, OWNER, data)
+            assert cb.answers or cb.deleted, (panel, data)
+            assert not any("went wrong" in a for a in cb.alerts), (panel, data)
+            clicked += 1
+    assert clicked >= 1
+
+
+@pytest.mark.parametrize("kind", sorted(panels.PROMPTS))
+async def test_every_prompt_opens_and_cancels(ctx, kind):
+    cb = await click(ctx, OWNER, f"in:{kind}")
+    p = ctx.app.pending[OWNER]
+    assert p.kind == kind and p.back in PANEL_NAMES and not p.is_photo
+    text, buttons = cb.edits[-1]
+    assert text == panels.PROMPTS[kind] and data_of(buttons) == [f"in:cancel:{p.back}"]
+    cb = await click(ctx, OWNER, f"in:cancel:{p.back}")
+    assert OWNER not in ctx.app.pending and cb.toasts == ["Cancelled."] and cb.edits
+
+
+# ---------------------------------------------------------------------------
+# "tap a button, then send the value"
+# ---------------------------------------------------------------------------
+
+
+async def test_template_prompt_flow(ctx):
+    await click(ctx, OWNER, "in:template", msg_id=500)
+    ev = await say(ctx, OWNER, "{title} [{quality}]", mid=60)
+    assert ev.deleted and OWNER not in ctx.app.pending  # the typed value is removed to keep the chat tidy
+    assert (await prefs(ctx))["template"] == "{title} [{quality}]"
+    (chat, text, kw), = ctx.client.edited
+    assert chat == OWNER and kw["message"] == 500 and "Template saved" in text and "RENAME MODE" in text
+    assert "rename" == "rename" and "set:mode:filename" in data_of(kw["buttons"])
+
+
+async def test_keep_audio_prompt_flow_enables_metadata_and_returns_to_the_tool_panel(ctx):
+    await click(ctx, OWNER, "in:keep_audio")
+    await say(ctx, OWNER, "English Japanese")
+    s = await prefs(ctx)
+    assert s["keep_audio"] == ["english", "japanese"] and s["metadata_on"] is True
+    (chat, text, kw), = ctx.client.edited
+    assert "TOOL" in text and "English, Japanese" in text and "in:keep_subtitle" in data_of(kw["buttons"])
+
+
+async def test_invalid_input_keeps_the_prompt_open(ctx):
+    await click(ctx, OWNER, "in:template")
+    ev = await say(ctx, OWNER, "x" * 300)
+    assert "too long" in ev.texts[0] and "Try again" in ev.texts[0] and not ev.deleted
+    assert OWNER in ctx.app.pending and ctx.client.edited == []
+    ev = await say(ctx, OWNER, "{title}")
+    assert OWNER not in ctx.app.pending and (await prefs(ctx))["template"] == "{title}"
+
+
+async def test_expired_prompts_and_other_users_text_are_ignored(ctx):
+    await click(ctx, OWNER, "in:template")
+    assert (await say(ctx, ADMIN_CFG, "{title}")).out == []  # not their prompt
+    assert OWNER in ctx.app.pending
+    ctx.app.pending[OWNER].expires = time.time() - 1
+    ev = await say(ctx, OWNER, "{title}")
+    assert ev.out == [] and not ev.deleted and OWNER not in ctx.app.pending
+    assert (await prefs(ctx))["template"] != "{title}"
+
+
+async def test_plain_text_without_a_prompt_is_ignored(ctx):
+    ev = await say(ctx, OWNER, "hello bot")
+    assert ev.out == [] and not ev.deleted
+
+
+async def test_prompt_on_a_photo_banner_message_is_flagged_and_long_updates_fall_back(ctx, monkeypatch):
+    await click(ctx, OWNER, "in:mt_title", photo=True)
+    assert ctx.app.pending[OWNER].is_photo and ctx.app.pending[OWNER].back == "meta"
+    monkeypatch.setattr(appmod, "visible_len", lambda _t: 5000)  # pretend it would not fit a caption
+    await say(ctx, OWNER, "My Title")
+    (_chat, text, _kw), = ctx.client.edited
+    assert "Open the menu to see the update" in text and "My Title" in text
+    assert (await prefs(ctx))["meta"]["title"] == "My Title"
+
+
+async def test_when_the_menu_message_cannot_be_edited_a_new_one_is_sent(ctx):
+    async def refuse(*a, **k):
+        raise RuntimeError("MESSAGE_ID_INVALID")
+
+    await click(ctx, OWNER, "in:remove")
+    ctx.client.edit_message = refuse
+    ev = await say(ctx, OWNER, "@Chan, [Group]")
+    assert (await prefs(ctx))["remove_words"] == ["@Chan", "[Group]"]
+    assert "I'll strip" in ev.texts[0] and ev.out[0][1]  # sent as a fresh message with buttons
+
+
+# ---------------------------------------------------------------------------
+# robustness
+# ---------------------------------------------------------------------------
+
+
+async def test_handler_failures_are_reported_to_the_user(ctx, monkeypatch):
+    async def boom(*a, **k):
+        raise RuntimeError("database is down")
+
+    monkeypatch.setattr(ctx.db, "get_settings", boom)
+    ev = await say(ctx, OWNER, "/start")
+    assert ev.texts == ["⚠️ Something went wrong. Please try again."]
+    cb = await click(ctx, OWNER, "m:meta")
+    assert cb.alerts == ["⚠️ Something went wrong."]
+    # and the bot keeps working afterwards
+    monkeypatch.undo()
+    assert "Auto Rename Bot" in (await say(ctx, OWNER, "/start")).texts[0]
+
+
+async def test_a_file_is_handled_by_exactly_one_handler(ctx):
+    ctx.app.pending[OWNER] = Pending("template", OWNER, 1, "rename", False, time.time() + 100)
+    ev = await send_doc(ctx, OWNER)
+    assert len(ev.out) == 1 and "Queued" in ev.texts[0]
+    assert OWNER in ctx.app.pending  # a file does not feed the text prompt

tests/test_db.py

@@ -0,0 +1,76 @@
+import pytest
+
+from bot.db import DEFAULT_SETTINGS, Database, normalize_database_url
+
+
+@pytest.fixture
+async def db(tmp_path):
+    database = Database(f"sqlite+aiosqlite:///{tmp_path}/t.db")
+    await database.init()
+    yield database
+    await database.close()
+
+
+def test_normalize_postgres_urls():
+    url, args = normalize_database_url("postgres://u:p@host/db?sslmode=require&channel_binding=require")
+    assert url == "postgresql+asyncpg://u:p@host/db"
+    assert args == {"ssl": "require"}
+    url, args = normalize_database_url("postgresql://u:p@host/db")
+    assert url == "postgresql+asyncpg://u:p@host/db" and args == {}
+    url, args = normalize_database_url("sqlite+aiosqlite:///x.db")
+    assert url == "sqlite+aiosqlite:///x.db" and args == {}
+
+
+async def test_defaults_and_update_roundtrip(db):
+    s = await db.get_settings(1)
+    assert s == DEFAULT_SETTINGS
+    s["mode"] = "tampered"  # returned copy must not leak into the cache
+    assert (await db.get_settings(1))["mode"] == "filename"
+
+    await db.update_settings(1, mode="caption", keep_audio=["2", "1"], meta={"title": "Hello"})
+    await db.update_settings(1, meta={"author": "me"})
+    # a fresh Database instance proves the values were persisted, not just cached
+    other = Database(db.url)
+    s2 = await other.get_settings(1)
+    assert s2["mode"] == "caption"
+    assert s2["keep_audio"] == ["2", "1"]
+    assert s2["meta"]["title"] == "Hello" and s2["meta"]["author"] == "me" and s2["meta"]["artist"] == ""
+    await other.close()
+
+
+async def test_unknown_setting_rejected(db):
+    with pytest.raises(KeyError):
+        await db.update_settings(1, nope=1)
+
+
+async def test_thumb_and_stats(db):
+    assert not await db.has_thumb(5)
+    await db.set_thumb(5, b"\xff\xd8jpeg")
+    assert await db.has_thumb(5)
+    assert await db.get_thumb(5) == b"\xff\xd8jpeg"
+    await db.set_thumb(5, None)
+    assert not await db.has_thumb(5)
+    assert await db.get_thumb(5) is None
+
+    await db.record_job(5, 1000)
+    await db.record_job(5, 24)
+    await db.get_settings(6)
+    assert await db.count_users() == 2
+    assert await db.totals() == (2, 1024)
+
+
+async def test_admins_and_kv(db):
+    assert await db.add_admin(10, 1) is True
+    assert await db.add_admin(10, 1) is False
+    assert await db.add_admin(11, 1) is True
+    assert sorted(await db.list_admins()) == [10, 11]
+    assert await db.del_admin(10) is True
+    assert await db.del_admin(10) is False
+    assert await db.list_admins() == [11]
+
+    assert await db.kv_get("session") is None
+    await db.kv_set("session", "abc")
+    await db.kv_set("session", "def")
+    assert await db.kv_get("session") == "def"
+    await db.kv_delete("session")
+    assert await db.kv_get("session") is None

tests/test_fasttransfer.py

@@ -0,0 +1,335 @@
+import asyncio
+import random
+
+import pytest
+
+from bot import fasttransfer as ft
+from bot.errors import Cancelled
+
+
+@pytest.fixture(autouse=True)
+def fast_retries(monkeypatch):
+    monkeypatch.setattr(ft, "RETRY_BASE_DELAY", 0.0)
+
+
+class FakeTransport:
+    """Serves bytes from memory and records uploaded parts."""
+
+    def __init__(self, blob=b"", *, fail_first=0, jitter=True, short_once=False, fatal=None, store=None, hang_after=None):
+        self.blob = blob
+        self.fail_first = fail_first
+        self.jitter = jitter
+        self.short_once = short_once
+        self.fatal = fatal
+        self.calls = 0
+        self.closed = False
+        self.store = store if store is not None else {}
+        self.hang_after = hang_after
+        self.requests = []
+
+    async def _tick(self):
+        self.calls += 1
+        if self.jitter:
+            await asyncio.sleep(random.random() * 0.003)
+        if self.fatal:
+            raise self.fatal
+        if self.calls <= self.fail_first:
+            raise ConnectionError("boom")
+        if self.hang_after is not None and self.calls > self.hang_after:
+            await asyncio.sleep(3600)
+
+    async def get_file(self, location, offset, limit):
+        await self._tick()
+        self.requests.append((offset, limit))
+        assert offset % 4096 == 0 and limit % 4096 == 0
+        assert (offset % (1024 * 1024)) + limit <= 1024 * 1024  # Telegram: never cross a 1 MiB boundary
+        data = self.blob[offset: offset + limit]
+        if self.short_once and offset > 0 and len(data) == limit:
+            self.short_once = False
+            return data[: limit // 2]
+        return data
+
+    async def save_part(self, file_id, part, total_parts, data):
+        await self._tick()
+        self.store[part] = (file_id, total_parts, bytes(data))
+
+    async def close(self):
+        self.closed = True
+
+
+def blob_of(n, seed=1):
+    return random.Random(seed).randbytes(n)
+
+
+@pytest.mark.parametrize("size", [0, 1, 4095, 1024 * 1024 - 1, 1024 * 1024, 1024 * 1024 + 1, 5 * 1024 * 1024 + 12345])
+async def test_download_matches_source(tmp_path, size):
+    blob = blob_of(size)
+    transports = [FakeTransport(blob) for _ in range(4)]
+    seen = []
+    n = await ft.download_parts(transports, "loc", size, tmp_path / "out.bin", progress=lambda c, t: seen.append((c, t)))
+    assert n == size
+    assert (tmp_path / "out.bin").read_bytes() == blob
+    if size:
+        assert seen[-1] == (size, size)
+        assert all(t == size for _c, t in seen)
+        assert max(c for c, _t in seen) == size
+
+
+async def test_download_work_is_shared_between_connections(tmp_path):
+    size = 8 * 1024 * 1024
+    blob = blob_of(size)
+    transports = [FakeTransport(blob) for _ in range(4)]
+    await ft.download_parts(transports, "loc", size, tmp_path / "o", progress=None)
+    assert sum(t.calls for t in transports) == 8
+    assert sum(1 for t in transports if t.calls) > 1  # more than one connection did work
+    offsets = sorted(o for t in transports for o, _ in t.requests)
+    assert offsets == [i * 1024 * 1024 for i in range(8)]  # every part exactly once
+
+
+async def test_download_retries_transient_failures(tmp_path):
+    size = 3 * 1024 * 1024 + 7
+    blob = blob_of(size)
+    transports = [FakeTransport(blob, fail_first=2), FakeTransport(blob, fail_first=3)]
+    await ft.download_parts(transports, "loc", size, tmp_path / "o")
+    assert (tmp_path / "o").read_bytes() == blob
+
+
+async def test_download_retries_short_reads(tmp_path):
+    size = 4 * 1024 * 1024
+    blob = blob_of(size)
+    transports = [FakeTransport(blob, short_once=True)]
+    await ft.download_parts(transports, "loc", size, tmp_path / "o")
+    assert (tmp_path / "o").read_bytes() == blob
+
+
+async def test_download_gives_up_after_max_retries(tmp_path):
+    blob = blob_of(2 * 1024 * 1024)
+    transport = FakeTransport(blob, fail_first=10_000)
+    with pytest.raises(ConnectionError):
+        await ft.download_parts([transport], "loc", len(blob), tmp_path / "o")
+    assert transport.calls == ft.MAX_RETRIES + 1
+
+
+async def test_download_fatal_error_is_not_retried(tmp_path):
+    class FileReferenceExpiredError(Exception):
+        pass
+
+    transport = FakeTransport(b"x" * 10, fatal=FileReferenceExpiredError("expired"))
+    with pytest.raises(FileReferenceExpiredError):
+        await ft.download_parts([transport], "loc", 10, tmp_path / "o")
+    assert transport.calls == 1
+
+
+async def test_download_cancel_stops_workers(tmp_path):
+    size = 64 * 1024 * 1024
+    blob = blob_of(1024)
+    cancel = asyncio.Event()
+
+    class SlowTransport(FakeTransport):
+        async def get_file(self, location, offset, limit):
+            await asyncio.sleep(0.01)
+            if offset >= 3 * 1024 * 1024:
+                cancel.set()
+            return b"\0" * limit
+
+    transports = [SlowTransport(blob) for _ in range(4)]
+    with pytest.raises(Cancelled):
+        await ft.download_parts(transports, "loc", size, tmp_path / "o", cancel=cancel)
+
+
+async def test_download_hung_connection_times_out_and_retries(tmp_path, monkeypatch):
+    monkeypatch.setattr(ft, "PART_TIMEOUT", 0.05)
+    blob = blob_of(2 * 1024 * 1024)
+    hanging = FakeTransport(blob, hang_after=0, jitter=False)  # every request hangs
+    with pytest.raises(asyncio.TimeoutError):
+        await ft.download_parts([hanging], "loc", len(blob), tmp_path / "o")
+    assert hanging.calls == ft.MAX_RETRIES + 1
+
+
+async def test_download_partial_max_bytes(tmp_path):
+    size = 6 * 1024 * 1024
+    blob = blob_of(size)
+    limit = int(2.5 * 1024 * 1024)
+    n = await ft.download_parts([FakeTransport(blob), FakeTransport(blob)], "loc", size, tmp_path / "o", max_bytes=limit)
+    assert n == limit
+    assert (tmp_path / "o").read_bytes() == blob[:limit]
+
+
+@pytest.mark.parametrize("size", [1, ft.UPLOAD_PART - 1, ft.UPLOAD_PART, ft.UPLOAD_PART + 1, 3 * 1024 * 1024 + 321])
+async def test_upload_parts_reassemble(tmp_path, size):
+    blob = blob_of(size, seed=7)
+    src = tmp_path / "in.bin"
+    src.write_bytes(blob)
+    store = {}
+    transports = [FakeTransport(store=store) for _ in range(3)]
+    seen = []
+    n = await ft.upload_parts(transports, src, size, 1234, progress=lambda c, t: seen.append((c, t)))
+    expected_parts = -(-size // ft.UPLOAD_PART)
+    assert n == expected_parts
+    assert sorted(store) == list(range(expected_parts))
+    assert all(fid == 1234 and total == expected_parts for fid, total, _d in store.values())
+    sizes = [len(store[i][2]) for i in range(expected_parts)]
+    assert all(s == ft.UPLOAD_PART for s in sizes[:-1])  # every part but the last is full size
+    assert b"".join(store[i][2] for i in range(expected_parts)) == blob
+    assert seen[-1] == (size, size)
+
+
+async def test_upload_retries_and_cancel(tmp_path):
+    blob = blob_of(2 * 1024 * 1024)
+    src = tmp_path / "in.bin"
+    src.write_bytes(blob)
+    store = {}
+    await ft.upload_parts([FakeTransport(store=store, fail_first=2), FakeTransport(store=store)], src, len(blob), 1)
+    assert b"".join(store[i][2] for i in sorted(store)) == blob
+
+    cancel = asyncio.Event()
+    cancel.set()
+    with pytest.raises(Cancelled):
+        await ft.upload_parts([FakeTransport(store={})], src, len(blob), 1, cancel=cancel)
+
+
+async def test_upload_detects_truncated_source(tmp_path):
+    src = tmp_path / "in.bin"
+    src.write_bytes(b"a" * 100)
+    with pytest.raises(IOError):
+        await ft.upload_parts([FakeTransport()], src, 5000, 1)  # claims more bytes than the file holds
+
+
+async def test_close_all_swallows_errors():
+    class Bad:
+        async def close(self):
+            raise RuntimeError("x")
+
+    good = FakeTransport()
+    await ft.close_all([Bad(), good])
+    assert good.closed
+
+
+# ---------------------------------------------------------------------------
+# wrappers / fallback
+# ---------------------------------------------------------------------------
+
+
+class FakeClient:
+    def __init__(self):
+        self.downloaded = []
+        self.uploaded = []
+
+    async def download_media(self, message, file, progress_callback):
+        progress_callback(5, 10)
+        with open(file, "wb") as fh:
+            fh.write(b"stock")
+        self.downloaded.append(file)
+
+    async def upload_file(self, path, file_name, progress_callback):
+        progress_callback(1, 1)
+        self.uploaded.append((path, file_name))
+        return ("stock-input-file", file_name)
+
+    async def iter_download(self, doc, request_size, limit):
+        for _ in range(limit):
+            yield b"z" * request_size
+
+
+class Msg:
+    def __init__(self, document="doc"):
+        self.document = document
+
+
+async def test_download_falls_back_to_stock_when_fast_path_breaks(tmp_path, monkeypatch):
+    async def broken(*a, **k):
+        raise RuntimeError("private API changed")
+
+    monkeypatch.setattr(ft, "fast_download", broken)
+    client = FakeClient()
+    dest = tmp_path / "x.bin"
+    dest.write_bytes(b"partial garbage")
+    await ft.download(client, Msg(), dest, fast=True)
+    assert dest.read_bytes() == b"stock"
+
+
+async def test_download_cancel_is_not_swallowed_by_fallback(tmp_path, monkeypatch):
+    async def cancelled(*a, **k):
+        raise Cancelled()
+
+    monkeypatch.setattr(ft, "fast_download", cancelled)
+    client = FakeClient()
+    with pytest.raises(Cancelled):
+        await ft.download(client, Msg(), tmp_path / "x", fast=True)
+    assert client.downloaded == []
+
+
+async def test_download_stock_progress_callback_can_cancel(tmp_path):
+    cancel = asyncio.Event()
+    cancel.set()
+    with pytest.raises(Cancelled):
+        await ft.download(FakeClient(), Msg(), tmp_path / "x", fast=False, cancel=cancel)
+
+
+async def test_download_partial_fallback_truncates(tmp_path, monkeypatch):
+    async def broken(*a, **k):
+        raise RuntimeError("nope")
+
+    monkeypatch.setattr(ft, "fast_download", broken)
+    dest = tmp_path / "head.bin"
+    await ft.download(FakeClient(), Msg(), dest, fast=True, max_bytes=700 * 1024)
+    assert dest.stat().st_size == 700 * 1024
+
+
+async def test_upload_small_file_uses_stock_upload(tmp_path):
+    src = tmp_path / "small.bin"
+    src.write_bytes(b"x" * 1000)
+    client = FakeClient()
+    result = await ft.fast_upload(client, src, "My Name.mkv")
+    assert result == ("stock-input-file", "My Name.mkv")
+    assert client.uploaded == [(str(src), "My Name.mkv")]
+
+
+async def test_upload_wrapper_falls_back(tmp_path, monkeypatch):
+    async def broken(*a, **k):
+        raise RuntimeError("nope")
+
+    monkeypatch.setattr(ft, "fast_upload", broken)
+    src = tmp_path / "f.bin"
+    src.write_bytes(b"x")
+    client = FakeClient()
+    assert await ft.upload(client, src, "n.mkv", fast=True) == ("stock-input-file", "n.mkv")
+    assert await ft.upload(client, src, "n.mkv", fast=False) == ("stock-input-file", "n.mkv")
+
+
+async def test_big_upload_builds_input_file_big(tmp_path, monkeypatch):
+    size = ft.BIG_FILE_THRESHOLD + 12345
+    src = tmp_path / "big.bin"
+    src.write_bytes(blob_of(size, seed=3))
+    store = {}
+
+    async def fake_open(client, dc_id, connections):
+        assert dc_id == 4 and connections == 3
+        return [FakeTransport(store=store, jitter=False) for _ in range(3)]
+
+    monkeypatch.setattr(ft, "open_transports", fake_open)
+
+    class C(FakeClient):
+        class session:
+            dc_id = 4
+
+    result = await ft.fast_upload(C(), src, "Big.mkv", connections=3)
+    from telethon.tl.types import InputFileBig
+
+    assert isinstance(result, InputFileBig)
+    assert result.name == "Big.mkv" and result.parts == len(store) == -(-size // ft.UPLOAD_PART)
+    assert result.id == next(iter(store.values()))[0]
+    assert b"".join(store[i][2] for i in sorted(store)) == src.read_bytes()
+
+
+async def test_file_helper_without_positional_io(tmp_path):
+    """Windows has no os.pread/os.pwrite: the lock + seek path must work too."""
+    f = ft._File(tmp_path / "w.bin", "w")
+    f._positional = False
+    f.pwrite(b"world", 5)
+    f.pwrite(b"hello", 0)
+    f.close()
+    r = ft._File(tmp_path / "w.bin", "r")
+    r._positional = False
+    assert r.pread(10, 0) == b"helloworld"
+    r.close()

tests/test_media.py

@@ -0,0 +1,321 @@
+import asyncio
+
+import pytest
+
+from bot.errors import Cancelled, MediaError
+from bot.media import (
+    MediaInfo,
+    Stream,
+    apply_plan,
+    build_plan,
+    canonical_lang,
+    format_tracks,
+    make_video_thumbnail,
+    parse_probe,
+    parse_track_tokens,
+    prepare_thumb,
+    probe,
+    resolve_tokens,
+    validate_track_tokens,
+)
+
+from .conftest import ffprobe_json, needs_ffmpeg
+
+
+def audio(index, lang="", title=""):
+    return Stream(index=index, kind="audio", codec="aac", lang=lang, title=title, channels=2)
+
+
+def sub(index, lang="", title=""):
+    return Stream(index=index, kind="subtitle", codec="subrip", lang=lang, title=title)
+
+
+# ---------------------------------------------------------------------------
+# pure logic
+# ---------------------------------------------------------------------------
+
+
+def test_parse_track_tokens():
+    assert parse_track_tokens("English, Japanese") == ["english", "japanese"]
+    assert parse_track_tokens("2 1") == ["2", "1"]
+    assert parse_track_tokens("eng,eng jpn") == ["eng", "jpn"]
+    assert parse_track_tokens("") == []
+
+
+def test_validate_track_tokens():
+    assert validate_track_tokens(["2", "english", "pt-br"]) is None
+    assert validate_track_tokens(["0"]) is not None
+    assert validate_track_tokens(["en;rm"]) is not None
+
+
+def test_canonical_lang():
+    assert canonical_lang("eng") == "english"
+    assert canonical_lang("EN-us") == "english"
+    assert canonical_lang("jpn") == "japanese"
+    assert canonical_lang("chi") == canonical_lang("zho") == "chinese"
+    assert canonical_lang("und") is None
+    assert canonical_lang("") is None
+
+
+def test_resolve_by_language_name_and_code_in_token_order():
+    streams = [audio(1, "jpn"), audio(2, "eng"), audio(3, "hin")]
+    assert [s.index for s in resolve_tokens(streams, ["english", "japanese"])] == [2, 1]
+    assert [s.index for s in resolve_tokens(streams, ["eng", "jpn"])] == [2, 1]
+    assert [s.index for s in resolve_tokens(streams, ["hindi"])] == [3]
+
+
+def test_resolve_by_number_is_one_based_position_not_stream_index():
+    streams = [audio(5, "jpn"), audio(9, "eng")]
+    assert [s.index for s in resolve_tokens(streams, ["2", "1"])] == [9, 5]
+    assert resolve_tokens(streams, ["3"]) == []
+
+
+def test_resolve_dedupes_and_keeps_all_matches_of_a_language():
+    streams = [audio(1, "eng", "Dub"), audio(2, "jpn"), audio(3, "eng", "Commentary")]
+    assert [s.index for s in resolve_tokens(streams, ["english", "1"])] == [1, 3]
+    assert [s.index for s in resolve_tokens(streams, ["english", "japanese"])] == [1, 3, 2]
+
+
+def test_resolve_untagged_track_uses_title_words():
+    streams = [audio(1, "und", "Japanese [Original]"), audio(2, "", "English Dub")]
+    assert [s.index for s in resolve_tokens(streams, ["english"])] == [2]
+    assert [s.index for s in resolve_tokens(streams, ["japanese"])] == [1]
+
+
+def test_resolve_tagged_language_is_not_overridden_by_title():
+    streams = [audio(1, "jpn", "English commentary")]
+    assert resolve_tokens(streams, ["english"]) == []
+
+
+def test_resolve_unknown_language_word_matches_raw_code():
+    streams = [audio(1, "xyz"), audio(2, "eng")]
+    assert [s.index for s in resolve_tokens(streams, ["xyz"])] == [1]
+
+
+def make_info():
+    return MediaInfo(
+        duration=2,
+        streams=[
+            Stream(0, "video", codec="h264", width=320, height=240),
+            audio(1, "jpn", "Japanese Original"),
+            audio(2, "eng"),
+            audio(3, "hin"),
+            sub(4, "jpn"),
+            sub(5, "eng"),
+            Stream(6, "attachment", codec="ttf"),
+        ],
+    )
+
+
+def test_build_plan_none_when_metadata_off_or_nothing_to_do():
+    info = make_info()
+    assert build_plan(info, {"metadata_on": False, "keep_audio": ["1"]}, ".mkv") is None
+    assert build_plan(info, {"metadata_on": True, "meta": {}}, ".mkv") is None
+    assert build_plan(info, {"metadata_on": True, "keep_audio": ["1"]}, ".avi") is None
+
+
+def test_build_plan_maps_in_requested_order_and_drops_others():
+    plan = build_plan(
+        make_info(),
+        {"metadata_on": True, "keep_audio": ["english", "japanese"], "keep_subtitle": ["2"], "meta": {}},
+        ".mkv",
+    )
+    assert plan is not None
+    maps = [plan.args[i + 1] for i, a in enumerate(plan.args) if a == "-map"]
+    # video, audio eng(2) then jpn(1), subtitle #2 -> stream 5, attachment kept; hindi + jpn sub dropped
+    assert maps == ["0:0", "0:2", "0:1", "0:5", "0:6"]
+    assert plan.args[plan.args.index("-disposition:a:0") + 1] == "+default"
+    assert plan.args[plan.args.index("-disposition:a:1") + 1] == "-default"
+    assert plan.args[plan.args.index("-disposition:s:0") + 1] == "+default"
+
+
+def test_build_plan_audio_safeguard():
+    plan = build_plan(make_info(), {"metadata_on": True, "keep_audio": ["klingon"], "meta": {}}, ".mkv")
+    assert plan is not None
+    assert [s.index for s in plan.kept_audio] == [1, 2, 3]
+    assert plan.warnings
+
+
+def test_build_plan_subtitles_dropped_when_nothing_matches():
+    plan = build_plan(make_info(), {"metadata_on": True, "keep_subtitle": ["french"], "meta": {}}, ".mkv")
+    assert plan.kept_subtitles == []
+    maps = [plan.args[i + 1] for i, a in enumerate(plan.args) if a == "-map"]
+    assert "0:4" not in maps and "0:5" not in maps
+
+
+def test_build_plan_metadata_fields_and_lang_placeholder():
+    plan = build_plan(
+        make_info(),
+        {
+            "metadata_on": True,
+            "keep_audio": ["japanese", "english"],
+            "meta": {"title": "Tokyo Revengers", "author": "@chan", "artist": "@chan",
+                     "audio": "{lang} Audio", "subtitle": "English", "video": "@chan"},
+        },
+        ".mkv",
+    )
+    a = plan.args
+    assert ["-metadata", "title=Tokyo Revengers"] == a[a.index("title=Tokyo Revengers") - 1: a.index("title=Tokyo Revengers") + 1]
+    assert "author=@chan" in a and "artist=@chan" in a
+    assert "title=Japanese Audio" in a and "title=English Audio" in a
+    assert a.index("title=Japanese Audio") < a.index("title=English Audio")
+    assert "-metadata:s:v:0" in a and "-metadata:s:s:0" in a
+
+
+def test_build_plan_mp3_tags_only():
+    plan = build_plan(MediaInfo(), {"metadata_on": True, "meta": {"title": "T", "author": "A"}}, ".mp3")
+    assert plan is not None
+    assert "title=T" in plan.args and "artist=A" in plan.args
+    assert build_plan(MediaInfo(), {"metadata_on": True, "meta": {}}, ".mp3") is None
+
+
+def test_format_tracks():
+    text = format_tracks(make_info())
+    assert "1. Japanese (jpn)" in text and "2. English (eng)" in text and "3. Hindi (hin)" in text
+    assert "Subtitles" in text and "“Japanese Original”" in text
+
+
+def test_parse_probe_duration_fallbacks():
+    info = parse_probe({"format": {"duration": "12.5"}, "streams": []})
+    assert info.duration == 12.5
+    info = parse_probe({"format": {}, "streams": [{"index": 0, "codec_type": "video", "tags": {"DURATION": "00:00:03.500000000"}}]})
+    assert info.duration == 3.5
+
+
+# ---------------------------------------------------------------------------
+# real ffprobe / ffmpeg
+# ---------------------------------------------------------------------------
+
+
+@needs_ffmpeg
+async def test_probe_real_mkv(media_dir):
+    info = await probe(media_dir / "sample.mkv")
+    assert [s.kind for s in info.streams] == ["video", "audio", "audio", "audio", "subtitle", "subtitle", "attachment"]
+    assert [s.lang for s in info.audio] == ["jpn", "eng", "hin"]
+    assert [s.lang for s in info.subtitles] == ["jpn", "eng"]
+    assert info.width == 320 and info.height == 240
+    assert 1.5 < info.duration < 2.6
+
+
+@needs_ffmpeg
+async def test_probe_missing_file_raises(tmp_path):
+    with pytest.raises(MediaError):
+        await probe(tmp_path / "nope.mkv")
+
+
+@needs_ffmpeg
+async def test_apply_plan_mkv_reorders_drops_and_tags(media_dir, tmp_path):
+    src = media_dir / "sample.mkv"
+    info = await probe(src)
+    settings = {
+        "metadata_on": True,
+        "keep_audio": ["english", "japanese"],
+        "keep_subtitle": ["english"],
+        "meta": {"title": "Tokyo Revengers", "author": "@chan", "artist": "@chan",
+                 "audio": "{lang} Audio", "subtitle": "{lang}", "video": "@chan video"},
+    }
+    plan = build_plan(info, settings, ".mkv")
+    dst = tmp_path / "out.mkv"
+    await apply_plan(src, dst, plan)
+
+    data = ffprobe_json(dst, "-show_chapters")
+    streams = data["streams"]
+    kinds = [s["codec_type"] for s in streams]
+    assert kinds == ["video", "audio", "audio", "subtitle", "attachment"]
+    audios = [s for s in streams if s["codec_type"] == "audio"]
+    assert [a["tags"]["language"] for a in audios] == ["eng", "jpn"]  # reordered, hindi dropped
+    assert [a["tags"]["title"] for a in audios] == ["English Audio", "Japanese Audio"]
+    assert audios[0]["disposition"]["default"] == 1 and audios[1]["disposition"]["default"] == 0
+    sub_stream = next(s for s in streams if s["codec_type"] == "subtitle")
+    assert sub_stream["tags"]["language"] == "eng" and sub_stream["tags"]["title"] == "English"
+    assert sub_stream["disposition"]["default"] == 1
+    video = streams[0]
+    assert video["tags"]["title"] == "@chan video"
+    fmt_tags = {k.lower(): v for k, v in data["format"]["tags"].items()}  # Matroska stores AUTHOR/ARTIST upper-case
+    assert fmt_tags["title"] == "Tokyo Revengers"
+    assert fmt_tags["author"] == "@chan" and fmt_tags["artist"] == "@chan"
+    assert len(data["chapters"]) == 2  # chapters survive
+    attach = next(s for s in streams if s["codec_type"] == "attachment")
+    assert attach["tags"]["filename"] == "font.ttf"  # fonts survive
+
+
+@needs_ffmpeg
+async def test_apply_plan_numbers_follow_given_order(media_dir, tmp_path):
+    src = media_dir / "sample.mkv"
+    info = await probe(src)
+    plan = build_plan(info, {"metadata_on": True, "keep_audio": ["3", "1"], "keep_subtitle": ["2", "1"], "meta": {}}, ".mkv")
+    dst = tmp_path / "out.mkv"
+    await apply_plan(src, dst, plan)
+    out = await probe(dst)
+    assert [s.lang for s in out.audio] == ["hin", "jpn"]
+    assert [s.lang for s in out.subtitles] == ["eng", "jpn"]
+
+
+@needs_ffmpeg
+async def test_apply_plan_audio_safeguard_keeps_everything(media_dir, tmp_path):
+    src = media_dir / "sample.mkv"
+    info = await probe(src)
+    plan = build_plan(info, {"metadata_on": True, "keep_audio": ["french"], "meta": {}}, ".mkv")
+    dst = tmp_path / "out.mkv"
+    await apply_plan(src, dst, plan)
+    assert len((await probe(dst)).audio) == 3
+
+
+@needs_ffmpeg
+async def test_apply_plan_mp4(media_dir, tmp_path):
+    src = media_dir / "sample.mp4"
+    info = await probe(src)
+    plan = build_plan(info, {"metadata_on": True, "keep_audio": ["english", "japanese"], "keep_subtitle": ["1"],
+                             "meta": {"title": "MP4 Title"}}, ".mp4")
+    dst = tmp_path / "out.mp4"
+    await apply_plan(src, dst, plan)
+    out = await probe(dst)
+    assert [s.lang for s in out.audio] == ["eng", "jpn"]
+    assert [s.kind for s in out.streams].count("subtitle") == 1
+    assert out.tags.get("title") == "MP4 Title"
+
+
+@needs_ffmpeg
+async def test_apply_plan_mp3_title(media_dir, tmp_path):
+    src = media_dir / "sample.mp3"
+    plan = build_plan(await probe(src), {"metadata_on": True, "meta": {"title": "New Title", "artist": "Me"}}, ".mp3")
+    dst = tmp_path / "out.mp3"
+    await apply_plan(src, dst, plan)
+    out = await probe(dst)
+    assert out.tags["title"] == "New Title" and out.tags["artist"] == "Me"
+
+
+@needs_ffmpeg
+async def test_apply_plan_failure_raises_media_error(tmp_path):
+    bad = tmp_path / "bad.mkv"
+    bad.write_bytes(b"not a video")
+    from bot.media import Plan
+
+    with pytest.raises(MediaError):
+        await apply_plan(bad, tmp_path / "out.mkv", Plan(["-map", "0:0", "-c", "copy"]))
+
+
+@needs_ffmpeg
+async def test_cancel_kills_ffmpeg(media_dir, tmp_path):
+    cancel = asyncio.Event()
+    cancel.set()
+    info = await probe(media_dir / "sample.mkv")
+    plan = build_plan(info, {"metadata_on": True, "keep_audio": ["1"], "meta": {}}, ".mkv")
+    with pytest.raises(Cancelled):
+        await apply_plan(media_dir / "sample.mkv", tmp_path / "out.mkv", plan, cancel)
+
+
+@needs_ffmpeg
+async def test_thumbnail_and_prepare_thumb(media_dir, tmp_path):
+    out = tmp_path / "t.jpg"
+    assert await make_video_thumbnail(media_dir / "sample.mkv", out, 2.0)
+    assert out.read_bytes()[:2] == b"\xff\xd8"
+    from PIL import Image
+    import io
+
+    big = io.BytesIO()
+    Image.effect_noise((1600, 1200), 80).convert("RGB").save(big, "PNG")
+    jpg = prepare_thumb(big.getvalue())
+    img = Image.open(io.BytesIO(jpg))
+    assert max(img.size) <= 320 and len(jpg) <= 200 * 1024 and img.format == "JPEG"
+    assert not await make_video_thumbnail(tmp_path / "missing.mkv", tmp_path / "x.jpg", 1.0)

tests/test_panels.py

@@ -0,0 +1,160 @@
+import copy
+import html
+import re
+
+import pytest
+
+from bot import panels
+from bot.app import BACK, PANEL_NAMES
+from bot.db import DEFAULT_SETTINGS
+from bot.media import LANGUAGES
+
+from .tgfakes import button_rows
+
+CAPTION_LIMIT = 1000  # Telegram allows 1024 for a caption; keep a margin
+
+
+def visible(text: str) -> str:
+    return html.unescape(re.sub(r"<[^>]+>", "", text))
+
+
+def settings(**over):
+    s = copy.deepcopy(DEFAULT_SETTINGS)
+    s.update(over)
+    return s
+
+
+def worst_case():
+    longest = sorted(LANGUAGES, key=len, reverse=True)[:12]
+    return settings(
+        mode="caption", file_type="document", metadata_on=True,
+        template="W" * 200, caption="C" * 800, remove_words=["R" * 60] * 50,
+        meta={k: "M" * 200 for k in DEFAULT_SETTINGS["meta"]},
+        keep_audio=list(longest), keep_subtitle=list(longest), target_channel=-1001234567890123,
+    )
+
+
+def every_panel(s, has_thumb=True):
+    out = {
+        "home_owner": panels.home(s, owner=True),
+        "home_user": panels.home(s, owner=False),
+        "rename": panels.rename(s),
+        "cap": panels.caption(s, has_thumb),
+        "meta": panels.metadata(s),
+        "tool": panels.tool(s),
+        "ftype": panels.filetype(s),
+        "help": panels.help_panel(),
+        "metahelp": panels.metadata_help(),
+        "admin": panels.admin(1, list(range(1000, 1030)), 3, 4, -1001234567890),
+    }
+    out.update({f"prompt_{k}": panels.input_prompt(k, BACK[k]) for k in panels.PROMPTS})
+    return out
+
+
+@pytest.mark.parametrize("s", [settings(), worst_case()], ids=["defaults", "worst-case"])
+def test_every_panel_fits_in_a_photo_caption(s):
+    for name, (text, _rows) in every_panel(s).items():
+        assert len(visible(text)) <= CAPTION_LIMIT, f"{name} is {len(visible(text))} characters"
+
+
+@pytest.mark.parametrize("s", [settings(), worst_case()], ids=["defaults", "worst-case"])
+def test_callback_data_is_short_unique_per_panel_and_labels_are_present(s):
+    for name, (_text, rows) in every_panel(s).items():
+        seen = set()
+        for row in rows:
+            assert 1 <= len(row) <= 4, name
+            for label, data in row:
+                assert label.strip() and len(label) <= 32, (name, label)
+                assert 0 < len(data.encode()) <= 64, (name, data)
+                assert data not in seen, (name, data)
+                seen.add(data)
+
+
+def test_every_panel_html_is_balanced():
+    for name, (text, _rows) in every_panel(worst_case()).items():
+        for tag in ("b", "code", "i"):
+            assert text.count(f"<{tag}>") == text.count(f"</{tag}>"), (name, tag)
+
+
+def test_every_input_button_has_a_prompt_and_a_back_target():
+    assert set(panels.PROMPTS) == set(BACK)
+    assert set(BACK.values()) <= PANEL_NAMES
+    for name, (_text, rows) in every_panel(settings()).items():
+        for row in rows:
+            for _label, data in row:
+                if data.startswith("in:") and not data.startswith("in:cancel"):
+                    assert data[3:] in panels.PROMPTS, (name, data)
+                if data.startswith("m:"):
+                    assert data[2:] in PANEL_NAMES, (name, data)
+
+
+def test_navigation_always_offers_a_way_out():
+    for name, (_text, rows) in every_panel(settings()).items():
+        data = [d for row in rows for _l, d in row]
+        if name.startswith("prompt_"):
+            assert any(d.startswith("in:cancel:") for d in data), name
+        else:
+            assert "x:close" in data, name
+
+
+def test_home_shows_admin_button_only_to_the_owner():
+    owner = [d for row in panels.home(settings(), owner=True)[1] for _l, d in row]
+    user = [d for row in panels.home(settings(), owner=False)[1] for _l, d in row]
+    assert "m:admin" in owner and "m:admin" not in user
+    for expected in ("m:rename", "m:cap", "m:meta", "m:ftype", "m:help"):
+        assert expected in user
+
+
+def test_active_choices_get_a_checkmark():
+    def labels(panel):
+        return {data: label for row in panel[1] for label, data in row}
+
+    r = labels(panels.rename(settings(mode="caption")))
+    assert r["set:mode:caption"].endswith("✅") and not r["set:mode:filename"].endswith("✅")
+    f = labels(panels.filetype(settings(file_type="audio")))
+    assert [k for k, v in f.items() if v.endswith("✅")] == ["set:ftype:audio"]
+    m = labels(panels.metadata(settings(metadata_on=True)))
+    assert m["set:meta:on"].endswith("✅") and not m["set:meta:off"].endswith("✅")
+
+
+def test_metadata_panel_matches_the_reference_layout():
+    text, rows = panels.metadata(settings(metadata_on=True, keep_audio=["english", "2"], meta={"title": "T", "author": "", "artist": "", "audio": "", "subtitle": "", "video": ""}))
+    plain = visible(text)
+    assert "currently: On" in plain
+    for label in ("Title", "Author", "Artist", "Audio", "Subtitle", "Video", "Keep Audio", "Keep Subtitle"):
+        assert label in plain
+    assert "English, 2" in plain
+    data = [d for row in rows for _l, d in row]
+    for expected in ("set:meta:on", "set:meta:off", "in:mt_title", "in:mt_author", "in:mt_artist", "in:mt_audio",
+                     "in:mt_subtitle", "in:mt_video", "m:tool", "help:meta"):
+        assert expected in data
+
+
+def test_tool_panel_holds_keep_audio_and_keep_subtitle():
+    text, rows = panels.tool(settings(keep_subtitle=["english"]))
+    data = [d for row in rows for _l, d in row]
+    assert {"in:keep_audio", "in:keep_subtitle", "clr:keep_audio", "clr:keep_subtitle"} <= set(data)
+    assert "m:meta" in data  # Back goes to the metadata panel
+    assert "English" in visible(text)
+
+
+def test_fmt_tokens():
+    assert panels.fmt_tokens([]) == "—"
+    assert panels.fmt_tokens(["english", "2", "jpn"]) == "English, 2, Japanese"
+    assert panels.fmt_tokens(["klingon"]) == "Klingon"
+
+
+def test_html_in_user_values_is_escaped():
+    s = settings(template="<b>{title}</b> & co", meta={**DEFAULT_SETTINGS["meta"], "title": "<i>x</i>"})
+    assert "<b>{title}</b>" not in panels.rename(s)[0]
+    assert "&lt;b&gt;" in panels.rename(s)[0]
+    assert "<i>x</i>" not in panels.metadata(s)[0]
+
+
+def test_to_buttons_builds_callback_buttons():
+    rows = [[("A", "a:1"), ("B", "b:2")], [("C", "c:3")]]
+    assert button_rows(panels.to_buttons(rows)) == rows
+
+
+def test_known_languages_lists_names():
+    assert "english" in panels.known_languages()

tests/test_parser.py

@@ -0,0 +1,202 @@
+import pytest
+
+from bot.parser import (
+    DEFAULT_TEMPLATE,
+    apply_remove_words,
+    build_manual_name,
+    compute_new_name,
+    finalize_name,
+    parse_caption,
+    parse_info,
+    render_template,
+    sanitize,
+    split_ext,
+)
+
+
+@pytest.mark.parametrize(
+    "name,title,season,episode,quality,year",
+    [
+        ("[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234].mkv", "Tokyo Revengers", "01", "05", "1080p", ""),
+        ("Show.Name.S02E10.Some.Episode.Title.720p.WEB-DL.x264-GRP.mkv", "Show Name", "02", "10", "720p", ""),
+        ("Naruto Shippuden Episode 123 Dual Audio 720p.mp4", "Naruto Shippuden", "01", "123", "720p", ""),
+        ("Inception.2010.1080p.BluRay.x264-GROUP.mkv", "Inception", "", "", "1080p", "2010"),
+        ("Blade.Runner.2049.2017.1080p.BluRay.mkv", "Blade Runner 2049", "", "", "1080p", "2017"),
+        ("One Piece - 1000 [1080p].mkv", "One Piece", "01", "1000", "1080p", ""),
+        ("Attack_on_Titan_S4E28_480p.mp4", "Attack on Titan", "04", "28", "480p", ""),
+        ("Show 1x05 720p.mkv", "Show", "01", "05", "720p", ""),
+        ("[S01E05] Title [720p].mkv", "Title", "01", "05", "720p", ""),
+        ("Title (2021) - 05 [720p].mkv", "Title", "01", "05", "720p", "2021"),
+        ("Some Movie 1920x1080.mkv", "Some Movie", "", "", "1080p", ""),
+        ("Plain Name.mkv", "Plain Name", "", "", "", ""),
+        ("Show S2 - 07 [1080p].mkv", "Show", "02", "07", "1080p", ""),
+        ("Movie 4K HDR.mkv", "Movie", "", "", "2160p", ""),
+    ],
+)
+def test_parse_info(name, title, season, episode, quality, year):
+    info = parse_info(name)
+    assert (info.title, info.season, info.episode, info.quality, info.year) == (
+        title, season, episode, quality, year
+    )
+
+
+def test_resolution_is_not_an_episode():
+    info = parse_info("Some Movie 1920x1080.mkv")
+    assert info.episode == ""
+
+
+def test_codec_detection():
+    assert parse_info("Show.S01E01.1080p.x265-GRP.mkv").codec == "x265"
+    assert parse_info("Show.S01E01.1080p.H.264.mkv").codec == "H264"
+    assert parse_info("Show - 01 [HEVC].mkv").codec == "HEVC"
+
+
+def test_title_only_marker_at_start():
+    info = parse_info("S01E05 Some Title.mkv")
+    assert info.title == "Some Title"
+    assert (info.season, info.episode) == ("01", "05")
+
+
+def test_split_ext():
+    assert split_ext("a.b.mkv") == ("a.b", ".mkv")
+    assert split_ext("Season 1.5", known_only=True) == ("Season 1.5", "")
+    assert split_ext("Season 1.5") == ("Season 1.5", "")
+    assert split_ext("noext") == ("noext", "")
+    assert split_ext("x.MKV", known_only=True) == ("x", ".MKV")
+    assert split_ext("weird.abc", known_only=True) == ("weird.abc", "")
+    assert split_ext("weird.abc") == ("weird", ".abc")
+
+
+def test_render_template_drops_group_with_empty_variable():
+    values = {"title": "Show", "season": "", "episode": "", "quality": "720p", "year": "", "codec": "", "filename": "x", "ext": "mkv"}
+    assert render_template(DEFAULT_TEMPLATE, values) == "Show [720p]"
+    values["quality"] = ""
+    assert render_template(DEFAULT_TEMPLATE, values) == "Show"
+
+
+def test_render_template_full():
+    values = {"title": "Show", "season": "01", "episode": "05", "quality": "720p", "year": "", "codec": "", "filename": "x", "ext": "mkv"}
+    assert render_template(DEFAULT_TEMPLATE, values) == "[S01E05] Show [720p]"
+    assert render_template("{title} - {episode}", values) == "Show - 05"
+    assert render_template("{title}.S{season}E{episode}", values) == "Show.S01E05"
+
+
+def test_render_template_values_are_not_reparsed():
+    values = {"title": "{quality} [x]", "season": "", "episode": "", "quality": "720p", "year": "", "codec": "", "filename": "x", "ext": "mkv"}
+    assert render_template("{title} [{quality}]", values) == "{quality} [x] [720p]"
+
+
+def test_render_template_unknown_token_kept():
+    values = {"title": "T", "season": "", "episode": "", "quality": "", "year": "", "codec": "", "filename": "x", "ext": "mkv"}
+    assert render_template("{title} {nope}", values) == "T {nope}"
+
+
+def test_compute_new_name_filename_mode():
+    name, info = compute_new_name(
+        template=DEFAULT_TEMPLATE,
+        mode="filename",
+        original_name="[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234].mkv",
+        original_ext=".mkv",
+    )
+    assert name == "[S01E05] Tokyo Revengers [1080p].mkv"
+    assert info.episode == "05"
+
+
+def test_compute_new_name_caption_mode_uses_caption():
+    name, _ = compute_new_name(
+        template=DEFAULT_TEMPLATE,
+        mode="caption",
+        original_name="random_file_123.mkv",
+        original_ext=".mkv",
+        caption="Bleach S01E12 720p",
+    )
+    assert name == "[S01E12] Bleach [720p].mkv"
+
+
+def test_compute_new_name_caption_mode_falls_back_to_filename():
+    name, _ = compute_new_name(
+        template=DEFAULT_TEMPLATE,
+        mode="caption",
+        original_name="One.Piece.E1000.1080p.mkv",
+        original_ext=".mkv",
+        caption="Hello everyone, enjoy!",
+    )
+    assert name == "[S01E1000] One Piece [1080p].mkv"
+
+
+def test_compute_new_name_caption_fills_missing_from_filename():
+    name, _ = compute_new_name(
+        template=DEFAULT_TEMPLATE,
+        mode="caption",
+        original_name="Show.S01E03.1080p.mkv",
+        original_ext=".mkv",
+        caption="Show Name S01E03",
+    )
+    assert name == "[S01E03] Show Name [1080p].mkv"
+
+
+def test_caption_title_from_first_line_details_from_rest():
+    info = parse_caption("My Show\nEpisode: 5\nQuality: 720p")
+    assert info.title == "My Show"
+    assert info.quality == "720p"
+
+
+def test_compute_new_name_remove_words_and_illegal_chars():
+    name, _ = compute_new_name(
+        template="{title} {quality}",
+        mode="filename",
+        original_name="Re:Zero - 03 [720p] @SomeChannel.mkv",
+        original_ext=".mkv",
+        remove_words=["@SomeChannel"],
+    )
+    assert name == "Re Zero 720p.mkv"
+
+
+def test_compute_new_name_keeps_extension_and_no_double_ext():
+    name, _ = compute_new_name(
+        template="{title}.{ext}",
+        mode="filename",
+        original_name="Movie.2020.720p.mkv",
+        original_ext=".mkv",
+    )
+    assert name == "Movie.mkv"
+
+
+def test_compute_new_name_missing_everything_falls_back_to_original():
+    name, _ = compute_new_name(
+        template="[S{season}E{episode}]",
+        mode="filename",
+        original_name="holiday video.mp4",
+        original_ext=".mp4",
+    )
+    assert name == "holiday video.mp4"
+
+
+def test_compute_new_name_uses_original_ext_when_name_has_none():
+    name, _ = compute_new_name(
+        template="{title}", mode="filename", original_name="Movie", original_ext=".mp4"
+    )
+    assert name == "Movie.mp4"
+
+
+def test_finalize_truncates_by_bytes_and_keeps_ext():
+    out = finalize_name("é" * 300, ".mkv")
+    assert out.endswith(".mkv")
+    assert len(out.encode("utf-8")) <= 200
+
+
+def test_manual_name_keeps_original_ext():
+    assert build_manual_name("My Movie", ".mkv") == "My Movie.mkv"
+    assert build_manual_name("My Movie.mkv", ".mkv") == "My Movie.mkv"
+    assert build_manual_name("My Movie.mp4", ".mkv") == "My Movie.mkv"
+    assert build_manual_name("Season 1.5", ".mkv") == "Season 1.5.mkv"
+    assert build_manual_name("Fixed.mkv", "") == "Fixed.mkv"
+
+
+def test_manual_name_sanitised():
+    assert build_manual_name('a/b:c*d?.mkv', ".mkv") == "a b c d.mkv"
+
+
+def test_sanitize_and_remove_words():
+    assert sanitize("  ..hidden:name  ") == "hidden name"
+    assert apply_remove_words("Show [Group] 720p", ["[group]"]) == "Show 720p"

tests/test_pipeline.py

@@ -0,0 +1,279 @@
+import shutil
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+from telethon import errors, types
+
+from bot.config import load_config
+from bot.db import Database
+from bot.media import probe
+from bot.parser import DEFAULT_TEMPLATE, compute_new_name
+from bot.pipeline import Renamer, decide_send_type, guess_mime, original_name_of, source_ext
+from bot.queue import Job
+
+from .conftest import needs_ffmpeg
+
+
+class FakeMessage:
+    def __init__(self, name, size, *, video=True, audio=False, mime="video/x-matroska", msg_id=7, ext=None):
+        self.id = msg_id
+        self.file = SimpleNamespace(name=name, size=size, ext=ext if ext is not None else Path(name or "").suffix, mime_type=mime)
+        self.video = object() if video else None
+        self.audio = object() if audio else None
+        self.document = object()
+
+
+class FakeClient:
+    def __init__(self, source: Path, message: FakeMessage):
+        self.source = source
+        self.message = message
+        self.sent = []
+        self.edits = []
+        self.uploads = {}
+        self.download_error = None
+        self.send_errors = []
+
+    async def get_messages(self, chat_id, ids):
+        return self.message
+
+    async def download_media(self, message, file, progress_callback):
+        progress_callback(1, 2)
+        if self.download_error:
+            raise self.download_error
+        shutil.copy(self.source, file)
+        progress_callback(2, 2)
+
+    async def upload_file(self, path, file_name, progress_callback):
+        progress_callback(1, 1)
+        keep = Path(path).with_name("uploaded_copy_" + Path(path).name)
+        keep = Path(self.source).parent / ("upload-" + str(len(self.uploads)) + Path(path).suffix)
+        shutil.copy(path, keep)
+        self.uploads[len(self.uploads)] = keep
+        return types.InputFileBig(id=len(self.uploads), parts=1, name=file_name)
+
+    async def send_file(self, target, input_file, **kwargs):
+        if self.send_errors:
+            raise self.send_errors.pop(0)
+        self.sent.append((target, input_file, kwargs))
+
+    async def edit_message(self, message, text, buttons=None, parse_mode=None):
+        self.edits.append((text, buttons))
+
+
+@pytest.fixture
+async def env(tmp_path, media_dir):
+    cfg = load_config({
+        "API_ID": "1", "API_HASH": "h", "BOT_TOKEN": "1:t", "OWNER_ID": "42",
+        "TEMP_DIR": str(tmp_path / "work"), "FAST_TRANSFER": "0", "PROGRESS_INTERVAL": "2",
+    })
+    db = Database(f"sqlite+aiosqlite:///{tmp_path}/p.db")
+    await db.init()
+    logs = []
+
+    async def log_send(text):
+        logs.append(text)
+
+    ns = SimpleNamespace(cfg=cfg, db=db, logs=logs, log_send=log_send, media_dir=media_dir, tmp=tmp_path)
+    yield ns
+    await db.close()
+
+
+def make(env, name="[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234].mkv", src="sample.mkv", **msg_kwargs):
+    source = env.media_dir / src
+    message = FakeMessage(name, source.stat().st_size, **msg_kwargs)
+    client = FakeClient(source, message)
+    renamer = Renamer(client, env.cfg, env.db, env.log_send)
+    new_name, _ = compute_new_name(template=DEFAULT_TEMPLATE, mode="filename", original_name=name, original_ext=Path(name).suffix)
+    job = Job(id=1, user_id=42, chat_id=42, msg_id=7, file_name=name, size=source.stat().st_size, new_name=new_name,
+              status_msg=SimpleNamespace(id=99))
+    return client, renamer, job
+
+
+@needs_ffmpeg
+async def test_plain_rename_sends_video_with_thumbnail(env):
+    client, renamer, job = make(env)
+    await renamer.process(job)
+
+    assert job.new_name == "[S01E05] Tokyo Revengers [1080p].mkv"
+    (target, input_file, kw), = client.sent
+    assert target == 42 and kw["reply_to"] == 7
+    by_type = {type(a): a for a in kw["attributes"]}
+    assert by_type[types.DocumentAttributeFilename].file_name == job.new_name
+    video = by_type[types.DocumentAttributeVideo]
+    assert (video.w, video.h) == (320, 240) and 1 < video.duration < 3 and video.supports_streaming
+    assert kw["force_document"] is False and kw["mime_type"] == "video/x-matroska"
+    assert kw["thumb"][:2] == b"\xff\xd8"  # generated from a video frame
+    assert kw["caption"] == "[S01E05] Tokyo Revengers [1080p]"
+    assert input_file.name == job.new_name
+    assert client.uploads[0].read_bytes() == (env.media_dir / "sample.mkv").read_bytes()  # untouched without metadata
+    assert "Done" in client.edits[-1][0] and client.edits[-1][1] is None
+    assert job.state == "done"
+    assert (await env.db.totals())[0] == 1
+    assert not (Path(env.cfg.temp_dir) / "job1").exists()  # temp files cleaned
+    assert any("Tokyo Revengers" in t for t in env.logs)
+
+
+@needs_ffmpeg
+async def test_metadata_and_track_selection_are_applied_before_upload(env):
+    await env.db.update_settings(
+        42, metadata_on=True, keep_audio=["english", "japanese"], keep_subtitle=["2"],
+        meta={"title": "Tokyo Revengers", "audio": "{lang}", "subtitle": "English"},
+    )
+    client, renamer, job = make(env)
+    await renamer.process(job)
+    out = await probe(client.uploads[0])
+    assert [s.lang for s in out.audio] == ["eng", "jpn"]
+    assert [s.lang for s in out.subtitles] == ["eng"]
+    assert out.tags.get("title") == "Tokyo Revengers"
+    assert [s.title for s in out.audio] == ["English", "Japanese"]
+    assert client.sent and job.state == "done"
+
+
+@needs_ffmpeg
+async def test_document_file_type_is_forced(env):
+    await env.db.update_settings(42, file_type="document")
+    client, renamer, job = make(env)
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    assert kw["force_document"] is True
+    assert types.DocumentAttributeVideo not in {type(a) for a in kw["attributes"]}
+
+
+@needs_ffmpeg
+async def test_same_type_keeps_document_as_document(env):
+    client, renamer, job = make(env, video=False)  # original was sent as a file
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    assert kw["force_document"] is True
+    assert types.DocumentAttributeVideo not in {type(a) for a in kw["attributes"]}
+
+
+@needs_ffmpeg
+async def test_forced_video_for_non_video_falls_back_to_document(env, tmp_path):
+    blob = tmp_path / "data.zip"
+    blob.write_bytes(b"PK" + b"0" * 5000)
+    message = FakeMessage("stuff.zip", 5002, video=False, mime="application/zip")
+    client = FakeClient(blob, message)
+    renamer = Renamer(client, env.cfg, env.db, env.log_send)
+    await env.db.update_settings(42, file_type="video")
+    job = Job(id=2, user_id=42, chat_id=42, msg_id=7, file_name="stuff.zip", size=5002, new_name="Stuff.zip", status_msg=object())
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    assert kw["force_document"] is True and kw["mime_type"] == "application/zip"
+    assert kw["thumb"] is None
+
+
+@needs_ffmpeg
+async def test_custom_thumbnail_wins_over_generated(env):
+    await env.db.set_thumb(42, b"\xff\xd8custom")
+    client, renamer, job = make(env)
+    await renamer.process(job)
+    assert client.sent[0][2]["thumb"] == b"\xff\xd8custom"
+
+
+@needs_ffmpeg
+async def test_target_channel(env):
+    await env.db.update_settings(42, target_channel=-100123)
+    client, renamer, job = make(env)
+    await renamer.process(job)
+    (target, _f, kw), = client.sent
+    assert target == -100123 and "reply_to" not in kw
+    assert "channel" in client.edits[-1][0]
+
+
+@needs_ffmpeg
+async def test_audio_file_sent_as_audio_with_tags(env):
+    await env.db.update_settings(42, metadata_on=True, meta={"title": "Song", "artist": "Me"})
+    client, renamer, job = make(env, name="old name.mp3", src="sample.mp3", video=False, audio=True, mime="audio/mpeg")
+    job.new_name = "New Song.mp3"
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    audio = next(a for a in kw["attributes"] if isinstance(a, types.DocumentAttributeAudio))
+    assert audio.title == "Song" and audio.performer == "Me" and audio.duration >= 1
+    assert kw["force_document"] is False and kw["mime_type"] == "audio/mpeg"
+    assert (await probe(client.uploads[0])).tags["title"] == "Song"
+
+
+@needs_ffmpeg
+async def test_unsupported_container_with_metadata_warns_but_still_renames(env, tmp_path):
+    # an .avi has video streams but is outside the supported remux containers
+    avi = tmp_path / "x.avi"
+    import subprocess
+    subprocess.run(["ffmpeg", "-y", "-loglevel", "error", "-f", "lavfi", "-i", "testsrc=duration=1:size=64x64:rate=5",
+                    "-c:v", "mpeg4", str(avi)], check=True)
+    message = FakeMessage("x.avi", avi.stat().st_size, video=False, mime="video/x-msvideo")
+    client = FakeClient(avi, message)
+    await env.db.update_settings(42, metadata_on=True, meta={"title": "T"})
+    job = Job(id=3, user_id=42, chat_id=42, msg_id=7, file_name="x.avi", size=avi.stat().st_size, new_name="Y.avi", status_msg=object())
+    await Renamer(client, env.cfg, env.db, env.log_send).process(job)
+    assert client.sent and "not supported" in client.edits[-1][0]
+
+
+@needs_ffmpeg
+async def test_caption_rejected_is_retried_without_caption(env):
+    client, renamer, job = make(env)
+    client.send_errors = [errors.MediaCaptionTooLongError(request=None)]
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    assert kw["caption"] is None
+    assert "caption was rejected" in client.edits[-1][0] and job.state == "done"
+
+
+@needs_ffmpeg
+async def test_cancel_before_start(env):
+    client, renamer, job = make(env)
+    job.cancel.set()
+    await renamer.process(job)
+    assert job.state == "cancelled" and client.sent == []
+    assert "Cancelled" in client.edits[-1][0]
+    assert not (Path(env.cfg.temp_dir) / "job1").exists()
+
+
+@needs_ffmpeg
+async def test_failure_is_reported_and_logged(env):
+    client, renamer, job = make(env)
+    client.download_error = RuntimeError("network down")
+    await renamer.process(job)
+    assert job.state == "failed" and client.sent == []
+    assert "Failed" in client.edits[-1][0] and "network down" in client.edits[-1][0]
+    assert any("Job failed" in t and "network down" in t for t in env.logs)
+    assert not (Path(env.cfg.temp_dir) / "job1").exists()
+
+
+@needs_ffmpeg
+async def test_not_enough_disk_space(env, monkeypatch):
+    client, renamer, job = make(env)
+    monkeypatch.setattr(shutil, "disk_usage", lambda p: SimpleNamespace(total=100, used=100, free=10))
+    await renamer.process(job)
+    assert job.state == "failed" and "disk space" in client.edits[-1][0]
+
+
+@needs_ffmpeg
+async def test_deleted_original_message_fails_cleanly(env):
+    client, renamer, job = make(env)
+
+    async def gone(chat_id, ids):
+        return None
+
+    client.get_messages = gone
+    await renamer.process(job)
+    assert job.state == "failed" and "deleted" in client.edits[-1][0]
+
+
+def test_helpers():
+    video = FakeMessage("a.mkv", 1)
+    doc = FakeMessage("a.mkv", 1, video=False)
+    audio = FakeMessage("a.mp3", 1, video=False, audio=True)
+    assert decide_send_type("same", video) == "video"
+    assert decide_send_type("same", doc) == "document"
+    assert decide_send_type("same", audio) == "audio"
+    assert decide_send_type("document", video) == "document"
+    assert decide_send_type("audio", doc) == "audio"
+    assert guess_mime("x.mkv", None) == "video/x-matroska"
+    assert guess_mime("x.unknown123", "foo/bar") == "foo/bar"
+    assert guess_mime("x.unknown123", None) == "application/octet-stream"
+    nameless = FakeMessage(None, 1, ext=".mp4", msg_id=55)
+    assert original_name_of(nameless) == "video_55.mp4"
+    assert source_ext(nameless, "video_55.mp4") == ".mp4"
+    assert source_ext(FakeMessage("noext", 1, ext=".mkv"), "noext") == ".mkv"

tests/test_queue_progress.py

@@ -0,0 +1,226 @@
+import asyncio
+from types import SimpleNamespace
+
+from telethon import errors
+
+from bot.progress import ProgressReporter
+from bot.queue import Job, JobQueue
+
+
+def job(queue, user=1, name="a.mkv"):
+    return Job(id=queue.new_id(), user_id=user, chat_id=user, msg_id=1, file_name=name, size=1, new_name=name)
+
+
+async def test_runs_jobs_fifo_with_single_worker():
+    order = []
+    gate = asyncio.Event()
+
+    async def runner(j):
+        order.append(("start", j.id))
+        await gate.wait()
+        order.append(("end", j.id))
+
+    q = JobQueue(runner, workers=1)
+    q.start()
+    a, b, c = job(q), job(q), job(q)
+    assert q.add(a) == 0 and q.add(b) == 1 and q.add(c) == 2
+    await asyncio.sleep(0.05)
+    assert q.running == 1 and q.waiting == 2
+    assert q.position(a) == 0 and q.position(b) == 1 and q.position(c) == 2
+    gate.set()
+    await asyncio.sleep(0.1)
+    assert order == [("start", 1), ("end", 1), ("start", 2), ("end", 2), ("start", 3), ("end", 3)]
+    assert q.jobs == {}  # finished jobs are forgotten
+    await q.stop()
+
+
+async def test_two_workers_run_in_parallel():
+    running = []
+    peak = 0
+    gate = asyncio.Event()
+
+    async def runner(j):
+        nonlocal peak
+        running.append(j.id)
+        peak = max(peak, len(running))
+        await gate.wait()
+        running.remove(j.id)
+
+    q = JobQueue(runner, workers=2)
+    q.start()
+    for _ in range(4):
+        q.add(job(q))
+    await asyncio.sleep(0.05)
+    assert q.running == 2 and peak == 2
+    gate.set()
+    await asyncio.sleep(0.1)
+    await q.stop()
+
+
+async def test_cancel_queued_job_skips_it_and_calls_back():
+    done, cancelled = [], []
+    gate = asyncio.Event()
+
+    async def runner(j):
+        done.append(j.id)
+        await gate.wait()
+
+    async def on_cancelled(j):
+        cancelled.append(j.id)
+
+    q = JobQueue(runner, workers=1, on_cancelled=on_cancelled)
+    q.start()
+    a, b, c = job(q), job(q), job(q)
+    for j in (a, b, c):
+        q.add(j)
+    await asyncio.sleep(0.05)
+    assert q.cancel(b.id) is True
+    assert q.cancel(b.id) is False  # already gone
+    await asyncio.sleep(0.05)
+    assert cancelled == [b.id] and b.state == "cancelled"
+    gate.set()
+    await asyncio.sleep(0.1)
+    assert done == [a.id, c.id]
+    await q.stop()
+
+
+async def test_cancel_running_job_sets_its_event_and_cancel_is_scoped_to_user():
+    seen = {}
+    started = asyncio.Event()
+
+    async def runner(j):
+        started.set()
+        await j.cancel.wait()
+        seen["cancelled"] = True
+
+    q = JobQueue(runner, workers=1)
+    q.start()
+    a = job(q, user=5)
+    q.add(a)
+    await started.wait()
+    assert q.cancel(a.id, user_id=99) is False  # someone else's job
+    assert q.cancel(a.id, user_id=5) is True
+    await asyncio.sleep(0.05)
+    assert seen == {"cancelled": True}
+    await q.stop()
+
+
+async def test_cancel_user_and_cancel_all():
+    gate = asyncio.Event()
+
+    async def runner(j):
+        await gate.wait()
+
+    q = JobQueue(runner, workers=1)
+    q.start()
+    jobs = [job(q, user=1), job(q, user=1), job(q, user=2), job(q, user=2)]
+    for j in jobs:
+        q.add(j)
+    await asyncio.sleep(0.05)
+    assert q.cancel_user(1) == 2
+    assert [j.id for j in q.for_user(2)] == [jobs[2].id, jobs[3].id]
+    assert q.cancel_all() == 2
+    gate.set()
+    await q.stop()
+
+
+async def test_runner_crash_does_not_kill_the_worker():
+    ran = []
+
+    async def runner(j):
+        ran.append(j.id)
+        if j.id == 1:
+            raise RuntimeError("boom")
+
+    q = JobQueue(runner, workers=1)
+    q.start()
+    q.add(job(q))
+    q.add(job(q))
+    await asyncio.sleep(0.1)
+    assert ran == [1, 2]
+    await q.stop()
+
+
+# ---------------------------------------------------------------------------
+# progress reporter
+# ---------------------------------------------------------------------------
+
+
+class FakeClient:
+    def __init__(self):
+        self.edits = []
+        self.error = None
+
+    async def edit_message(self, message, text, buttons=None, parse_mode=None):
+        if self.error:
+            raise self.error
+        self.edits.append((text, buttons))
+
+
+async def test_reporter_throttles_and_shows_stage_and_cancel_button():
+    client = FakeClient()
+    r = ProgressReporter(client, SimpleNamespace(id=1), 7, "My <File>.mkv", interval=60)
+    r.set_stage("⬇️ Downloading", 1000)
+    await asyncio.sleep(0.02)
+    assert len(client.edits) == 1
+    text, buttons = client.edits[0]
+    assert "Downloading" in text and "My &lt;File&gt;.mkv" in text
+    assert buttons[0][0].type.data == b"job:x:7"
+
+    for cur in range(1, 500, 50):
+        r(cur, 1000)  # within the throttle window: no more edits
+    await asyncio.sleep(0.02)
+    assert len(client.edits) == 1
+
+    r(1000, 1000)  # completion always shows
+    await asyncio.sleep(0.02)
+    assert len(client.edits) == 2 and "100.0%" in client.edits[-1][0]
+
+
+async def test_stage_change_is_shown_even_while_an_edit_is_in_flight():
+    class SlowClient(FakeClient):
+        async def edit_message(self, message, text, buttons=None, parse_mode=None):
+            await asyncio.sleep(0.05)
+            await super().edit_message(message, text, buttons=buttons, parse_mode=parse_mode)
+
+    client = SlowClient()
+    r = ProgressReporter(client, None, 1, "x", interval=0)
+    r.set_stage("⬇️ Downloading", 100)
+    r(100, 100)  # dropped: the first edit is still running
+    r.set_stage("⚙️ Applying metadata", 0)  # must not be dropped
+    await r.finish("✅ Done")
+    stages = [t for t, _b in client.edits]
+    assert "Downloading" in stages[0] and "Applying metadata" in stages[1] and stages[-1] == "✅ Done"
+    assert len(stages) == 3
+
+
+async def test_reporter_render_numbers():
+    r = ProgressReporter(FakeClient(), None, 1, "x", interval=4)
+    r.stage = "⬆️ Uploading"
+    r._speed = 1024 * 1024
+    text = r.render(512 * 1024 * 1024, 1024 * 1024 * 1024)
+    assert "50.0%" in text and "512.00 MB / 1.00 GB" in text and "1.00 MB/s" in text and "ETA 8:32" in text
+    assert "Working" in r.render(0, 0)
+
+
+async def test_reporter_survives_flood_wait_and_message_errors():
+    client = FakeClient()
+    r = ProgressReporter(client, None, 1, "x", interval=0)
+    client.error = errors.FloodWaitError(request=None, capture=3)
+    r.set_stage("a", 10)
+    await asyncio.sleep(0.02)
+    assert r._muted_until > 0  # backed off instead of crashing
+    client.error = errors.MessageNotModifiedError(request=None)
+    r._muted_until = 0
+    r(5, 10)
+    await asyncio.sleep(0.02)
+    client.error = RuntimeError("deleted")
+    r(10, 10)
+    await asyncio.sleep(0.02)
+
+
+async def test_reporter_finish_removes_buttons():
+    client = FakeClient()
+    r = ProgressReporter(client, None, 1, "x")
+    await r.finish("✅ Done")
+    assert client.edits[-1] == ("✅ Done", None)

tests/test_settings_ops.py

@@ -0,0 +1,138 @@
+import pytest
+
+from bot.db import DEFAULT_SETTINGS, Database
+from bot.settings_ops import META_COMMANDS, META_KINDS, apply_setting, parse_channel, preview_template
+
+UID = 7
+
+
+@pytest.fixture
+async def db(tmp_path):
+    d = Database(f"sqlite+aiosqlite:///{tmp_path}/s.db")
+    await d.init()
+    yield d
+    await d.close()
+
+
+async def get(db):
+    return await db.get_settings(UID)
+
+
+async def test_template_saved_with_preview(db):
+    ok, msg = await apply_setting(db, UID, "template", "[S{season}E{episode}] {title} [{quality}]")
+    assert ok and "Template saved" in msg and "Preview" in msg
+    assert (await get(db))["template"] == "[S{season}E{episode}] {title} [{quality}]"
+
+
+async def test_template_validation_and_reset(db):
+    assert (await apply_setting(db, UID, "template", "   "))[0] is False
+    ok, msg = await apply_setting(db, UID, "template", "x" * 201)
+    assert not ok and "too long" in msg
+    assert (await get(db))["template"] == DEFAULT_SETTINGS["template"]
+    await apply_setting(db, UID, "template", "{title}")
+    ok, _ = await apply_setting(db, UID, "template", "reset")
+    assert ok and (await get(db))["template"] == DEFAULT_SETTINGS["template"]
+
+
+async def test_template_unknown_variables_are_reported_but_saved(db):
+    ok, msg = await apply_setting(db, UID, "template", "{title} {nope}")
+    assert ok and "{nope}" in msg and "Unknown variables" in msg
+    assert (await get(db))["template"] == "{title} {nope}"
+
+
+async def test_caption_set_validate_reset(db):
+    ok, msg = await apply_setting(db, UID, "caption", "<b>{filename}</b> · {size}")
+    assert ok and (await get(db))["caption"] == "<b>{filename}</b> · {size}"
+    assert "Unknown" not in msg
+    assert (await apply_setting(db, UID, "caption", "x" * 801))[0] is False
+    assert (await apply_setting(db, UID, "caption", ""))[0] is False
+    ok, msg = await apply_setting(db, UID, "caption", "{bogus}")
+    assert ok and "{bogus}" in msg
+    ok, _ = await apply_setting(db, UID, "caption", "reset")
+    assert ok and (await get(db))["caption"] == "{filename}"
+
+
+async def test_remove_words(db):
+    ok, msg = await apply_setting(db, UID, "remove", "@Chan, [Group]\n www.site.com ,, ")
+    assert ok
+    assert (await get(db))["remove_words"] == ["@Chan", "[Group]", "www.site.com"]
+    assert (await apply_setting(db, UID, "remove", " , ,"))[0] is False
+    assert (await apply_setting(db, UID, "remove", ", ".join(f"w{i}" for i in range(51))))[0] is False
+    assert (await apply_setting(db, UID, "remove", "x" * 61))[0] is False
+    ok, _ = await apply_setting(db, UID, "remove", "off")
+    assert ok and (await get(db))["remove_words"] == []
+
+
+@pytest.mark.parametrize("kind", sorted(META_KINDS))
+async def test_every_metadata_field_can_be_set_and_cleared(db, kind):
+    field = META_KINDS[kind]
+    ok, msg = await apply_setting(db, UID, kind, f"{field} value")
+    assert ok and (await get(db))["meta"][field] == f"{field} value"
+    assert "Metadata is Off" in msg  # reminder that nothing applies until it is switched on
+    await db.update_settings(UID, metadata_on=True)
+    ok, msg = await apply_setting(db, UID, kind, "another")
+    assert ok and "Metadata is Off" not in msg
+    ok, _ = await apply_setting(db, UID, kind, "off")
+    assert ok and (await get(db))["meta"][field] == ""
+
+
+async def test_metadata_value_validation(db):
+    assert (await apply_setting(db, UID, "mt_title", ""))[0] is False
+    ok, msg = await apply_setting(db, UID, "mt_title", "x" * 201)
+    assert not ok and "too long" in msg
+    assert (await get(db))["meta"]["title"] == ""
+
+
+async def test_meta_commands_map_to_known_kinds():
+    assert set(META_COMMANDS.values()) == set(META_KINDS)
+
+
+async def test_metadata_values_are_html_escaped_in_the_reply(db):
+    ok, msg = await apply_setting(db, UID, "mt_title", "<script>")
+    assert ok and "<script>" not in msg and "&lt;script&gt;" in msg
+
+
+@pytest.mark.parametrize("kind", ["keep_audio", "keep_subtitle"])
+async def test_keep_tracks_by_language_names_keeps_order_and_enables_metadata(db, kind):
+    assert (await get(db))["metadata_on"] is False
+    ok, msg = await apply_setting(db, UID, kind, "English, Japanese")
+    assert ok
+    s = await get(db)
+    assert s[kind] == ["english", "japanese"]
+    assert s["metadata_on"] is True and "turned it On" in msg
+    ok, msg = await apply_setting(db, UID, kind, "2 1")
+    assert ok and (await get(db))[kind] == ["2", "1"] and "turned it On" not in msg
+    ok, msg = await apply_setting(db, UID, kind, "off")
+    assert ok and (await get(db))[kind] == [] and "all tracks are kept" in msg
+
+
+async def test_keep_tracks_rejects_bad_input_without_changing_anything(db):
+    await apply_setting(db, UID, "keep_audio", "english")
+    for bad in ("0", "1 english 0", "***", "   ", "a" * 30, "1 2 3 4 5 6 7 8 9 10 11 12 13"):
+        ok, msg = await apply_setting(db, UID, "keep_audio", bad)
+        assert not ok and msg.startswith("❌"), bad
+        assert (await get(db))["keep_audio"] == ["english"]
+
+
+async def test_keep_tracks_duplicates_are_collapsed(db):
+    await apply_setting(db, UID, "keep_audio", "english eng English 2 2")
+    assert (await get(db))["keep_audio"] == ["english", "eng", "2"]
+
+
+async def test_unknown_kind_raises(db):
+    with pytest.raises(ValueError):
+        await apply_setting(db, UID, "nonsense", "x")
+
+
+def test_parse_channel():
+    assert parse_channel("-1001234567890") == (True, -1001234567890, "")
+    assert parse_channel("12345") == (True, 12345, "")
+    assert parse_channel("off") == (True, None, "")
+    ok, cid, err = parse_channel("@mychannel")
+    assert not ok and cid is None and "numeric" in err
+    assert parse_channel("12")[0] is False
+
+
+def test_preview_template_renders_sample():
+    out = preview_template("{title} [{quality}]")
+    assert "Preview" in out and "<code>" in out and "[" in out

tests/test_sysinfo.py

@@ -0,0 +1,72 @@
+import pytest
+
+from bot import sysinfo
+
+
+def test_parse_cpu_max():
+    assert sysinfo.parse_cpu_max("200000 100000") == 2.0
+    assert sysinfo.parse_cpu_max("max 100000") is None
+    assert sysinfo.parse_cpu_max("garbage") is None
+    assert sysinfo.parse_cpu_max(None) is None
+
+
+def test_parse_mem_limit():
+    assert sysinfo.parse_mem_limit("17179869184") == 17179869184
+    assert sysinfo.parse_mem_limit("max") is None
+    assert sysinfo.parse_mem_limit("9223372036854771712") is None  # cgroup v1 "unlimited"
+    assert sysinfo.parse_mem_limit(None) is None
+
+
+def test_parse_stat_value():
+    text = "usage_usec 12345\nuser_usec 1\ninactive_file 99"
+    assert sysinfo.parse_stat_value(text, "usage_usec") == 12345
+    assert sysinfo.parse_stat_value(text, "inactive_file") == 99
+    assert sysinfo.parse_stat_value(text, "missing") is None
+
+
+@pytest.fixture
+def fake_cgroup(tmp_path, monkeypatch):
+    (tmp_path / "cpu.max").write_text("200000 100000\n")
+    (tmp_path / "memory.max").write_text("17179869184\n")
+    (tmp_path / "memory.current").write_text("3000000000\n")
+    (tmp_path / "memory.stat").write_text("anon 1\ninactive_file 1000000000\n")
+    (tmp_path / "cpu.stat").write_text("usage_usec 1000000\n")
+    monkeypatch.setattr(sysinfo, "CGROUP_ROOT", str(tmp_path))
+    return tmp_path
+
+
+def test_container_memory_uses_cgroup_and_ignores_page_cache(fake_cgroup):
+    used, total = sysinfo.memory_usage()
+    assert used == 2_000_000_000
+    assert total <= 17179869184
+    assert sysinfo.cpu_cores() == 2.0
+
+
+async def test_container_cpu_percent_from_cgroup(fake_cgroup, monkeypatch):
+    calls = {"n": 0}
+    real = sysinfo._cgroup_cpu_usec
+
+    def fake_usec():
+        calls["n"] += 1
+        return 1_000_000 if calls["n"] == 1 else 1_500_000  # 0.5 cpu-seconds over ~0.1s window
+
+    monkeypatch.setattr(sysinfo, "_cgroup_cpu_usec", fake_usec)
+    pct = await sysinfo.cpu_percent(interval=0.1)
+    assert 0 < pct <= 100
+    monkeypatch.setattr(sysinfo, "_cgroup_cpu_usec", real)
+
+
+def test_falls_back_to_psutil_without_cgroup(tmp_path, monkeypatch):
+    monkeypatch.setattr(sysinfo, "CGROUP_ROOT", str(tmp_path / "does-not-exist"))
+    used, total = sysinfo.memory_usage()
+    assert total > 0 and used >= 0
+    assert sysinfo.cpu_cores() >= 1
+
+
+async def test_format_status_and_stats(tmp_path):
+    text = sysinfo.format_status(123.4, 1, "1.45.0")
+    assert "123 ms" in text and "DC 1" in text and "v1.0.0" in text and "Uptime" in text
+    assert "n/a" in sysinfo.format_status(None, None, "x")
+    stats = await sysinfo.format_stats(3, 12, 4_500_000_000, 1, 2, str(tmp_path))
+    for needle in ("Users:</b> 3", "Files renamed", "1 running · 2 waiting", "CPU", "RAM", "Disk", "Network"):
+        assert needle in stats

tests/test_telethon_glue.py

@@ -0,0 +1,106 @@
+"""Exercise the private-Telethon-API glue with real Telethon objects against a dummy TCP server.
+
+The server never speaks MTProto; connecting with an existing auth key does not need
+a handshake, which is enough to prove the constructor/connect/disconnect signatures
+the fast path relies on still match the installed Telethon.
+"""
+import asyncio
+import os
+from types import SimpleNamespace
+
+import pytest
+from telethon import TelegramClient
+from telethon.crypto import AuthKey
+from telethon.sessions import StringSession
+from telethon.tl import types
+
+from bot import fasttransfer as ft
+
+
+@pytest.fixture
+async def server():
+    connections = []
+
+    async def handle(reader, writer):
+        connections.append(writer)
+        try:
+            await reader.read()
+        finally:
+            writer.close()
+
+    srv = await asyncio.start_server(handle, "127.0.0.1", 0)
+    port = srv.sockets[0].getsockname()[1]
+    yield SimpleNamespace(port=port, connections=connections)
+    srv.close()
+    await srv.wait_closed()
+
+
+async def test_open_transports_on_home_dc(server, monkeypatch):
+    client = TelegramClient(StringSession(), 12345, "0123456789abcdef0123456789abcdef")
+    client.session.set_dc(2, "127.0.0.1", server.port)
+    client.session.auth_key = AuthKey(os.urandom(256))
+    monkeypatch.setattr(
+        TelegramClient, "_config",
+        SimpleNamespace(dc_options=[types.DcOption(id=2, ip_address="127.0.0.1", port=server.port)]),
+        raising=False,
+    )
+
+    transports = await ft.open_transports(client, 2, 3)
+    try:
+        assert len(transports) == 3
+        for _ in range(50):
+            if len(server.connections) == 3:
+                break
+            await asyncio.sleep(0.02)
+        assert len(server.connections) == 3  # three real TCP connections to the "DC"
+    finally:
+        await ft.close_all(transports)
+
+
+async def test_get_file_request_is_built_with_current_tl_signature():
+    from telethon.tl.functions.upload import GetFileRequest, SaveBigFilePartRequest
+
+    loc = types.InputDocumentFileLocation(id=1, access_hash=2, file_reference=b"r", thumb_size="")
+    req = GetFileRequest(location=loc, offset=1024 * 1024, limit=1024 * 1024)
+    assert req.offset == 1024 * 1024 and req.limit == 1024 * 1024
+    part = SaveBigFilePartRequest(5, 0, 3, b"abc")
+    assert (part.file_id, part.file_part, part.file_total_parts, part.bytes) == (5, 0, 3, b"abc")
+    # and both serialise (catches wrong field types early)
+    bytes(req)
+    bytes(part)
+
+
+async def test_document_location_helper():
+    from telethon import utils
+
+    doc = types.Document(
+        id=1, access_hash=2, file_reference=b"x", date=None, mime_type="video/x-matroska", size=10, dc_id=4, attributes=[]
+    )
+    dc_id, location = utils.get_input_location(doc)
+    assert dc_id == 4 and isinstance(location, types.InputDocumentFileLocation)
+
+
+async def test_send_file_accepts_input_file_big_with_explicit_attributes():
+    """send_file(file=InputFileBig, attributes=..., mime_type=...) must keep our filename/video attributes."""
+    from telethon import utils
+
+    big = types.InputFileBig(id=1, parts=3, name="disk-name.mkv")
+    attrs, mime = utils.get_attributes(
+        big,
+        mime_type="video/x-matroska",
+        attributes=[
+            types.DocumentAttributeFilename("[S01E05] Show [1080p].mkv"),
+            types.DocumentAttributeVideo(duration=1420, w=1920, h=1080, supports_streaming=True),
+        ],
+        force_document=False,
+    )
+    by_type = {type(a): a for a in attrs}
+    assert by_type[types.DocumentAttributeFilename].file_name == "[S01E05] Show [1080p].mkv"
+    video = by_type[types.DocumentAttributeVideo]
+    assert (video.duration, video.w, video.h) == (1420, 1920, 1080)
+    assert mime == "video/x-matroska"
+
+    attrs, _ = utils.get_attributes(
+        big, mime_type="video/x-matroska", attributes=[types.DocumentAttributeFilename("n.mkv")], force_document=True
+    )
+    assert types.DocumentAttributeVideo not in {type(a) for a in attrs}  # as a document: no video attribute

tests/test_web_main.py

@@ -0,0 +1,200 @@
+import asyncio
+import dataclasses
+import socket
+from types import SimpleNamespace
+
+import aiohttp
+import pytest
+from aiohttp.test_utils import TestClient, TestServer
+from telethon import functions
+from telethon.crypto import AuthKey
+
+import bot.main as bot_main
+from bot import __version__
+from bot.config import load_config
+from bot.db import Database
+from bot.web import make_app, start_web
+
+from .tgfakes import FakeClient
+
+
+def free_port() -> int:
+    with socket.socket() as s:
+        s.bind(("127.0.0.1", 0))
+        return s.getsockname()[1]
+
+
+# ---------------------------------------------------------------------------
+# health server
+# ---------------------------------------------------------------------------
+
+
+async def test_health_endpoints_answer_get_and_head():
+    async with TestClient(TestServer(make_app())) as client:
+        r = await client.get("/")
+        assert r.status == 200 and "running" in await r.text()
+        assert (await client.head("/")).status == 200  # cron pingers often use HEAD
+        r = await client.get("/health")
+        body = await r.json()
+        assert r.status == 200 and body["status"] == "ok" and body["version"] == __version__
+        assert body["uptime_seconds"] >= 0
+        assert (await client.get("/nope")).status == 404
+
+
+async def test_start_web_listens_on_the_given_port():
+    port = free_port()
+    runner = await start_web(port, host="127.0.0.1")
+    try:
+        async with aiohttp.ClientSession() as http:
+            async with http.get(f"http://127.0.0.1:{port}/health") as r:
+                assert r.status == 200
+    finally:
+        await runner.cleanup()
+
+
+# ---------------------------------------------------------------------------
+# start-up helpers
+# ---------------------------------------------------------------------------
+
+
+def test_clean_temp_dir_removes_only_job_leftovers(tmp_path):
+    root = tmp_path / "work"
+    (root / "job1").mkdir(parents=True)
+    (root / "job1" / "movie.mkv").write_bytes(b"1")
+    (root / "tracks5_6").mkdir()
+    (root / "tracks5_6" / "probe.mkv").write_bytes(b"2")
+    (root / "other").mkdir()
+    (root / "keep.txt").write_text("k")
+    bot_main.clean_temp_dir(str(root))
+    assert sorted(p.name for p in root.iterdir()) == ["keep.txt", "other"]
+
+
+def test_clean_temp_dir_creates_a_missing_directory(tmp_path):
+    bot_main.clean_temp_dir(str(tmp_path / "a" / "b"))
+    assert (tmp_path / "a" / "b").is_dir()
+
+
+def test_main_exits_with_status_2_when_configuration_is_missing(monkeypatch, capsys):
+    for key in ("API_ID", "API_HASH", "BOT_TOKEN", "OWNER_ID"):
+        monkeypatch.delenv(key, raising=False)
+    with pytest.raises(SystemExit) as exc:
+        bot_main.main()
+    assert exc.value.code == 2
+    assert "Missing required environment variables" in capsys.readouterr().err
+
+
+class FakeTG:
+    created: list = []
+
+    def __init__(self, session, api_id, api_hash, **kw):
+        self.session, self.api_id, self.api_hash, self.kw = session, api_id, api_hash, kw
+        self.had_key = bool(session.auth_key)
+        self.started_with = None
+        FakeTG.created.append(self)
+
+    async def start(self, bot_token=None):
+        self.started_with = bot_token
+        if not self.session.auth_key:  # a fresh login creates an auth key
+            self.session.set_dc(2, "149.154.167.51", 443)
+            self.session.auth_key = AuthKey(b"\x07" * 256)
+        return self
+
+
+@pytest.fixture
+async def login(tmp_path, monkeypatch):
+    FakeTG.created = []
+    monkeypatch.setattr("telethon.TelegramClient", FakeTG)
+    cfg = load_config({"API_ID": "11", "API_HASH": "hash", "BOT_TOKEN": "1234:abc", "OWNER_ID": "1"})
+    db = Database(f"sqlite+aiosqlite:///{tmp_path}/login.db")
+    await db.init()
+    yield SimpleNamespace(cfg=cfg, db=db)
+    await db.close()
+
+
+async def test_first_login_saves_the_session_and_later_starts_reuse_it(login):
+    first = await bot_main.build_client(login.cfg, login.db)
+    assert not first.had_key and first.started_with == "1234:abc" and (first.api_id, first.api_hash) == (11, "hash")
+    assert first.kw["connection_retries"] == -1 and first.kw["auto_reconnect"] is True
+    assert await login.db.kv_get("session") and await login.db.kv_get("session_bot") == "1234"
+
+    second = await bot_main.build_client(login.cfg, login.db)  # e.g. after the Space restarted
+    assert second.had_key and second.session.dc_id == 2
+
+
+async def test_a_saved_session_of_another_bot_is_not_reused(login):
+    await bot_main.build_client(login.cfg, login.db)
+    other = dataclasses.replace(login.cfg, bot_token="9999:zzz")
+    client = await bot_main.build_client(other, login.db)
+    assert not client.had_key and await login.db.kv_get("session_bot") == "9999"
+
+
+async def test_session_string_setting_wins_over_the_database(login):
+    saved = (await bot_main.build_client(login.cfg, login.db)).session.save()
+    await login.db.kv_delete("session")
+    await login.db.kv_delete("session_bot")
+    cfg = dataclasses.replace(login.cfg, session_string=saved)
+    assert (await bot_main.build_client(cfg, login.db)).had_key
+
+
+# ---------------------------------------------------------------------------
+# whole start-up sequence with a fake Telegram client
+# ---------------------------------------------------------------------------
+
+
+async def test_amain_wires_everything_and_exits_nonzero_if_telegram_disconnects(tmp_path, monkeypatch):
+    port = free_port()
+    env = {
+        "API_ID": "1", "API_HASH": "h", "BOT_TOKEN": "1:t", "OWNER_ID": "1000001", "LOG_CHANNEL": "-1001111111111",
+        "DATABASE_URL": f"sqlite+aiosqlite:///{tmp_path}/main.db", "TEMP_DIR": str(tmp_path / "work"),
+        "PORT": str(port), "FAST_TRANSFER": "0",
+    }
+    for key, value in env.items():
+        monkeypatch.setenv(key, value)
+    (tmp_path / "work" / "job9").mkdir(parents=True)  # leftover of a "crashed" run
+
+    gate = asyncio.Event()
+    client = FakeClient()
+    client.disconnected = False
+
+    async def get_me():
+        return SimpleNamespace(username="rename_bot")
+
+    async def run_until_disconnected():
+        await gate.wait()
+
+    async def disconnect():
+        client.disconnected = True
+
+    client.get_me, client.run_until_disconnected, client.disconnect = get_me, run_until_disconnected, disconnect
+
+    async def fake_build_client(cfg, db):
+        return client
+
+    monkeypatch.setattr(bot_main, "build_client", fake_build_client)
+
+    task = asyncio.ensure_future(bot_main.amain())
+    try:
+        for _ in range(200):  # wait for the "started" notice: everything is wired by then
+            if any("Bot started" in text for _chat, text, _kw in client.sent):
+                break
+            await asyncio.sleep(0.05)
+        else:
+            pytest.fail("the bot never finished starting")
+        async with aiohttp.ClientSession() as http:
+            async with http.get(f"http://127.0.0.1:{port}/health") as r:
+                assert r.status == 200
+        assert len(client.handlers) > 10
+        assert any(isinstance(r, functions.bots.SetBotCommandsRequest) for r in client.requests)
+        assert not (tmp_path / "work" / "job9").exists()
+        assert client.sent[0][0] == -1001111111111
+        gate.set()  # Telegram connection lost -> exit non-zero so the container restarts
+        assert await asyncio.wait_for(task, 10) == 1
+    finally:
+        gate.set()
+        if not task.done():
+            task.cancel()
+    assert client.disconnected
+    with pytest.raises(aiohttp.ClientError):
+        async with aiohttp.ClientSession() as http:
+            async with http.get(f"http://127.0.0.1:{port}/health"):
+                pass

tests/tgfakes.py

@@ -0,0 +1,193 @@
+"""Stand-ins for Telethon events and clients, used by the handler tests.
+
+``dispatch`` pushes an event through the handlers registered on ``FakeClient`` the
+same way Telethon does (every matching builder runs, in registration order), so
+the real event builders, patterns and ``func`` filters are exercised too.
+"""
+from __future__ import annotations
+
+import inspect
+from types import SimpleNamespace
+from typing import Any, List, Optional
+
+from telethon import events
+
+
+def make_file(name: Optional[str] = "Movie.mkv", size: int = 5 * 1024 * 1024, mime: str = "video/x-matroska",
+              ext: Optional[str] = None) -> SimpleNamespace:
+    if ext is None:
+        ext = name[name.rfind("."):] if name and "." in name else ""
+    return SimpleNamespace(name=name, size=size, mime_type=mime, ext=ext)
+
+
+class FakeMessage:
+    def __init__(self, text: str = "", *, mid: int = 1, sender: int = 1, file: Any = None, video: bool = False,
+                 audio: bool = False, photo: bool = False, sticker: bool = False, gif: bool = False,
+                 voice: bool = False, video_note: bool = False, fwd: bool = False, out: bool = False):
+        self.id = mid
+        self.message = text
+        self.raw_text = text
+        self.out = out
+        self.fwd_from = object() if fwd else None
+        self.sender_id = sender
+        self.file = file
+        self.document = object() if file is not None else None
+        self.video = object() if video else None
+        self.audio = object() if audio else None
+        self.photo = object() if photo else None
+        self.sticker = object() if sticker else None
+        self.gif = object() if gif else None
+        self.voice = object() if voice else None
+        self.video_note = object() if video_note else None
+        self.media = object() if (file is not None or photo) else None
+
+
+def document_message(name: str = "Movie.mkv", size: int = 5 * 1024 * 1024, *, mid: int = 10, caption: str = "",
+                     video: bool = True, mime: str = "video/x-matroska") -> FakeMessage:
+    return FakeMessage(caption, mid=mid, file=make_file(name, size, mime), video=video)
+
+
+class FakeEvent:
+    """A ``NewMessage`` event."""
+
+    def __init__(self, sender: int, text: str = "", *, message: Optional[FakeMessage] = None, reply: Any = None,
+                 mid: int = 1, chat: Optional[int] = None, private: bool = True, photo_bytes: Optional[bytes] = None):
+        self.message = message if message is not None else FakeMessage(text, mid=mid, sender=sender)
+        self.message.sender_id = sender
+        self.sender_id = sender
+        self.chat_id = sender if chat is None else chat
+        self.is_private = private
+        self.id = self.message.id
+        self.raw_text = self.message.raw_text
+        self.pattern_match = None
+        self._reply = reply
+        self.out: List[tuple] = []  # every respond()/reply(): (text, buttons, kwargs)
+        self.deleted = False
+        self.photo_bytes = photo_bytes
+
+    async def respond(self, text: Optional[str] = None, **kw: Any) -> SimpleNamespace:
+        self.out.append((text, kw.get("buttons"), kw))
+        return SimpleNamespace(id=1000 + len(self.out), text=text)
+
+    reply = respond
+
+    async def get_reply_message(self) -> Any:
+        return self._reply
+
+    async def delete(self) -> None:
+        self.deleted = True
+
+    async def download_media(self, file: Any = None) -> Optional[bytes]:
+        return self.photo_bytes
+
+    @property
+    def texts(self) -> List[str]:
+        return [t or "" for t, _b, _k in self.out]
+
+
+class FakeCallback:
+    """A ``CallbackQuery`` event."""
+
+    def __init__(self, sender: int, data: str, *, msg_id: int = 500, chat: Optional[int] = None, photo: bool = False):
+        self.sender_id = sender
+        self.chat_id = sender if chat is None else chat
+        self.data = data.encode()
+        self.message_id = msg_id
+        self.id = 9
+        self.query = SimpleNamespace(data=self.data, chat_instance=1, msg_id=msg_id)
+        self.edits: List[tuple] = []
+        self.answers: List[tuple] = []
+        self.deleted = False
+        self._photo = photo
+        self.delete_error: Optional[Exception] = None
+
+    async def edit(self, text: Optional[str] = None, **kw: Any) -> None:
+        self.edits.append((text, kw.get("buttons")))
+
+    async def answer(self, message: Optional[str] = None, *, alert: bool = False, **kw: Any) -> None:
+        self.answers.append((message, alert))
+
+    async def delete(self) -> None:
+        if self.delete_error is not None:
+            raise self.delete_error
+        self.deleted = True
+
+    async def get_message(self) -> SimpleNamespace:
+        return SimpleNamespace(photo=object() if self._photo else None)
+
+    @property
+    def alerts(self) -> List[str]:
+        return [m or "" for m, a in self.answers if a]
+
+    @property
+    def toasts(self) -> List[str]:
+        return [m or "" for m, a in self.answers if m and not a]
+
+
+class FakeClient:
+    def __init__(self) -> None:
+        self.handlers: List[tuple] = []
+        self.parse_mode = None
+        self.session = SimpleNamespace(dc_id=1)
+        self.sent: List[tuple] = []     # send_message(entity, text, **kw)
+        self.files: List[tuple] = []    # send_file(entity, file, **kw)
+        self.edited: List[tuple] = []   # edit_message(entity, text, **kw)
+        self.requests: List[Any] = []   # raw MTProto requests
+        self.bad_entities: set = set()
+        self.fail_send_file = False
+
+    def add_event_handler(self, callback: Any, event: Any = None) -> None:
+        self.handlers.append((callback, event))
+
+    async def __call__(self, request: Any) -> Any:
+        self.requests.append(request)
+        return True
+
+    async def get_input_entity(self, entity: Any) -> Any:
+        if entity in self.bad_entities:
+            raise ValueError(f"Could not find the input entity for {entity!r}")
+        return SimpleNamespace(id=entity)
+
+    async def send_message(self, entity: Any, text: str = "", **kw: Any) -> SimpleNamespace:
+        self.sent.append((entity, text, kw))
+        return SimpleNamespace(id=2000 + len(self.sent))
+
+    async def send_file(self, entity: Any, file: Any, **kw: Any) -> SimpleNamespace:
+        if self.fail_send_file:
+            raise RuntimeError("cannot send file")
+        self.files.append((entity, file, kw))
+        return SimpleNamespace(id=3000 + len(self.files))
+
+    async def edit_message(self, entity: Any, message: Any = None, text: Optional[str] = None, **kw: Any) -> None:
+        if text is None and isinstance(message, str):
+            text, message = message, None
+        self.edited.append((entity, text, {**kw, "message": message}))
+
+
+async def dispatch(client: FakeClient, event: Any) -> None:
+    """Run ``event`` through the registered handlers like Telethon's dispatcher."""
+    for callback, builder in list(client.handlers):
+        if isinstance(builder, events.CallbackQuery) != isinstance(event, FakeCallback):
+            continue  # Telethon builds one event per builder type
+        builder.resolved = True
+        passed = builder.filter(event)
+        if inspect.isawaitable(passed):
+            passed = await passed
+        if not passed:
+            continue
+        try:
+            await callback(event)
+        except events.StopPropagation:
+            break
+
+
+def button_rows(buttons: Any) -> List[List[tuple]]:
+    """Telethon buttons -> ``[[(text, data_str), ...], ...]``."""
+    out = []
+    for row in buttons or []:
+        out.append([(b.text, b.type.data.decode()) for b in row])
+    return out
+
+
+def flat_buttons(buttons: Any) -> List[tuple]:
+    return [b for row in button_rows(buttons) for b in row]