Automated sync from GitHub

.gitattributes

@@ -1,8 +1,8 @@
-*.png filter=lfs diff=lfs merge=lfs -text
-*.ttf filter=lfs diff=lfs merge=lfs -text
 *.otf 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

Dockerfile

@@ -1,10 +1,22 @@
 FROM python:3.12-slim
 
-# ffmpeg/ffprobe: metadata + track keep/reorder (stream copy, no re-encoding)
+# ffmpeg/ffprobe: metadata + track keep/reorder (stream copy, no re-encoding); curl: fetches the Speedtest CLI below
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends ffmpeg ca-certificates \
+    && apt-get install -y --no-install-recommends ffmpeg ca-certificates curl \
     && rm -rf /var/lib/apt/lists/*
 
+# Ookla's official Speedtest CLI for /speed. Optional: if the download fails the build goes on and /speed
+# uses the speedtest-cli Python package (also Ookla) instead.
+RUN set -eux; \
+    case "$(dpkg --print-architecture)" in amd64) arch=x86_64 ;; arm64) arch=aarch64 ;; *) arch="" ;; esac; \
+    if [ -n "$arch" ]; then \
+        curl -fsSL --retry 3 --max-time 120 -o /tmp/speedtest.tgz "https://install.speedtest.net/app/cli/ookla-speedtest-1.2.0-linux-${arch}.tgz" \
+        && tar -xzf /tmp/speedtest.tgz -C /tmp speedtest \
+        && install -m 0755 /tmp/speedtest /usr/local/bin/ookla-speedtest \
+        || echo "Ookla Speedtest CLI not installed: /speed will use the speedtest-cli package"; \
+        rm -f /tmp/speedtest.tgz /tmp/speedtest; \
+    fi
+
 # Hugging Face Spaces run Docker containers as user 1000
 RUN useradd -m -u 1000 user
 USER user

bot/app.py

@@ -2,36 +2,47 @@
 from __future__ import annotations
 
 import asyncio
+import base64
 import html
 import io
+import json
 import logging
 import random
 import re
 import shutil
 import time
 from dataclasses import dataclass
+from datetime import timezone
 from pathlib import Path
 from typing import Any, Awaitable, Callable, Dict, List, Optional, Set
 
 import telethon
 from telethon import errors, events, functions, types
+from telethon.tl.custom import Button
 
 from . import fasttransfer as transfer
-from . import media, panels, sysinfo
+from . import media, mediainfo, panels, speed, sysinfo
 from .config import Config
-from .db import Database
-from .parser import build_manual_name, compute_new_name, missing_variables
-from .pipeline import Renamer, original_name_of, source_ext
+from .db import MAX_FORMATS, Database
+from .errors import FormatError
+from .formats import FIELD_KINDS, FormatSettings, validate_name
+from .parser import compute_new_name, missing_variables, parse_caption, parse_info, split_ext
+from .pipeline import PROBE_EXTS, Renamer, original_name_of, source_ext
 from .queue import Job, JobQueue
+from .sequence import SeqItem, SequenceState, analyse, format_report
 from .settings_ops import META_COMMANDS, apply_setting, parse_channel, preview_template
-from .utils import clip, esc, human_size
+from .telegraph import Telegraph, TelegraphError
+from .utils import clip, esc, human_size, human_uptime
 
 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"),
+    ("rename", "Rename files with a saved format"),
+    ("formats", "Create and edit your saved formats"),
+    ("sequence", "Collect files to sort by episode"),
+    ("sort", "Sort the collected files by episode"),
     ("mode", "Choose Filename or Caption mode"),
     ("template", "Set the filename template"),
     ("caption", "Set the caption template"),
@@ -40,22 +51,42 @@ COMMANDS = [
     ("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)"),
+    ("check", "See what I can read from a file (reply to it)"),
+    ("mediainfo", "Full media details of a file on Telegraph (reply to it)"),
+    ("ethumb", "Extract the thumbnail of a file or video"),
+    ("resize", "Resize an image, for thumbnails"),
     ("thumb", "View your thumbnail"),
     ("delthumb", "Delete your thumbnail"),
     ("queue", "Show your queued files"),
     ("cancel", "Cancel your current job"),
+    ("speed", "Test the bot's internet speed (Ookla)"),
     ("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"}
+OWNER_COMMANDS = {"addadmin", "deladmin", "admins", "smedia"}
 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"}
+PANEL_NAMES = {"home", "rename", "cap", "meta", "tool", "ftype", "help", "admin", "formats"}
 QUEUE_SETTLE = 1.5  # seconds an idle worker waits so files sent together are queued in message order
+ONE_FILE_WAIT = 600  # seconds the bot waits for the file after /rename (or /ethumb ...) before forgetting about it
+ONE_SHOT_GRACE = 8  # seconds after a one-file command during which further files get a hint, not an auto-rename
+ONE_SHOT_TAKES = {  # what each one-file command consumes; further files of that kind sent right after it are skipped
+    "rename": {"doc"}, "ethumb": {"doc"}, "resize": {"doc", "photo"}, "smedia": {"doc", "photo", "gif"},
+}
+ETHUMB_FRAME_WIDTH = 1280
+START_MEDIA_MAX_BYTES = 10 * 1024 * 1024  # biggest /start picture or GIF; a copy of it is kept in the database
+START_IMAGE_BOX = 1280  # pictures are shrunk to fit this box, as Telegram does with photos
+RESIZE_MAX_BYTES = 20 * 1024 * 1024
+SEQUENCE_WAIT = 1800  # seconds /sequence keeps the collected files without a new one arriving
+SEQUENCE_MAX = 200  # files one /sequence collects
+SEQUENCE_STATUS_DELAY = 1.2  # seconds without a new file before "N files collected" is sent
+SORT_GAP = 0.3  # seconds between the files /sort sends back
+SORT_MAX_WAIT = 120  # a Telegram flood wait longer than this (seconds) stops /sort instead of being waited out
+SORT_PROGRESS_EVERY = 10  # files between two updates of the "Sorting…" message
 TRACKS_PROBE_BYTES = 12 * 1024 * 1024
 TRACKS_FULL_LIMIT = 700 * 1024 * 1024
 
@@ -68,12 +99,27 @@ class Pending:
     back: str
     is_photo: bool
     expires: float
+    fid: int = 0  # the saved format a "fmt:*" prompt is about (0 = one that is being created)
+
+
+@dataclass
+class Mode:
+    """What a user's next files are for: a /rename format session, /sequence, /ethumb, /resize or /smedia."""
+
+    kind: str
+    ttl: float
+    expires: float
+    data: Any = None
+    dropped: str = ""  # a note about what starting this mode threw away, for the reply that announces it
 
 
 def cmd_pattern(name: str) -> "re.Pattern[str]":
     return re.compile(rf"(?is)^/{name}(?:@\w+)?(?:\s+(.*))?$")
 
 
+MEDIAINFO_CAPTION = cmd_pattern("mediainfo")  # a file sent with this as its caption is for /mediainfo, not for renaming
+
+
 def visible_len(html_text: str) -> int:
     return len(html.unescape(re.sub(r"<[^>]+>", "", html_text)))
 
@@ -89,6 +135,51 @@ def is_renameable(message: Any) -> bool:
     )
 
 
+def is_image(message: Any) -> bool:
+    """A photo, or a file that is a still picture (not a GIF animation)."""
+    if getattr(message, "photo", None) is not None:
+        return True
+    f = getattr(message, "file", None)
+    return bool(
+        getattr(message, "document", None) is not None and not getattr(message, "gif", None)
+        and f is not None and (f.mime_type or "").startswith("image/")
+    )
+
+
+def sent_as(message: Any) -> str:
+    """How Telegram labels the file: a video, an audio file, a voice message ..., or a plain document."""
+    for attr, label in (
+        ("voice", "Voice message"), ("video_note", "Video message"), ("gif", "GIF"), ("sticker", "Sticker"),
+        ("video", "Video"), ("audio", "Audio"),
+    ):
+        if getattr(message, attr, None) is not None:
+            return label
+    return "Document"
+
+
+def is_playable(message: Any, name: str) -> bool:
+    """A file that should hold audio or video streams, going by its MIME type and extension."""
+    mime = (getattr(message.file, "mime_type", "") or "").lower()
+    return mime.startswith(("video/", "audio/")) or source_ext(message, name).lower() in PROBE_EXTS
+
+
+def telegram_facts(message: Any, caption: bool = True) -> Dict[str, str]:
+    """What Telegram knows about the file, for the "Telegram" part of the /mediainfo page."""
+    date = getattr(message, "date", None)
+    stamp = ""
+    if date is not None:
+        if date.tzinfo is None:
+            date = date.replace(tzinfo=timezone.utc)
+        stamp = date.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    return {
+        "mime": getattr(message.file, "mime_type", "") or "",
+        "sent_as": sent_as(message),
+        "sent_on": stamp,
+        "dc": str(getattr(message.document, "dc_id", "") or ""),
+        "caption": clip((message.raw_text or "").strip(), 500) if caption else "",
+    }
+
+
 class App:
     PENDING_TTL = 300
 
@@ -98,6 +189,12 @@ class App:
         self.db = db
         self.admins: Set[int] = set(cfg.admin_ids)
         self.pending: Dict[int, Pending] = {}
+        self.modes: Dict[int, Mode] = {}
+        self._recent: Dict[int, List[Any]] = {}  # uid -> [command, finished_at, hint_sent] of the last one-file command
+        self._sorting: Dict[int, asyncio.Event] = {}  # users whose /sort is sending files; set to stop it
+        self._speed_lock = asyncio.Lock()  # one speed test at a time
+        self.telegraph = Telegraph(self._load_telegraph_token, self._save_telegraph_token)
+        self._tasks: Set["asyncio.Future[Any]"] = set()
         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, settle=QUEUE_SETTLE)
         self._warned: Set[int] = set()
@@ -123,6 +220,8 @@ class App:
         self.queue.start()
 
     async def shutdown(self) -> None:
+        for task in list(self._tasks):
+            task.cancel()
         await self.queue.stop()
 
     async def _set_commands(self) -> None:
@@ -195,6 +294,7 @@ class App:
             )
         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_gif), events.NewMessage(incoming=True, func=lambda e: e.is_private and e.message.gif 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)))
@@ -208,14 +308,17 @@ class App:
 
     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,
+            "start": self.cmd_start, "help": self.cmd_help, "rename": self.cmd_rename, "formats": self.cmd_formats,
+            "sequence": self.cmd_sequence, "sort": self.cmd_sort, "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,
+            "tracks": self.cmd_tracks, "check": self.cmd_check, "mediainfo": self.cmd_mediainfo,
+            "ethumb": self.cmd_ethumb, "resize": self.cmd_resize,
+            "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,
+            "cancel": self.cmd_cancel, "speed": self.cmd_speed, "status": self.cmd_status, "stats": self.cmd_stats,
+            "addadmin": self.cmd_addadmin, "deladmin": self.cmd_deladmin, "admins": self.cmd_admins, "smedia": self.cmd_smedia,
         }
         for command, kind in META_COMMANDS.items():
             table[command] = self._cmd_meta_field(command, kind)
@@ -246,6 +349,8 @@ class App:
             return panels.filetype(s)
         if name == "help":
             return panels.help_panel()
+        if name == "formats":
+            return panels.formats_menu(await self.db.list_formats(uid), MAX_FORMATS)
         if name == "admin":
             return panels.admin(
                 self.cfg.owner_id, sorted(self.admins), self.queue.running, self.queue.waiting, self.cfg.log_channel
@@ -268,19 +373,70 @@ class App:
         except errors.MessageNotModifiedError:
             pass
 
+    # ------------------------------------------------------------------ modes
+    def _mode(self, uid: int, *kinds: str) -> Optional[Mode]:
+        """The user's active mode (of one of ``kinds`` if given); an expired one is dropped."""
+        mode = self.modes.get(uid)
+        if mode is not None and mode.expires < time.time():
+            self._end_mode(uid)
+            return None
+        if mode is None or (kinds and mode.kind not in kinds):
+            return None
+        return mode
+
+    def _start_mode(self, uid: int, kind: str, ttl: float, data: Any = None) -> Mode:
+        previous = self._end_mode(uid)
+        mode = Mode(kind=kind, ttl=ttl, expires=time.time() + ttl, data=data)
+        if previous is not None and previous.kind == "sequence" and previous.expires >= time.time() and previous.data.items:
+            mode.dropped = f"⚠️ Your /sequence with {len(previous.data.items)} file(s) was discarded."
+        self.modes[uid] = mode
+        return mode
+
+    def _end_mode(self, uid: int) -> Optional[Mode]:
+        mode = self.modes.pop(uid, None)
+        if mode is not None and isinstance(mode.data, SequenceState):
+            mode.data.closed = True
+        return mode
+
+    def _spawn(self, coro: Awaitable[Any]) -> "asyncio.Future[Any]":
+        task = asyncio.ensure_future(coro)
+        self._tasks.add(task)
+        task.add_done_callback(self._tasks.discard)
+        return task
+
+    def _consume(self, uid: int, kind: str) -> Optional[Mode]:
+        """Take the user's one-file mode.  Nothing awaits in here, so of several files that arrive together only one gets it."""
+        mode = self._mode(uid, kind)
+        if mode is None:
+            return None
+        del self.modes[uid]
+        self._recent[uid] = [kind, time.time(), False]
+        return mode
+
+    def _extra_file_hint(self, uid: int, via: str = "doc") -> Optional[str]:
+        """After a one-file command: ``""`` for a further file to skip silently, a hint for the first one, ``None`` once the grace is over.
+
+        ``via`` is how the file arrived (``doc``, ``photo`` or ``gif``); only files the command itself would have taken are skipped.
+        """
+        rec = self._recent.get(uid)
+        if rec is None:
+            return None
+        if time.time() - rec[1] > ONE_SHOT_GRACE:
+            del self._recent[uid]
+            return None
+        if via not in ONE_SHOT_TAKES.get(rec[0], {"doc"}):
+            return None
+        if rec[2]:
+            return ""
+        rec[2] = True
+        return f"ℹ️ /{rec[0]} handles one file at a time, so I skipped this one. Send /{rec[0]} again for the next file."
+
     # --------------------------------------------------------------- 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)
+        if not await self._send_start_media(event.chat_id, text, rows):
+            await self._reply(event, text, rows)
 
     async def cmd_help(self, event: Any) -> None:
         text, _ = panels.help_panel()
@@ -439,6 +595,16 @@ class App:
             await self._reply(event, "You have no thumbnail.")
 
     async def on_photo(self, event: Any) -> None:
+        uid = event.sender_id
+        p = self.pending.get(uid)
+        if not (p is not None and p.kind == "fmt:thumb" and p.expires >= time.time()):
+            if await self._image_mode(event):
+                return
+            hint = self._extra_file_hint(uid, "photo")
+            if hint is not None:
+                if hint:
+                    await self._reply(event, hint)
+                return
         raw = await event.download_media(bytes)
         if not raw:
             await self._reply(event, "❌ I couldn't download that photo.")
@@ -448,22 +614,208 @@ class App:
         except Exception:  # noqa: BLE001
             await self._reply(event, "❌ I couldn't read that image.")
             return
+        if p is not None and p.kind == "fmt:thumb" and p.expires >= time.time():
+            await self._format_thumb_saved(event, p, thumb)
+            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")]])
 
+    async def on_gif(self, event: Any) -> None:
+        if await self._image_mode(event):
+            return
+        hint = self._extra_file_hint(event.sender_id, "gif")
+        if hint:
+            await self._reply(event, hint)
+
     # ------------------------------------------------------------ rename flow
+    async def cmd_formats(self, event: Any) -> None:
+        self.pending.pop(event.sender_id, None)
+        text, rows = await self.panel(event.sender_id, "formats")
+        await self._reply(event, text, rows)
+
     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)
+        uid = event.sender_id
+        self.pending.pop(uid, None)
+        text, rows = panels.rename_picker(await self.db.list_formats(uid))
+        await self._reply(event, text, rows)
 
     async def on_media(self, event: Any) -> None:
+        uid = event.sender_id
+        if MEDIAINFO_CAPTION.match(event.raw_text or ""):
+            return  # cmd_mediainfo has it
+        mode = self._consume(uid, "rename")
+        if mode is not None:
+            await self._media_rename(event, mode)
+            return
+        mode = self._consume(uid, "ethumb")
+        if mode is not None:
+            await self._send_thumbnail(event, event.message)
+            return
+        if await self._image_mode(event):
+            return
+        mode = self._mode(uid, "sequence")
+        if mode is not None:
+            notice = self._collect(event, mode)
+            if notice:
+                await self._reply(event, notice)
+            return
+        hint = self._extra_file_hint(uid)
+        if hint is not None:
+            if hint:
+                await self._reply(event, hint)
+            return
         await self.enqueue(event, event.message)
 
-    async def enqueue(self, event: Any, msg: Any, manual: Optional[str] = None) -> None:
+    async def _media_rename(self, event: Any, mode: Mode) -> None:
+        fmt = await self.db.get_format(event.sender_id, mode.data["fid"])
+        if fmt is None:
+            await self._reply(event, "⚠️ That format was deleted. Use /rename to pick another one, then send the file again.")
+            return
+        await self.enqueue(event, event.message, fmt=fmt)
+
+    # --------------------------------------------------------- /sequence, /sort
+    async def cmd_sequence(self, event: Any) -> None:
+        uid = event.sender_id
+        self.pending.pop(uid, None)
+        mode = self._mode(uid, "sequence")
+        if mode is not None and mode.data.items:  # a second /sequence must not throw the collected files away
+            mode.expires = time.time() + mode.ttl
+            text, rows = panels.sequence_status(len(mode.data.items), SEQUENCE_MAX)
+            await self._reply(event, "You're already collecting files for a sequence.\n\n" + text, rows)
+            return
+        mode = self._start_mode(uid, "sequence", SEQUENCE_WAIT, SequenceState())
+        text, rows = panels.sequence_intro(SEQUENCE_MAX)
+        await self._reply(event, text + (f"\n\n{mode.dropped}" if mode.dropped else ""), rows)
+
+    def _collect(self, event: Any, mode: Mode) -> Optional[str]:
+        """Add a file to the user's sequence.  Nothing awaits in here, so files that arrive together are all kept."""
+        state: SequenceState = mode.data
+        mode.expires = time.time() + mode.ttl
+        if len(state.items) >= SEQUENCE_MAX:
+            if state.full_noted:
+                return None
+            state.full_noted = True
+            return f"⚠️ That's the limit: {SEQUENCE_MAX} files. Send /sort now, or /cancel to start over."
+        msg = event.message
+        state.items.append(SeqItem(msg_id=msg.id, name=original_name_of(msg), caption=msg.raw_text or ""))
+        state.version += 1
+        if state.task is None or state.task.done():
+            state.task = self._spawn(self._sequence_status(event.chat_id, state))
+        return None
+
+    async def _sequence_status(self, chat_id: int, state: SequenceState) -> None:
+        """Send "N files collected" once the files stop arriving, so it is the newest message in the chat."""
+        try:
+            while not state.closed:
+                seen = state.version
+                await asyncio.sleep(SEQUENCE_STATUS_DELAY)
+                if state.closed:
+                    return
+                if state.version != seen:
+                    continue
+                text, rows = panels.sequence_status(len(state.items), SEQUENCE_MAX)
+                previous = state.status_id
+                sent = await self.client.send_message(chat_id, text, buttons=panels.to_buttons(rows), parse_mode="html")
+                if state.closed:  # /sort or /cancel came while it was being sent
+                    await self._delete_quietly(chat_id, sent.id)
+                    return
+                state.status_id = sent.id
+                if previous is not None:
+                    await self._delete_quietly(chat_id, previous)
+                if state.version == seen:
+                    return
+        except asyncio.CancelledError:
+            raise
+        except Exception:  # noqa: BLE001
+            log.exception("could not send the sequence status")
+
+    async def _delete_quietly(self, chat_id: int, *ids: int) -> None:
+        try:
+            await self.client.delete_messages(chat_id, list(ids))
+        except Exception as exc:  # noqa: BLE001
+            log.debug("could not delete messages %s: %s", ids, exc)
+
+    async def cmd_sort(self, event: Any) -> None:
+        await self._run_sort(event.sender_id, event.chat_id)
+
+    @staticmethod
+    async def _pause(seconds: float) -> None:
+        await asyncio.sleep(seconds)
+
+    async def _send_back(self, chat_id: int, msg: Any) -> None:
+        """Send one collected file again (no re-upload), keeping its caption and formatting."""
+        for attempt in range(3):
+            try:
+                await self.client.send_file(chat_id, msg, caption=msg.raw_text or "", formatting_entities=msg.entities, parse_mode=None)
+                return
+            except errors.FloodWaitError as exc:
+                if attempt == 2 or exc.seconds > SORT_MAX_WAIT:
+                    raise
+                await self._pause(exc.seconds + 1)
+
+    async def _run_sort(self, uid: int, chat_id: int) -> None:
+        say = lambda text, **kw: self.client.send_message(chat_id, text, parse_mode="html", link_preview=False, **kw)  # noqa: E731
+        if uid in self._sorting:
+            await say("⏳ I'm still sorting your last batch. /cancel to stop it.")
+            return
+        mode = self._mode(uid, "sequence")
+        state: Optional[SequenceState] = mode.data if mode is not None else None
+        if state is None or not state.items:
+            await say("Nothing to sort yet. Send /sequence, then the files, then /sort.")
+            return
+        self._end_mode(uid)
+        cancel = self._sorting[uid] = asyncio.Event()
+        total = len(state.items)
+        status = None
+        try:
+            if state.status_id is not None:
+                await self._delete_quietly(chat_id, state.status_id)
+            s = await self.db.get_settings(uid)
+            plan = analyse(state.items, s["mode"])
+            status = await say(f"🔢 <b>Sorting {total} file{'s' if total != 1 else ''}…</b>")
+            fetched = list(await self.client.get_messages(chat_id, ids=[i.msg_id for i in plan.ordered]))
+            fetched += [None] * (len(plan.ordered) - len(fetched))
+
+            sent = 0
+            failed: List[SeqItem] = []
+            note = ""
+            stopped = False
+            for index, (item, msg) in enumerate(zip(plan.ordered, fetched)):
+                if cancel.is_set():
+                    stopped = True
+                    break
+                if msg is None or getattr(msg, "file", None) is None:  # deleted since it was sent
+                    failed.append(item)
+                    continue
+                try:
+                    await self._send_back(chat_id, msg)
+                except errors.FloodWaitError as exc:
+                    note = f"⚠️ Telegram asked me to wait {human_uptime(exc.seconds)} before sending more, so I stopped here."
+                    failed.extend(plan.ordered[index:])
+                    break
+                except Exception as exc:  # noqa: BLE001
+                    log.warning("could not send %s back: %s", item.name, exc)
+                    failed.append(item)
+                    continue
+                sent += 1
+                if sent % SORT_PROGRESS_EVERY == 0 and sent < total:
+                    try:
+                        await self.client.edit_message(status, f"🔢 <b>Sorting…</b> {sent} of {total} sent", parse_mode="html")
+                    except Exception:  # noqa: BLE001
+                        pass
+                if SORT_GAP:
+                    await asyncio.sleep(SORT_GAP)
+            if status is not None:
+                await self._delete_quietly(chat_id, status.id)
+            if stopped:
+                await say(f"⏹ Stopped after {sent} of {total} file{'s' if total != 1 else ''}.")
+                return
+            for chunk in format_report(plan, total, sent, failed, note):
+                await say(chunk)
+        finally:
+            self._sorting.pop(uid, None)
+
+    async def enqueue(self, event: Any, msg: Any, fmt: Optional[Dict[str, Any]] = 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:
@@ -472,29 +824,28 @@ class App:
         s = await self.db.get_settings(uid)
         orig = original_name_of(msg)
         ext = source_ext(msg, orig)
+        template = fmt["template"] if fmt else s["template"]
+        new_name, info = compute_new_name(
+            template=template, mode=s["mode"], original_name=orig, original_ext=ext,
+            caption=msg.raw_text or "", remove_words=s["remove_words"],
+        )
         notes: List[str] = []
-        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"],
+        gaps = missing_variables(template, info)
+        if gaps:
+            where_from = "caption" if s["mode"] == "caption" else "file name"
+            notes.append(
+                "Couldn't find " + ", ".join("{%s}" % g for g in gaps) + f" in the {where_from}, so it is left empty. "
+                "Cancel and change the template if you don't want that."
             )
-            gaps = missing_variables(s["template"], info)
-            if gaps:
-                where_from = "caption" if s["mode"] == "caption" else "file name"
-                notes.append(
-                    "Couldn't find " + ", ".join("{%s}" % g for g in gaps) + f" in the {where_from}, so it is left empty. "
-                    "Cancel and use /rename, or change the template."
-                )
         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), notes=notes, order=event.id,
+            file_name=orig, size=size, new_name=new_name, fmt=fmt, notes=notes, order=event.id,
         )
         ahead = self.queue.running + self.queue.waiting
         where = "starting soon" if ahead == 0 else f"{ahead} ahead of it"
+        used = f"\n🗂 Format: <b>{esc(clip(fmt['name'], 30))}</b>" if fmt else ""
         job.status_msg = await event.reply(
-            f"📥 <b>Queued</b> ({where})\n<code>{esc(clip(new_name, 120))}</code>" + "".join(f"\n⚠️ {esc(n)}" for n in notes),
+            f"📥 <b>Queued</b> ({where}){used}\n<code>{esc(clip(new_name, 120))}</code>" + "".join(f"\n⚠️ {esc(n)}" for n in notes),
             buttons=panels.to_buttons([[("✖ Cancel", f"job:x:{job.id}")]]),
             parse_mode="html",
         )
@@ -528,6 +879,18 @@ class App:
         if not arg and self.pending.pop(uid, None) is not None:
             await self._reply(event, "Cancelled — nothing was changed.")
             return
+        if not arg and uid in self._sorting:
+            self._sorting[uid].set()
+            await self._reply(event, "⏹ Stopping the sort…")
+            return
+        if not arg:
+            mode = self._end_mode(uid)
+            if mode is not None and mode.expires >= time.time():
+                if isinstance(mode.data, SequenceState) and mode.data.status_id is not None:
+                    await self._delete_quietly(event.chat_id, mode.data.status_id)  # its buttons are of no use any more
+                busy = " Send /cancel again to cancel your queued files." if self.queue.for_user(uid) else ""
+                await self._reply(event, self._mode_cancelled_text(mode) + busy)
+                return
         owner_scope = None if self.is_owner(uid) else uid
         if arg.isdigit():
             ok = self.queue.cancel(int(arg), user_id=owner_scope)
@@ -536,42 +899,492 @@ class App:
         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.")
 
+    @staticmethod
+    def _mode_cancelled_text(mode: Mode) -> str:
+        if mode.kind == "sequence":
+            count = len(mode.data.items)
+            return f"⏹ Sequence cancelled. {count} file{'s' if count != 1 else ''} discarded." if count else "⏹ Sequence cancelled."
+        return {
+            "rename": "⏹ Cancelled. Send /rename again to pick a format.",
+            "smedia": "⏹ Cancelled. Send /smedia again to change the start media.",
+        }.get(mode.kind, "Cancelled.")
+
+    # ------------------------------------------------------------------ check
+    async def cmd_check(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 file with /check to see the details I can read from its name and caption.")
+            return
+        s = await self.db.get_settings(event.sender_id)
+        name = original_name_of(reply)
+        caption = reply.raw_text or ""
+        new_name, _info = compute_new_name(
+            template=s["template"], mode=s["mode"], original_name=name, original_ext=source_ext(reply, name),
+            caption=caption, remove_words=s["remove_words"],
+        )
+        text = panels.check_text(s["mode"], parse_info(split_ext(name)[0]), parse_caption(caption), new_name)
+        await event.reply(text, parse_mode="html", link_preview=False)
+
     # ------------------------------------------------------------------ tracks
+    async def _with_file_start(
+        self, event: Any, msg: Any, tag: str,
+        attempt: Callable[[Path], Awaitable[Any]], on_whole: Optional[Callable[[], Awaitable[None]]] = None,
+    ) -> Any:
+        """Run ``attempt(path)`` on the first part of the file; when it gives nothing (an index at the end of an mp4, say) on the whole file.
+
+        The files live in a temporary folder that is removed afterwards.  ``on_whole`` runs before the big download starts.
+        """
+        name = original_name_of(msg)
+        size = int(msg.file.size or 0)
+        tmp_dir = Path(self.cfg.temp_dir) / f"{tag}{event.chat_id}_{event.id}"
+        tmp_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            path = tmp_dir / f"probe{source_ext(msg, name)}"
+            await transfer.download(self.client, msg, path, fast=self.cfg.fast_transfer, connections=2, max_bytes=TRACKS_PROBE_BYTES)
+            result = await attempt(path)
+            if result is None and TRACKS_PROBE_BYTES < size <= TRACKS_FULL_LIMIT:
+                if on_whole is not None:
+                    await on_whole()
+                await transfer.download(self.client, msg, path, fast=self.cfg.fast_transfer, connections=self.cfg.connections)
+                result = await attempt(path)
+            return result
+        finally:
+            shutil.rmtree(tmp_dir, ignore_errors=True)
+
     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
-            )
+
+        async def read(path: Path) -> Optional[media.MediaInfo]:
             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)
+                return None
+            return info if info.streams else None
+
+        async def whole() -> None:
+            await self.client.edit_message(status, "🔎 Reading the tracks (this one needs the whole file)…", parse_mode="html")
+
+        info = await self._with_file_start(event, reply, "tracks", read, whole)
+        if info is None:
+            await self.client.edit_message(status, "❌ I couldn't read any tracks from that file.", parse_mode="html")
+            return
+        text = f"<b>{esc(clip(original_name_of(reply), 80))}</b>\n\n{media.format_tracks(info)}"
+        await self.client.edit_message(status, text[:3900], parse_mode="html")
+
+    # --------------------------------------------------------------- /mediainfo
+    async def _load_telegraph_token(self) -> Optional[str]:
+        return await self.db.kv_get("telegraph_token")
+
+    async def _save_telegraph_token(self, token: str) -> None:
+        if token:
+            await self.db.kv_set("telegraph_token", token)
+        else:
+            await self.db.kv_delete("telegraph_token")
+
+    async def cmd_mediainfo(self, event: Any) -> None:
+        target, own = await event.get_reply_message(), False
+        if target is None or getattr(target, "document", None) is None:
+            target, own = event.message, True  # a file sent with /mediainfo as its caption
+        if getattr(target, "document", None) is None:
+            await self._reply(event, "Reply to a file or video with /mediainfo and I'll put everything MediaInfo can read from it on a Telegraph page.")
+            return
+        status = await self._reply(event, "🔎 Reading the file…")
+        try:
+            await self._mediainfo(event, target, own, status)
+        except Exception:  # noqa: BLE001
+            log.exception("/mediainfo failed")
+            try:
+                await self.client.edit_message(status, "⚠️ Something went wrong while reading that file.", parse_mode="html")
+            except Exception:  # noqa: BLE001
+                pass
+
+    async def _mediainfo(self, event: Any, msg: Any, own: bool, status: Any) -> None:
+        name = original_name_of(msg)
+        size = int(msg.file.size or 0)
+        playable = is_playable(msg, name)
+        extra = mediainfo.telegram_section(name, size, **telegram_facts(msg, caption=not own))
+        last: List[mediainfo.Report] = []
+
+        async def read(path: Path) -> Optional[mediainfo.Report]:
+            report = await mediainfo.read_file(path, name, size, extra=extra)
+            last[:] = [report]
+            return report if report.has_streams or not playable else None
+
+        async def whole() -> None:
+            await self.client.edit_message(status, "🔎 Reading the file (this one needs the whole file)…", parse_mode="html")
+
+        try:
+            report = await self._with_file_start(event, msg, "minfo", read, whole) or (last[0] if last else None)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("could not read %s for /mediainfo: %s", name, exc)
+            report = None
+        if report is None:
+            await self.client.edit_message(status, "❌ I couldn't read that file.", parse_mode="html")
+            return
+        if playable and not report.has_streams:
+            report.notes.append(
+                "No tracks could be read from this file, and it is too big for me to download completely."
+                if size > TRACKS_FULL_LIMIT else "No tracks could be read from this file. It may be damaged."
+            )
+        try:
+            url = await self.telegraph.create_page(clip(f"MediaInfo – {name}", 256), mediainfo.to_nodes(report))
+        except Exception as exc:  # noqa: BLE001
+            log.warning("Telegraph did not take the /mediainfo page: %s", exc)
+            why = str(exc) if isinstance(exc, TelegraphError) else "Telegraph is not available"
+            await self._mediainfo_file(event, status, name, report, why)
+            return
+        summary = report.summary()
+        text = f"🔎 <b>MediaInfo</b> · {esc(clip(name, 80))}\n" + (f"<i>{esc(summary)}</i>\n" if summary else "") + f"\n{esc(url)}"
+        await self.client.edit_message(status, text, buttons=[[Button.url("📄 Open MediaInfo", url)]], parse_mode="html", link_preview=False)
+
+    async def _mediainfo_file(self, event: Any, status: Any, name: str, report: mediainfo.Report, why: str) -> None:
+        """Telegraph did not work: send the same report as a text file instead."""
+        bio = io.BytesIO(mediainfo.render_text(report).encode("utf-8"))
+        bio.name = re.sub(r'[\\/:*?"<>|]+', "_", clip(split_ext(name)[0], 60)) + " - MediaInfo.txt"
+        caption = f"🔎 <b>MediaInfo</b> · {esc(clip(name, 80))}\n<i>{esc(why)}, so here it is as a text file.</i>"
+        await self.client.send_file(event.chat_id, bio, caption=caption, parse_mode="html", force_document=True)
+        await self._delete_quietly(event.chat_id, status.id)
+
+    # ----------------------------------------------------------- /ethumb, /resize
+    async def cmd_ethumb(self, event: Any) -> None:
+        uid = event.sender_id
+        self.pending.pop(uid, None)
+        reply = await event.get_reply_message()
+        if reply is not None and is_renameable(reply):  # sent as a reply to the file: no need to ask for it
+            await self._send_thumbnail(event, reply)
+            return
+        mode = self._start_mode(uid, "ethumb", ONE_FILE_WAIT)
+        text, rows = panels.ethumb_prompt(ONE_FILE_WAIT // 60)
+        await self._reply(event, text + (f"\n\n{mode.dropped}" if mode.dropped else ""), rows)
+
+    async def _embedded_thumb(self, msg: Any, allow_stripped: bool = False) -> Optional[bytes]:
+        """The preview Telegram keeps with a file.  The tiny blurred one (a "stripped" size) only counts when ``allow_stripped``."""
+        thumbs = getattr(getattr(msg, "document", None), "thumbs", None) or []
+        if not any(not isinstance(t, types.PhotoStrippedSize) for t in thumbs) and not (allow_stripped and thumbs):
+            return None
+        try:
+            return await self.client.download_media(msg, file=bytes, thumb=-1) or None
+        except Exception as exc:  # noqa: BLE001
+            log.debug("could not download the embedded thumbnail: %s", exc)
+            return None
+
+    async def _extract_thumbnail(self, event: Any, msg: Any) -> Optional[bytes]:
+        data = await self._embedded_thumb(msg)
+        if data:
+            return data
+        name = original_name_of(msg)
+        playable = getattr(msg, "video", None) is not None or getattr(msg, "audio", None) is not None
+        if playable or source_ext(msg, name).lower() in PROBE_EXTS:
+            async def frame(path: Path) -> Optional[bytes]:
+                out = path.with_suffix(".jpg")
                 try:
-                    info = await media.probe(path)
+                    duration = (await media.probe(path)).duration
                 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")
+                    duration = 0.0  # cut off before the index: ffmpeg may still find a picture
+                ok = await media.extract_frame(path, out, media.frame_seeks(duration), width=ETHUMB_FRAME_WIDTH)
+                return out.read_bytes() if ok else None
+
+            data = await self._with_file_start(event, msg, "ethumb", frame)
+            if data:
+                return data
+        return await self._embedded_thumb(msg, allow_stripped=True)
+
+    async def _send_thumbnail(self, event: Any, msg: Any) -> None:
+        status = await self._reply(event, "🖼 Extracting the thumbnail…")
+        name = original_name_of(msg)
+        try:
+            data = await self._extract_thumbnail(event, msg)
+        except Exception as exc:  # noqa: BLE001
+            log.warning("thumbnail extraction failed for %s: %s", name, exc)
+            data = None
+        if not data:
+            await self.client.edit_message(status, "❌ I couldn't find a thumbnail in that file or grab a frame from it.", parse_mode="html")
+            return
+        bio = io.BytesIO(data)
+        bio.name = "thumbnail.jpg"
+        await self.client.send_file(event.chat_id, bio, caption=f"🖼 Thumbnail of <b>{esc(clip(name, 80))}</b>", parse_mode="html")
+        await self._delete_quietly(event.chat_id, status.id)
+
+    async def cmd_resize(self, event: Any) -> None:
+        uid = event.sender_id
+        self.pending.pop(uid, None)
+        arg = self._args(event)
+        box = None
+        if arg:
+            box = media.parse_size(arg)
+            if box is None:
+                await self._reply(event, "❌ Send a size like <code>/resize 320</code> or <code>/resize 320x180</code> (16 to 4096 pixels).")
                 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)
+        reply = await event.get_reply_message()
+        if reply is not None and is_image(reply):  # sent as a reply to the image: do it now (thumbnail size unless told otherwise)
+            await self._send_resized(event, reply, box or (media.THUMB_BOX, media.THUMB_BOX))
+            return
+        if box is None:
+            text, rows = panels.resize_menu()
+            await self._reply(event, text, rows)
+            return
+        await self._wait_for_image(event, box)
+
+    async def _wait_for_image(self, event: Any, box: Any) -> None:
+        mode = self._start_mode(event.sender_id, "resize", ONE_FILE_WAIT, {"box": box})
+        text, rows = panels.resize_ready(box, ONE_FILE_WAIT // 60)
+        await self._reply(event, text + (f"\n\n{mode.dropped}" if mode.dropped else ""), rows)
+
+    async def _cb_resize(self, event: Any, uid: int, parts: List[str]) -> None:
+        self.pending.pop(uid, None)
+        action = parts[1] if len(parts) > 1 else ""
+        if action == "s" and len(parts) == 3 and parts[2].isdigit() and int(parts[2]) in dict(panels.RESIZE_PRESETS):
+            box = (int(parts[2]), int(parts[2]))
+            mode = self._start_mode(uid, "resize", ONE_FILE_WAIT, {"box": box})
+            text, rows = panels.resize_ready(box, ONE_FILE_WAIT // 60)
+            await self._edit_panel(event, text + (f"\n\n{mode.dropped}" if mode.dropped else ""), rows)
+            await event.answer(f"Size: {panels.describe_box(box)}")
+        elif action == "custom":
+            self.pending[uid] = Pending(
+                kind="resize:size", chat_id=event.chat_id, msg_id=event.message_id, back="", is_photo=False,
+                expires=time.time() + self.PENDING_TTL,
+            )
+            await self._edit_panel(event, panels.RESIZE_CUSTOM_PROMPT, [[("✖ Cancel", "rz:menu")]])
+            await event.answer()
+        elif action == "menu":
+            if self._mode(uid, "resize") is not None:
+                self._end_mode(uid)
+            text, rows = panels.resize_menu()
+            await self._edit_panel(event, text, rows)
+            await event.answer()
+        elif action == "stop":
+            if self._mode(uid, "resize") is not None:
+                self._end_mode(uid)
+            await self._edit_panel(event, "⏹ Stopped. Send /resize again to resize an image.", [[("✖ Close", "x:close")]])
+            await event.answer()
+        else:
+            await event.answer()
+
+    async def _on_resize_text(self, event: Any, p: Pending) -> None:
+        uid = event.sender_id
+        box = media.parse_size(event.raw_text or "")
+        if box is None:
+            await self._reply(
+                event, "❌ I couldn't read that size. Send it like <code>320x180</code> or <code>320</code> (16 to 4096 pixels).\n\nTry again, or tap Cancel."
+            )
+            return
+        self.pending.pop(uid, None)
+        mode = self._start_mode(uid, "resize", ONE_FILE_WAIT, {"box": box})
+        try:
+            await event.delete()
+        except Exception:  # noqa: BLE001
+            pass
+        text, rows = panels.resize_ready(box, ONE_FILE_WAIT // 60)
+        text += f"\n\n{mode.dropped}" if mode.dropped else ""
+        try:
+            await self.client.edit_message(p.chat_id, p.msg_id, text, buttons=panels.to_buttons(rows), parse_mode="html")
+        except Exception:  # noqa: BLE001
+            await self._reply(event, text, rows)
+
+    async def _image_mode(self, event: Any) -> bool:
+        """Give an incoming picture (or GIF) to the command that is waiting for one (/resize, /smedia).  True when the message was taken care of."""
+        uid = event.sender_id
+        mode = self._mode(uid, "resize", "smedia")
+        if mode is None:
+            return False
+        if mode.kind == "smedia":
+            await self._take_start_media(event, mode)
+            return True
+        if not is_image(event.message):
+            await self._reply(event, "❌ That isn't an image. Send a photo or an image file, or /cancel to stop.")
+            return True
+        self._consume(uid, "resize")
+        await self._send_resized(event, event.message, mode.data["box"])
+        return True
+
+    async def _send_resized(self, event: Any, msg: Any, box: Any) -> None:
+        size = int(msg.file.size or 0) if getattr(msg, "file", None) is not None else 0
+        if size > RESIZE_MAX_BYTES:
+            await self._reply(event, f"❌ That image is {human_size(size)}; I can resize images up to {human_size(RESIZE_MAX_BYTES)}.")
+            return
+        raw = await self.client.download_media(msg, file=bytes)
+        if not raw:
+            await self._reply(event, "❌ I couldn't download that image.")
+            return
+        try:
+            data, original, new = await asyncio.to_thread(media.resize_image, raw, box[0], box[1])
+        except Exception:  # noqa: BLE001
+            await self._reply(event, "❌ I couldn't read that image.")
+            return
+        bio = io.BytesIO(data)
+        bio.name = "resized.jpg"
+        caption = f"🖼 <b>{new[0]}×{new[1]}</b> (was {original[0]}×{original[1]}) · {human_size(len(data))}"
+        await self.client.send_file(event.chat_id, bio, caption=caption, parse_mode="html", force_document=max(new) > 1280)
+
+    # ------------------------------------------------------- /smedia, the /start picture
+    async def _start_media_meta(self) -> Optional[Dict[str, Any]]:
+        """What /start shows above the menu: ``{"kind": "image" | "gif", "file_id": ..., ...}``, or None."""
+        raw = await self.db.kv_get("start_media")
+        if not raw:
+            return None
+        try:
+            meta = json.loads(raw)
+        except ValueError:
+            return None
+        return meta if isinstance(meta, dict) and meta.get("kind") in ("image", "gif") else None
+
+    async def _store_start_media(self, meta: str, data: str) -> None:
+        """Keep the /start media (its description and a base64 copy of the file); empty strings forget it."""
+        for key, value in (("start_media", meta), ("start_media_data", data)):
+            if value:
+                await self.db.kv_set(key, value)
+            else:
+                await self.db.kv_delete(key)
+
+    async def _send_start_media(self, chat_id: int, text: str, rows: List[panels.Row]) -> bool:
+        """Send the menu with the owner's picture or GIF above it.  False when there is none or it can't be sent."""
+        meta = await self._start_media_meta()
+        if meta is None:
+            return False
+        kw: Dict[str, Any] = dict(caption=text, buttons=panels.to_buttons(rows), parse_mode="html")
+        sent = None
+        if meta.get("file_id"):
+            try:
+                sent = await self.client.send_file(chat_id, meta["file_id"], **kw)
+            except Exception as exc:  # noqa: BLE001 - a file reference that went stale: the stored copy is used instead
+                log.warning("the start media could not be sent by its file id (%s); sending the stored copy", exc)
+        if sent is None:
+            try:
+                data = base64.b64decode(await self.db.kv_get("start_media_data") or "", validate=True)
+                if not data:
+                    return False
+                sent = await self._upload_start_media(chat_id, meta, data, **kw)
+            except Exception as exc:  # noqa: BLE001
+                log.warning("could not send the start media (%s); /start shows the menu only", exc)
+                return False
+            fresh = getattr(getattr(sent, "file", None), "id", None)
+            if fresh and fresh != meta.get("file_id"):  # the next /start can reuse what was just uploaded
+                await self.db.kv_set("start_media", json.dumps({**meta, "file_id": fresh}))
+        return True
+
+    async def _upload_start_media(self, chat_id: int, meta: Dict[str, Any], data: bytes, **kw: Any) -> Any:
+        bio = io.BytesIO(data)
+        if meta["kind"] == "gif":
+            bio.name = "start.mp4"
+            kw.update(
+                mime_type=meta.get("mime") or "video/mp4",
+                attributes=[
+                    types.DocumentAttributeVideo(
+                        duration=float(meta.get("duration") or 0), w=int(meta.get("width") or 0), h=int(meta.get("height") or 0),
+                        supports_streaming=True,
+                    ),
+                    types.DocumentAttributeAnimated(),
+                ],
+            )
+        else:
+            bio.name = "start.jpg"
+        return await self.client.send_file(chat_id, bio, **kw)
+
+    async def cmd_smedia(self, event: Any) -> None:
+        self.pending.pop(event.sender_id, None)
+        meta = await self._start_media_meta()
+        text, rows = panels.smedia_menu(meta["kind"] if meta else "")
+        await self._reply(event, text, rows)
+
+    async def _cb_smedia(self, event: Any, uid: int, parts: List[str]) -> None:
+        if not self.is_owner(uid):
+            await event.answer("Owner only.", alert=True)
+            return
+        self.pending.pop(uid, None)
+        action = parts[1] if len(parts) > 1 else ""
+        if action in ("image", "gif"):
+            mode = self._start_mode(uid, "smedia", ONE_FILE_WAIT, {"kind": action})
+            text, rows = panels.smedia_prompt(action, ONE_FILE_WAIT // 60)
+            await self._edit_panel(event, text + (f"\n\n{mode.dropped}" if mode.dropped else ""), rows)
+            await event.answer()
+        elif action == "menu":
+            if self._mode(uid, "smedia") is not None:
+                self._end_mode(uid)
+            meta = await self._start_media_meta()
+            text, rows = panels.smedia_menu(meta["kind"] if meta else "")
+            await self._edit_panel(event, text, rows)
+            await event.answer()
+        elif action == "rm":
+            await self._store_start_media("", "")
+            text, rows = panels.smedia_menu("")
+            await self._edit_panel(event, text, rows)
+            await event.answer("Start media removed.")
+        elif action == "stop":
+            if self._mode(uid, "smedia") is not None:
+                self._end_mode(uid)
+            await self._edit_panel(event, "⏹ Stopped. Send /smedia again to change the start media.", [[("✖ Close", "x:close")]])
+            await event.answer()
+        else:
+            await event.answer()
+
+    async def _take_start_media(self, event: Any, mode: Mode) -> None:
+        """The owner sent the picture or GIF /smedia asked for: keep it, then show /start with it."""
+        uid, msg, want = event.sender_id, event.message, mode.data["kind"]
+        is_gif = getattr(msg, "gif", None) is not None
+        if want == "gif" and not is_gif:
+            await self._reply(event, "❌ That isn't a GIF. Send a GIF (an animation), or /cancel to stop.")
+            return
+        if want == "image" and (is_gif or not is_image(msg)):
+            await self._reply(event, "❌ That isn't an image. Send a photo or an image file, or /cancel to stop.")
+            return
+        size = int(msg.file.size or 0) if getattr(msg, "file", None) is not None else 0
+        if size > START_MEDIA_MAX_BYTES:
+            await self._reply(
+                event, f"❌ That's {human_size(size)}; the biggest I can keep is {human_size(START_MEDIA_MAX_BYTES)}. Send a smaller one, or /cancel to stop."
+            )
+            return
+        self._consume(uid, "smedia")
+        raw = await self.client.download_media(msg, file=bytes)
+        if not raw:
+            await self._reply(event, "❌ I couldn't download that. Send /smedia to try again.")
+            return
+        try:
+            if want == "gif":
+                data, meta = raw, {
+                    "kind": "gif", "mime": msg.file.mime_type or "video/mp4", "width": int(msg.file.width or 0),
+                    "height": int(msg.file.height or 0), "duration": float(msg.file.duration or 0),
+                }
+            elif getattr(msg, "photo", None) is not None:  # Telegram already made it a JPEG that fits
+                data, meta = raw, {"kind": "image"}
+            else:
+                data, meta = await asyncio.to_thread(media.fit_photo, raw, START_IMAGE_BOX), {"kind": "image"}
+        except Exception:  # noqa: BLE001
+            await self._reply(event, "❌ I couldn't read that image. Send /smedia to try again.")
+            return
+        if len(data) > START_MEDIA_MAX_BYTES:
+            await self._reply(event, f"❌ That's {human_size(len(data))}; the biggest I can keep is {human_size(START_MEDIA_MAX_BYTES)}. Send /smedia to try another.")
+            return
+        before = (await self.db.kv_get("start_media") or "", await self.db.kv_get("start_media_data") or "")
+        await self._store_start_media(json.dumps({**meta, "file_id": ""}), base64.b64encode(data).decode("ascii"))
+        text, rows = await self.panel(uid, "home")
+        if not await self._send_start_media(event.chat_id, text, rows):  # the preview is the real /start: if it fails, so would /start
+            await self._store_start_media(*before)
+            await self._reply(event, "❌ Telegram wouldn't take that as the start media, so nothing was changed. Send /smedia to try another.")
+            return
+        await self._reply(event, f"✅ Done: /start shows this {'image' if want == 'image' else 'GIF'} from now on.")
+
+    # ------------------------------------------------------------------- speed
+    async def cmd_speed(self, event: Any) -> None:
+        if self._speed_lock.locked():
+            await self._reply(event, "⏳ A speed test is already running. Try again in a minute.")
+            return
+        async with self._speed_lock:
+            busy = self.queue.running > 0
+            status = await self._reply(event, "⚡ Running the speed test… this takes about half a minute.")
+            try:
+                text = speed.format_result(await speed.run_speedtest())
+                if busy:
+                    text += "\nℹ️ A rename job was running during the test, so the numbers may be lower than usual."
+            except speed.SpeedError as exc:
+                text = f"❌ I couldn't run the speed test: {esc(exc)}"
+            except Exception:  # noqa: BLE001
+                log.exception("speed test failed")
+                text = "❌ The speed test failed unexpectedly."
+            await self.client.edit_message(status, text, parse_mode="html", link_preview=False)
 
     # ----------------------------------------------------------- status/stats
     async def cmd_status(self, event: Any) -> None:
@@ -630,6 +1443,12 @@ class App:
         if p is None or p.expires < time.time():
             self.pending.pop(uid, None)
             return
+        if p.kind.startswith("fmt:"):
+            await self._on_format_text(event, p)
+            return
+        if p.kind == "resize:size":
+            await self._on_resize_text(event, p)
+            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.")
@@ -674,6 +1493,33 @@ class App:
             await self._cb_set(event, uid, parts[1], parts[2])
             return
 
+        if head == "fm":
+            await self._cb_format(event, uid, parts)
+            return
+
+        if head == "rn":
+            await self._cb_rename(event, uid, parts)
+            return
+
+        if head == "sq":
+            await self._cb_sequence(event, uid, parts)
+            return
+
+        if head == "rz":
+            await self._cb_resize(event, uid, parts)
+            return
+
+        if head == "sm":
+            await self._cb_smedia(event, uid, parts)
+            return
+
+        if data == "et:stop":
+            if self._mode(uid, "ethumb") is not None:
+                self._end_mode(uid)
+            await self._edit_panel(event, "⏹ Stopped. Send /ethumb again to extract a thumbnail.", [[("✖ Close", "x:close")]])
+            await event.answer()
+            return
+
         if head == "in":
             await self._cb_input(event, uid, parts)
             return
@@ -776,8 +1622,182 @@ class App:
         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,
+            is_photo=bool(msg_obj is not None and (msg_obj.photo is not None or getattr(msg_obj, "media", None) 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()
+
+    # ------------------------------------------------------------ saved formats
+    async def _show_format(self, event: Any, uid: int, fid: int, note: str = "") -> bool:
+        fmt = await self.db.get_format(uid, fid)
+        if fmt is None:
+            return False
+        text, rows = panels.format_view(fmt)
+        await self._edit_panel(event, f"{note}\n\n{text}" if note else text, rows)
+        return True
+
+    async def _cb_format(self, event: Any, uid: int, parts: List[str]) -> None:
+        self.pending.pop(uid, None)  # leaving a prompt open by tapping something else abandons it
+        action = parts[1] if len(parts) > 1 else ""
+        fid = int(parts[2]) if len(parts) > 2 and parts[2].isdigit() else 0
+
+        if action == "new":
+            if await self.db.count_formats(uid) >= MAX_FORMATS:
+                await event.answer(f"You already have {MAX_FORMATS} formats. Delete one first.", alert=True)
+                return
+            await self._format_prompt(event, uid, "new", 0)
+            return
+
+        fmt = await self.db.get_format(uid, fid) if fid else None
+        if fmt is None:
+            text, rows = await self.panel(uid, "formats")
+            await self._edit_panel(event, text, rows)
+            await event.answer("That format no longer exists.", alert=True)
+            return
+
+        if action in ("v", "cx"):
+            await self._show_format(event, uid, fid)
+            await event.answer()
+        elif action == "in" and len(parts) == 4 and parts[3] in (*FIELD_KINDS, "name"):
+            await self._format_prompt(event, uid, parts[3], fid)
+        elif action == "th":
+            await self._format_prompt(event, uid, "thumb", fid)
+        elif action == "thd":
+            await self.db.set_format_thumb(uid, fid, None)
+            await self._show_format(event, uid, fid)
+            await event.answer("Thumbnail deleted.")
+        elif action == "del":
+            text, rows = panels.format_delete_confirm(fmt)
+            await self._edit_panel(event, text, rows)
+            await event.answer()
+        elif action == "ok":
+            await self.db.delete_format(uid, fid)
+            text, rows = await self.panel(uid, "formats")
+            await self._edit_panel(event, text, rows)
+            await event.answer(f"Deleted {clip(fmt['name'], 40)}.")
+        else:
+            await event.answer()
+
+    async def _format_prompt(self, event: Any, uid: int, field: str, fid: int) -> None:
+        msg_obj = await event.get_message()
+        self.pending[uid] = Pending(
+            kind=f"fmt:{field}", chat_id=event.chat_id, msg_id=event.message_id, back="formats",
+            is_photo=bool(msg_obj is not None and (msg_obj.photo is not None or getattr(msg_obj, "media", None) is not None)),
+            expires=time.time() + self.PENDING_TTL, fid=fid,
+        )
+        text, rows = panels.format_prompt(field, fid)
+        await self._edit_panel(event, text, rows)
+        await event.answer()
+
+    async def _on_format_text(self, event: Any, p: Pending) -> None:
+        uid = event.sender_id
+        field = p.kind[4:]
+        text = event.raw_text or ""
+        if field == "thumb":
+            await self._reply(event, "Send a photo for the thumbnail, or tap Cancel.")
+            return
+        try:
+            if field in ("new", "name"):
+                ok, value = validate_name(text)
+                if ok and field == "new":
+                    fmt = await self.db.create_format(uid, value, template=(await self.db.get_settings(uid))["template"])
+                    msg = f"✅ Format <b>{esc(value)}</b> created. Now set its template, thumbnail and metadata."
+                    p.fid = fmt["id"]
+                elif ok:
+                    if await self.db.update_format(uid, p.fid, name=value) is None:
+                        raise LookupError
+                    msg = f"✅ Renamed to <b>{esc(value)}</b>."
+                else:
+                    msg = value
+            else:
+                ok, msg = await apply_setting(FormatSettings(self.db, p.fid), uid, FIELD_KINDS[field], text)
+        except FormatError as exc:
+            ok = False
+            if exc.code == "limit":
+                self.pending.pop(uid, None)
+                await self._reply(event, f"❌ You already have {MAX_FORMATS} formats. Delete one first.")
+                return
+            msg = "❌ You already have a format with that name."
+        except LookupError:
+            self.pending.pop(uid, None)
+            await self._reply(event, "⚠️ That format no longer exists.")
+            return
+        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
+        await self._refresh_format_panel(event, p, msg)
+
+    async def _format_thumb_saved(self, event: Any, p: Pending, thumb: bytes) -> None:
+        uid = event.sender_id
+        self.pending.pop(uid, None)
+        if not await self.db.set_format_thumb(uid, p.fid, thumb):
+            await self._reply(event, "⚠️ That format no longer exists.")
+            return
+        await self._refresh_format_panel(event, p, "✅ Thumbnail saved for this format.")
+
+    async def _refresh_format_panel(self, event: Any, p: Pending, msg: str) -> None:
+        """Put the format's panel back into the message the prompt was shown in (a new message if that fails)."""
+        fmt = await self.db.get_format(event.sender_id, p.fid)
+        if fmt is None:
+            await self._reply(event, msg)
+            return
+        text, rows = panels.format_view(fmt)
+        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 format 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)
+
+    # ---------------------------------------------------------- /rename picker
+    async def _cb_rename(self, event: Any, uid: int, parts: List[str]) -> None:
+        self.pending.pop(uid, None)
+        action = parts[1] if len(parts) > 1 else ""
+        if action == "p" and len(parts) == 3 and parts[2].isdigit():
+            fmt = await self.db.get_format(uid, int(parts[2]))
+            if fmt is None:
+                text, rows = panels.rename_picker(await self.db.list_formats(uid))
+                await self._edit_panel(event, text, rows)
+                await event.answer("That format no longer exists.", alert=True)
+                return
+            mode = self._start_mode(uid, "rename", ONE_FILE_WAIT, {"fid": fmt["id"]})
+            text, rows = panels.rename_ready(fmt, ONE_FILE_WAIT // 60)
+            await self._edit_panel(event, text + (f"\n\n{mode.dropped}" if mode.dropped else ""), rows)
+            await event.answer(f"Format: {clip(fmt['name'], 40)}")
+        elif action == "menu":
+            if self._mode(uid, "rename") is not None:
+                self._end_mode(uid)
+            text, rows = panels.rename_picker(await self.db.list_formats(uid))
+            await self._edit_panel(event, text, rows)
+            await event.answer()
+        elif action == "stop":
+            if self._mode(uid, "rename") is not None:
+                self._end_mode(uid)
+            await self._edit_panel(event, "⏹ Stopped. Send /rename again to pick a format.", [[("✖ Close", "x:close")]])
+            await event.answer()
+        else:
+            await event.answer()
+
+    # ------------------------------------------------------------ /sequence buttons
+    async def _cb_sequence(self, event: Any, uid: int, parts: List[str]) -> None:
+        action = parts[1] if len(parts) > 1 else ""
+        mode = self._mode(uid, "sequence")
+        if mode is None:
+            await event.answer("That sequence is over.", alert=True)
+            return
+        if action == "sort":
+            await event.answer()
+            await self._run_sort(uid, event.chat_id)
+        elif action == "cx":
+            self._end_mode(uid)
+            await event.answer("Cancelled.")
+            await self._edit_panel(event, self._mode_cancelled_text(mode), [])
+        else:
+            await event.answer()

bot/config.py

@@ -50,7 +50,6 @@ class Config:
     database_url: str
     session_string: str
     log_channel: Optional[int]
-    start_image: Optional[str]
     port: int
     temp_dir: str
     max_jobs: int
@@ -91,7 +90,6 @@ def load_config(env: Optional[Mapping[str, str]] = None) -> Config:
         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,

bot/db.py

@@ -18,6 +18,7 @@ from sqlalchemy.dialects.sqlite import insert as sqlite_insert
 from sqlalchemy.ext.asyncio import AsyncEngine, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
 
+from .errors import FormatError
 from .parser import DEFAULT_TEMPLATE
 
 DEFAULT_SETTINGS: Dict[str, Any] = {
@@ -34,6 +35,16 @@ DEFAULT_SETTINGS: Dict[str, Any] = {
 }
 
 
+MAX_FORMATS = 12
+# what a saved /rename format holds; everything else (mode, caption, file type, ...) comes from the user's settings
+DEFAULT_FORMAT: Dict[str, Any] = {
+    "template": DEFAULT_TEMPLATE,
+    "meta": {"title": "", "author": "", "artist": "", "audio": "", "subtitle": "", "video": ""},
+    "keep_audio": [],
+    "keep_subtitle": [],
+}
+
+
 def _utcnow() -> datetime:
     return datetime.now(timezone.utc)
 
@@ -61,6 +72,17 @@ class Admin(Base):
     added_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
 
 
+class Format(Base):
+    __tablename__ = "formats"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    user_id: Mapped[int] = mapped_column(BigInteger, index=True)
+    name: Mapped[str] = mapped_column(String(64))
+    data: Mapped[str] = mapped_column(Text, default="{}")
+    thumb: Mapped[Optional[bytes]] = mapped_column(LargeBinary, nullable=True)
+    created: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=_utcnow)
+
+
 class KV(Base):
     __tablename__ = "kv"
 
@@ -96,6 +118,28 @@ def _merge_settings(stored: Dict[str, Any]) -> Dict[str, Any]:
     return merged
 
 
+def _merge_format(stored: Dict[str, Any]) -> Dict[str, Any]:
+    merged = copy.deepcopy(DEFAULT_FORMAT)
+    if isinstance(stored.get("template"), str) and stored["template"]:
+        merged["template"] = stored["template"]
+    if isinstance(stored.get("meta"), dict):
+        merged["meta"].update({k: str(v) for k, v in stored["meta"].items() if k in merged["meta"]})
+    for key in ("keep_audio", "keep_subtitle"):
+        if isinstance(stored.get(key), list):
+            merged[key] = [str(t) for t in stored[key]]
+    return merged
+
+
+def _format_dict(fid: int, name: str, raw: Optional[str], has_thumb: bool) -> Dict[str, Any]:
+    try:
+        stored = json.loads(raw or "{}")
+    except ValueError:
+        stored = {}
+    out = _merge_format(stored if isinstance(stored, dict) else {})
+    out.update(id=int(fid), name=name, has_thumb=bool(has_thumb))
+    return out
+
+
 class Database:
     def __init__(self, url: str):
         self.url, connect_args = normalize_database_url(url)
@@ -191,6 +235,93 @@ class Database:
             ).one()
             return int(row[0]), int(row[1])
 
+    # ----- saved /rename formats ------------------------------------------------------
+    async def list_formats(self, uid: int) -> List[Dict[str, Any]]:
+        async with self._sessions() as session:
+            result = await session.execute(
+                select(Format.id, Format.name, Format.data, Format.thumb.isnot(None)).where(Format.user_id == uid).order_by(Format.id)
+            )
+            return [_format_dict(r[0], r[1], r[2], r[3]) for r in result.all()]
+
+    async def count_formats(self, uid: int) -> int:
+        async with self._sessions() as session:
+            return int((await session.execute(select(func.count()).select_from(Format).where(Format.user_id == uid))).scalar() or 0)
+
+    async def get_format(self, uid: int, fid: int) -> Optional[Dict[str, Any]]:
+        async with self._sessions() as session:
+            result = await session.execute(
+                select(Format.id, Format.name, Format.data, Format.thumb.isnot(None)).where(Format.id == fid, Format.user_id == uid)
+            )
+            r = result.first()
+            return _format_dict(r[0], r[1], r[2], r[3]) if r else None
+
+    async def create_format(self, uid: int, name: str, template: Optional[str] = None) -> Dict[str, Any]:
+        """Add a format; raises ``FormatError`` when the user already has ``MAX_FORMATS`` or the name is taken."""
+        async with self._sessions() as session:
+            names = list((await session.execute(select(Format.name).where(Format.user_id == uid))).scalars())
+            if len(names) >= MAX_FORMATS:
+                raise FormatError("limit")
+            if name.casefold() in {n.casefold() for n in names}:
+                raise FormatError("taken")
+            data = copy.deepcopy(DEFAULT_FORMAT)
+            if template:
+                data["template"] = template
+            row = Format(user_id=uid, name=name, data=json.dumps(data, ensure_ascii=False))
+            session.add(row)
+            await session.flush()
+            fid = row.id
+            await session.commit()
+        return _format_dict(fid, name, json.dumps(data, ensure_ascii=False), False)
+
+    async def update_format(self, uid: int, fid: int, **changes: Any) -> Optional[Dict[str, Any]]:
+        """Change ``name``, ``template``, ``keep_audio``, ``keep_subtitle`` or merge a ``meta`` dict; ``None`` if it is gone."""
+        async with self._sessions() as session:
+            row = await session.get(Format, fid)
+            if row is None or row.user_id != uid:
+                return None
+            current = _format_dict(row.id, row.name, row.data, False)
+            for key, value in changes.items():
+                if key == "name":
+                    others = (
+                        await session.execute(select(Format.name).where(Format.user_id == uid, Format.id != fid))
+                    ).scalars()
+                    if value.casefold() in {n.casefold() for n in others}:
+                        raise FormatError("taken")
+                    row.name = value
+                elif key == "meta":
+                    current["meta"].update(value)
+                elif key in DEFAULT_FORMAT:
+                    current[key] = value
+                else:
+                    raise KeyError(key)
+            row.data = json.dumps({k: current[k] for k in DEFAULT_FORMAT}, ensure_ascii=False)
+            has_thumb = row.thumb is not None
+            await session.commit()
+            return _format_dict(row.id, row.name, row.data, has_thumb)
+
+    async def set_format_thumb(self, uid: int, fid: int, data: Optional[bytes]) -> bool:
+        async with self._sessions() as session:
+            row = await session.get(Format, fid)
+            if row is None or row.user_id != uid:
+                return False
+            row.thumb = data
+            await session.commit()
+            return True
+
+    async def get_format_thumb(self, uid: int, fid: int) -> Optional[bytes]:
+        async with self._sessions() as session:
+            row = await session.get(Format, fid)
+            return bytes(row.thumb) if row is not None and row.user_id == uid and row.thumb else None
+
+    async def delete_format(self, uid: int, fid: int) -> bool:
+        async with self._sessions() as session:
+            row = await session.get(Format, fid)
+            if row is None or row.user_id != uid:
+                return False
+            await session.delete(row)
+            await session.commit()
+            return True
+
     # ----- admins ------------------------------------------------------------------
     async def list_admins(self) -> List[int]:
         async with self._sessions() as session:

bot/errors.py

@@ -4,3 +4,11 @@ class Cancelled(Exception):
 
 class MediaError(RuntimeError):
     """ffprobe / ffmpeg failed."""
+
+
+class FormatError(Exception):
+    """A saved-format operation was refused; ``code`` is ``limit`` (12 formats already) or ``taken`` (name in use)."""
+
+    def __init__(self, code: str):
+        super().__init__(code)
+        self.code = code

bot/formats.py

@@ -0,0 +1,78 @@
+"""Saved /rename formats: the pieces shared by the menus, the handlers and the pipeline.
+
+A format is a named bundle of a naming template, a thumbnail, the six metadata titles and the Keep Audio /
+Keep Subtitle lists.  Every other setting (mode, caption template, file type, remove words, target channel)
+still comes from the user's normal auto-rename settings.
+"""
+from __future__ import annotations
+
+import copy
+from typing import Any, Dict, Optional, Tuple
+
+from .db import DEFAULT_SETTINGS, Database
+
+NAME_MAX = 30
+# format field -> the kind settings_ops.apply_setting() understands
+FIELD_KINDS: Dict[str, str] = {
+    "template": "template",
+    "title": "mt_title", "author": "mt_author", "artist": "mt_artist",
+    "audio": "mt_audio", "subtitle": "mt_subtitle", "video": "mt_video",
+    "keep_audio": "keep_audio", "keep_subtitle": "keep_subtitle",
+}
+_EDITABLE = ("template", "meta", "keep_audio", "keep_subtitle")
+
+
+def validate_name(text: Optional[str]) -> Tuple[bool, str]:
+    """``(True, cleaned name)`` or ``(False, html error)``."""
+    name = " ".join((text or "").split())
+    if not name:
+        return False, "❌ Send a name for the format."
+    if len(name) > NAME_MAX:
+        return False, f"❌ That name is too long ({NAME_MAX} characters max)."
+    return True, name
+
+
+def has_metadata(fmt: Dict[str, Any]) -> bool:
+    return any(fmt["meta"].values()) or bool(fmt["keep_audio"] or fmt["keep_subtitle"])
+
+
+def apply_format(settings: Dict[str, Any], fmt: Dict[str, Any]) -> Dict[str, Any]:
+    """The user's settings with the format's template, metadata and keep lists laid over them.
+
+    Metadata is on whenever the format sets anything, whatever the global Metadata switch says: the format
+    carries its own metadata, and a format with none leaves the file alone (no ffmpeg pass).
+    """
+    out = copy.deepcopy(settings)
+    out["template"] = fmt["template"]
+    out["meta"] = dict(fmt["meta"])
+    out["keep_audio"] = list(fmt["keep_audio"])
+    out["keep_subtitle"] = list(fmt["keep_subtitle"])
+    out["metadata_on"] = has_metadata(fmt)
+    return out
+
+
+class FormatSettings:
+    """Edits one saved format through the two methods ``apply_setting`` uses on ``Database``.
+
+    That keeps a single copy of every validation rule and message for the global settings and the formats.
+    Metadata is always "on" here, so the "metadata is off" notes never show for a format.
+    """
+
+    def __init__(self, db: Database, fid: int):
+        self.db = db
+        self.fid = fid
+
+    async def get_settings(self, uid: int) -> Dict[str, Any]:
+        fmt = await self.db.get_format(uid, self.fid)
+        if fmt is None:
+            raise LookupError("that format no longer exists")
+        out = copy.deepcopy(DEFAULT_SETTINGS)
+        out.update(template=fmt["template"], keep_audio=list(fmt["keep_audio"]), keep_subtitle=list(fmt["keep_subtitle"]), metadata_on=True)
+        out["meta"] = dict(fmt["meta"])
+        return out
+
+    async def update_settings(self, uid: int, **changes: Any) -> Dict[str, Any]:
+        wanted = {k: v for k, v in changes.items() if k in _EDITABLE}
+        if wanted and await self.db.update_format(uid, self.fid, **wanted) is None:
+            raise LookupError("that format no longer exists")
+        return await self.get_settings(uid)

bot/main.py

@@ -15,13 +15,15 @@ from .db import Database
 
 log = logging.getLogger("bot")
 
+TEMP_PREFIXES = ("job", "tracks", "ethumb", "minfo")  # the folders the bot makes in TEMP_DIR
+
 
 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")):
+        if child.is_dir() and child.name.startswith(TEMP_PREFIXES):
             shutil.rmtree(child, ignore_errors=True)
 
 
@@ -63,6 +65,8 @@ async def amain() -> int:
     client = await build_client(cfg, db)
     me = await client.get_me()
     app = App(client, cfg, db)
+    username = getattr(me, "username", "") or ""
+    app.telegraph.set_author(getattr(me, "first_name", "") or username, f"https://t.me/{username}" if username else "")
     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")

bot/media.py

@@ -208,6 +208,22 @@ async def probe(path: Path | str, cancel: Optional[asyncio.Event] = None) -> Med
     return parse_probe(data)
 
 
+async def probe_raw(path: Path | str, cancel: Optional[asyncio.Event] = None) -> Dict[str, Any]:
+    """ffprobe's own JSON (format, streams, chapters) for /mediainfo; an empty dict when it found nothing."""
+    code, out, err = await _run(
+        ["ffprobe", "-v", "error", "-print_format", "json", "-show_format", "-show_streams", "-show_chapters", str(path)], cancel
+    )
+    try:
+        data = json.loads(out.decode("utf-8", "replace") or "{}")
+    except ValueError:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+    if not data.get("streams") and not data.get("format") and code != 0:
+        raise MediaError("ffprobe failed: " + err.decode("utf-8", "replace").strip()[-300:])
+    return data
+
+
 # ---------------------------------------------------------------------------
 # track selection
 # ---------------------------------------------------------------------------
@@ -391,6 +407,95 @@ async def make_video_thumbnail(src: Path, dst: Path, duration: float, cancel: Op
     return code == 0 and dst.exists() and dst.stat().st_size > 0
 
 
+def frame_seeks(duration: float) -> List[float]:
+    """Positions (seconds) to try for a picture, best first: ~10% in, then earlier ones for a file that is cut off."""
+    first = 1.0 if duration <= 0 else min(max(duration * 0.1, 0.0), 60.0)
+    return [round(first, 2)] + [seek for seek in (20.0, 5.0, 0.0) if seek < first]
+
+
+async def extract_frame(
+    src: Path, dst: Path, seeks: Sequence[float], width: int = 1280, cancel: Optional[asyncio.Event] = None
+) -> bool:
+    """Save one frame of ``src`` as a JPEG (at most ``width`` px wide), trying each seek position until one gives a picture."""
+    for seek in seeks:
+        dst.unlink(missing_ok=True)
+        cmd = [
+            "ffmpeg", "-hide_banner", "-nostdin", "-y", "-loglevel", "error", "-ss", f"{seek:.2f}", "-i", str(src),
+            "-frames:v", "1", "-vf", f"scale='min({width},iw)':-2", "-q:v", "3", str(dst),
+        ]
+        try:
+            code, _o, _e = await _run(cmd, cancel)
+        except MediaError:
+            return False
+        if code == 0 and dst.exists() and dst.stat().st_size > 0:
+            return True
+    return False
+
+
+SIZE_MIN, SIZE_MAX = 16, 4096
+THUMB_BOX = 320  # Telegram shows custom thumbnails up to 320 px, as a JPEG under 200 KB
+
+
+_SIZE_RE = re.compile(r"\s*(\d{1,5})(?:(?:\s*[x×*,:]\s*|\s+)(\d{1,5}))?\s*", re.I)
+
+
+def parse_size(text: str) -> Optional[Tuple[int, int]]:
+    """``320`` -> (320, 320); ``320x180`` / ``320×180`` / ``320 180`` -> (320, 180); None when it isn't a usable size."""
+    m = _SIZE_RE.fullmatch(text or "")
+    if not m:
+        return None
+    width = int(m.group(1))
+    height = int(m.group(2)) if m.group(2) else width
+    if not (SIZE_MIN <= width <= SIZE_MAX and SIZE_MIN <= height <= SIZE_MAX):
+        return None
+    return width, height
+
+
+def _flatten(img: Any) -> Any:
+    """``img`` as RGB; transparent parts become white."""
+    from PIL import Image
+
+    if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
+        rgba = img.convert("RGBA")
+        flat = Image.new("RGB", rgba.size, (255, 255, 255))
+        flat.paste(rgba, mask=rgba.getchannel("A"))
+        return flat
+    return img.convert("RGB")
+
+
+def fit_photo(data: bytes, box: int = 1280) -> bytes:
+    """A picture as a JPEG that fits ``box`` x ``box`` (a smaller one is not enlarged): what Telegram takes as a photo."""
+    from PIL import Image, ImageOps
+
+    with Image.open(io.BytesIO(data)) as img:
+        img = _flatten(ImageOps.exif_transpose(img))
+        img.thumbnail((box, box), Image.LANCZOS)
+        buf = io.BytesIO()
+        img.save(buf, "JPEG", quality=90, optimize=True)
+        return buf.getvalue()
+
+
+def resize_image(data: bytes, width: int, height: int) -> Tuple[bytes, Tuple[int, int], Tuple[int, int]]:
+    """Scale an image to fit inside ``width`` x ``height``, keeping its shape.
+
+    Returns ``(jpeg bytes, original size, new size)``.  A result that fits Telegram's thumbnail box stays under 200 KB.
+    """
+    from PIL import Image, ImageOps
+
+    with Image.open(io.BytesIO(data)) as img:
+        img = ImageOps.exif_transpose(img)
+        original = img.size
+        img = _flatten(img)
+        out = ImageOps.contain(img, (width, height), Image.LANCZOS)
+        limit = 200 * 1024 if max(out.size) <= THUMB_BOX else None
+        for quality in (92, 85, 78, 70, 60, 50, 40):
+            buf = io.BytesIO()
+            out.save(buf, "JPEG", quality=quality, optimize=True)
+            if limit is None or buf.tell() <= limit:
+                break
+        return buf.getvalue(), original, out.size
+
+
 def prepare_thumb(data: bytes) -> bytes:
     """Resize/re-encode an image to Telegram's thumbnail limits (<=320px, <=200 KB JPEG)."""
     from PIL import Image

bot/mediainfo.py

@@ -0,0 +1,491 @@
+"""/mediainfo: everything we can tell about a file, laid out like MediaInfo and ready for a Telegraph page.
+
+MediaInfo (the ``pymediainfo`` package) is used when it is available, because it reports the most.  Without it the
+report is built from ffprobe, which is always there because the renamer needs it.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import textwrap
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from . import media
+from .errors import MediaError
+from .telegraph import CONTENT_LIMIT, Node, content_size
+from .utils import clip
+
+log = logging.getLogger(__name__)
+
+WRAP = 64  # columns of the monospace blocks on the page (Telegraph does not wrap them)
+LABEL_ALIGN = 26  # labels longer than this are not used to line up the values
+MIN_VALUE = 40  # columns a wrapped value always gets, even next to a long label
+STREAM_KINDS = {"Video", "Audio", "Text", "Image", "Other"}
+# lines MediaInfo adds when it is given only the start of a file; they describe our download, not the file
+PARTIAL_ARTIFACTS = {"CRC_Error_Pos", "IsTruncated"}
+_CONTROL_RE = re.compile(r"[\x00-\x08\x0b-\x1f\x7f]")
+
+
+@dataclass
+class Section:
+    title: str
+    lines: List[Tuple[str, str]] = field(default_factory=list)  # (label, value); an empty label is a plain line
+
+    @property
+    def kind(self) -> str:
+        return self.title.split(" #")[0]
+
+
+@dataclass
+class Report:
+    sections: List[Section]
+    engine: str  # "MediaInfo", "ffprobe" or "" when nothing could read the file
+    truncated: bool = False  # only the start of the file was read
+    notes: List[str] = field(default_factory=list)  # shown under the sections
+
+    @property
+    def has_streams(self) -> bool:
+        return any(s.kind in STREAM_KINDS for s in self.sections)
+
+    def section(self, title: str) -> Optional[Section]:
+        return next((s for s in self.sections if s.title == title), None)
+
+    def summary(self) -> str:
+        """``Matroska · 24 min 1 s · 1 video · 2 audio · 3 subtitle``"""
+        parts: List[str] = []
+        general = self.section("General")
+        for label in ("Format", "Duration"):
+            value = next((v for lab, v in general.lines if lab == label), "") if general is not None else ""
+            if value:
+                parts.append(value)
+        for kind, word in (("Video", "video"), ("Audio", "audio"), ("Text", "subtitle")):
+            count = sum(1 for s in self.sections if s.kind == kind)
+            if count:
+                parts.append(f"{count} {word}")
+        return " · ".join(parts)
+
+
+# ---------------------------------------------------------------------------
+# MediaInfo's number formats
+# ---------------------------------------------------------------------------
+
+
+def mi_size(num: float) -> str:
+    """``71.0 KiB``, ``1.46 GiB``: three significant digits, binary units."""
+    value = float(num)
+    unit = "Bytes"
+    for unit in ("Bytes", "KiB", "MiB", "GiB", "TiB"):
+        if value < 1023.5 or unit == "TiB":
+            break
+        value /= 1024
+    if unit == "Bytes":
+        return f"{int(round(value))} Bytes"
+    digits = 0 if value >= 99.95 else 1 if value >= 9.995 else 2
+    return f"{value:.{digits}f} {unit}"
+
+
+def mi_rate(bits_per_second: float) -> str:
+    """``62 b/s``, ``370 kb/s`` below 10 Mb/s, ``12.3 Mb/s`` above."""
+    if bits_per_second < 1000:
+        return f"{int(round(bits_per_second))} b/s"
+    kbps = bits_per_second / 1000
+    if kbps < 10000:
+        return f"{kbps:,.0f}".replace(",", " ") + " kb/s"
+    mbps = kbps / 1000
+    return f"{mbps:.0f} Mb/s" if mbps >= 100 else f"{mbps:.1f} Mb/s"
+
+
+def mi_duration(milliseconds: float) -> str:
+    """``1 h 24 min``, ``24 min 1 s``, ``2 s 23 ms``."""
+    ms = int(round(milliseconds))
+    hours, rest = divmod(ms, 3_600_000)
+    minutes, rest = divmod(rest, 60_000)
+    seconds, millis = divmod(rest, 1000)
+    if hours:
+        return f"{hours} h {minutes} min"
+    if minutes:
+        return f"{minutes} min {seconds} s"
+    return f"{seconds} s {millis} ms"
+
+
+def clean(value: Any) -> str:
+    return _CONTROL_RE.sub("", str(value)).strip()
+
+
+# ---------------------------------------------------------------------------
+# reading MediaInfo's text
+# ---------------------------------------------------------------------------
+
+
+def parse_text(text: str) -> List[Section]:
+    """Split MediaInfo's text output into sections of ``label : value`` lines (nested lines keep their indent)."""
+    sections: List[Section] = []
+    current: Optional[Section] = None
+    for raw in text.splitlines():
+        line = _CONTROL_RE.sub("", raw).rstrip()
+        if not line.strip():
+            current = None
+            continue
+        if current is None:
+            current = Section(title=line.strip())
+            sections.append(current)
+            continue
+        label, sep, value = line.partition(" : ")
+        if sep:
+            current.lines.append((label.rstrip(), value.strip()))
+        elif line.endswith(" :"):
+            current.lines.append((line[:-2].rstrip(), ""))
+        else:
+            current.lines.append(("", line.strip()))
+    return sections
+
+
+def _set(section: Section, label: str, value: str, *, first: bool = False) -> None:
+    for i, (existing, _old) in enumerate(section.lines):
+        if existing == label:
+            section.lines[i] = (label, value)
+            return
+    section.lines.insert(0 if first else len(section.lines), (label, value))
+
+
+def _drop(section: Section, label: str) -> None:
+    section.lines = [(lab, val) for lab, val in section.lines if lab != label]
+
+
+def _drop_partial_artifacts(section: Section) -> None:
+    """Remove the conformance errors and the like that MediaInfo reports about a file that was cut short on purpose."""
+    kept: List[Tuple[str, str]] = []
+    skipping = False
+    for label, value in section.lines:
+        if skipping and label[:1].isspace():  # a line nested under the one being dropped
+            continue
+        skipping = False
+        bare = label.strip()
+        if bare.startswith("Conformance"):
+            skipping = True
+            continue
+        if bare in PARTIAL_ARTIFACTS:
+            continue
+        kept.append((label, value))
+    section.lines = kept
+
+
+def fix_general(report: Report, name: str, true_size: int, duration_ms: Optional[float]) -> None:
+    """Show the file's own name instead of the temporary path, and its real size when only the start was read."""
+    general = report.section("General")
+    if general is None:
+        general = Section("General")
+        report.sections.insert(0, general)
+    _set(general, "Complete name", name, first=True)
+    if true_size:
+        _set(general, "File size", mi_size(true_size))
+    if report.truncated:
+        _drop_partial_artifacts(general)
+        if true_size and duration_ms:
+            _set(general, "Overall bit rate", mi_rate(true_size * 8 / (duration_ms / 1000)))
+        else:
+            _drop(general, "Overall bit rate")  # it was worked out from the part we have, so it would be wrong
+
+
+def telegram_section(name: str, size: int, *, mime: str = "", sent_as: str = "", sent_on: str = "", dc: str = "", caption: str = "") -> Section:
+    """What Telegram itself says about the file."""
+    lines = [("File name", name)]
+    if size:
+        lines.append(("File size", f"{mi_size(size)} ({size:,} bytes)".replace(",", " ")))
+    for label, value in (("MIME type", mime), ("Sent as", sent_as), ("Sent on", sent_on), ("Data center", dc), ("Caption", caption)):
+        if value:
+            lines.append((label, value))
+    return Section("Telegram", lines)
+
+
+# ---------------------------------------------------------------------------
+# the ffprobe fallback
+# ---------------------------------------------------------------------------
+
+_TAG_LABELS = {
+    "title": "Title", "encoder": "Writing application", "creation_time": "Encoded date", "artist": "Performer",
+    "album": "Album", "date": "Recorded date", "comment": "Comment", "genre": "Genre", "copyright": "Copyright",
+}
+
+
+def _language(code: str) -> str:
+    name = media.canonical_lang(code)
+    return name.title() if name else code.strip()
+
+
+def _fraction(text: Any) -> float:
+    try:
+        num, _sep, den = str(text).partition("/")
+        return float(num) / float(den) if den else float(num)
+    except (ValueError, ZeroDivisionError):
+        return 0.0
+
+
+def _seconds(*candidates: Any) -> float:
+    """The first usable duration among ``candidates``: plain seconds or ``HH:MM:SS.fff``."""
+    for cand in candidates:
+        if not cand:
+            continue
+        text = str(cand)
+        try:
+            value = media._parse_hms(text) if ":" in text else float(text)
+        except ValueError:
+            continue
+        if value > 0:
+            return value
+    return 0.0
+
+
+def _add(section: Section, label: str, value: Any) -> None:
+    text = clean(value) if value not in (None, "") else ""
+    if text:
+        section.lines.append((label, text))
+
+
+def _flag(value: Any) -> str:
+    return "Yes" if int(value or 0) else "No"
+
+
+def _level(stream: Dict[str, Any]) -> str:
+    try:
+        level = int(stream.get("level"))
+    except (TypeError, ValueError):
+        return ""
+    if level <= 0:
+        return ""
+    codec = stream.get("codec_name")
+    if codec == "h264":
+        return f"L{level / 10:g}"
+    if codec == "hevc":
+        return f"L{level / 30:g}"
+    return ""
+
+
+def _stream_section(stream: Dict[str, Any], title: str) -> Section:
+    sec = Section(title)
+    kind = stream.get("codec_type")
+    tags = {k.lower(): v for k, v in (stream.get("tags") or {}).items()}
+    disp = stream.get("disposition") or {}
+    _add(sec, "ID", int(stream.get("index", 0)) + 1)
+    _add(sec, "Format", stream.get("codec_long_name") or stream.get("codec_name"))
+    if kind == "video":
+        _add(sec, "Format profile", "@".join(p for p in (stream.get("profile"), _level(stream)) if p))
+    else:
+        _add(sec, "Format profile", stream.get("profile"))
+    tag = stream.get("codec_tag_string")
+    if tag and not tag.startswith("[0]"):
+        _add(sec, "Codec ID", tag)
+    seconds = _seconds(stream.get("duration"), tags.get("duration"))
+    if seconds:
+        _add(sec, "Duration", mi_duration(seconds * 1000))
+    try:
+        rate = float(stream.get("bit_rate") or tags.get("bps") or tags.get("bps-eng") or 0)
+    except ValueError:
+        rate = 0.0
+    if rate:
+        _add(sec, "Bit rate", mi_rate(rate))
+    if kind == "video":
+        if stream.get("width") and stream.get("height"):
+            _add(sec, "Width", f"{stream['width']} pixels")
+            _add(sec, "Height", f"{stream['height']} pixels")
+        _add(sec, "Display aspect ratio", stream.get("display_aspect_ratio"))
+        fps = _fraction(stream.get("avg_frame_rate") or "0") or _fraction(stream.get("r_frame_rate") or "0")
+        if fps:
+            _add(sec, "Frame rate", f"{fps:.3f} FPS")
+        _add(sec, "Pixel format", stream.get("pix_fmt"))
+        if stream.get("bits_per_raw_sample"):
+            _add(sec, "Bit depth", f"{stream['bits_per_raw_sample']} bits")
+        for label, key in (("Color space", "color_space"), ("Color range", "color_range"), ("Transfer characteristics", "color_transfer"),
+                           ("Color primaries", "color_primaries"), ("Scan type", "field_order")):
+            _add(sec, label, stream.get(key))
+    elif kind == "audio":
+        channels = stream.get("channels")
+        if channels:
+            _add(sec, "Channel(s)", f"{channels} channel" + ("s" if channels != 1 else ""))
+        _add(sec, "Channel layout", stream.get("channel_layout"))
+        try:
+            if stream.get("sample_rate"):
+                _add(sec, "Sampling rate", f"{float(stream['sample_rate']) / 1000:g} kHz")
+        except ValueError:
+            pass
+        if stream.get("bits_per_raw_sample"):
+            _add(sec, "Bit depth", f"{stream['bits_per_raw_sample']} bits")
+    _add(sec, "Title", tags.get("title"))
+    if tags.get("language") not in (None, "", "und"):
+        _add(sec, "Language", _language(str(tags["language"])))
+    sec.lines.append(("Default", _flag(disp.get("default"))))
+    sec.lines.append(("Forced", _flag(disp.get("forced"))))
+    return sec
+
+
+def ffprobe_sections(data: Dict[str, Any], name: str, true_size: int) -> List[Section]:
+    """MediaInfo-style sections from ffprobe's JSON (``-show_format -show_streams -show_chapters``)."""
+    fmt = data.get("format") or {}
+    streams = data.get("streams") or []
+    general = Section("General")
+    _add(general, "Complete name", name)
+    _add(general, "Format", fmt.get("format_long_name") or fmt.get("format_name"))
+    if true_size:
+        _add(general, "File size", mi_size(true_size))
+    seconds = _seconds(fmt.get("duration"))
+    if seconds:
+        _add(general, "Duration", mi_duration(seconds * 1000))
+        if true_size:
+            _add(general, "Overall bit rate", mi_rate(true_size * 8 / seconds))
+    for key, value in (fmt.get("tags") or {}).items():
+        _add(general, _TAG_LABELS.get(key.lower(), key.replace("_", " ").title()), value)
+    attached = [
+        (s.get("tags") or {}).get("filename") or (s.get("tags") or {}).get("FILENAME")
+        for s in streams if s.get("codec_type") == "attachment"
+    ]
+    _add(general, "Attachments", " / ".join(a for a in attached if a))
+    sections = [general]
+
+    titles = {"video": "Video", "audio": "Audio", "subtitle": "Text"}
+    counts = {kind: sum(1 for s in streams if s.get("codec_type") == kind) for kind in titles}
+    seen: Dict[str, int] = {}
+    for stream in streams:
+        kind = stream.get("codec_type")
+        if kind not in titles:
+            continue
+        seen[kind] = seen.get(kind, 0) + 1
+        title = titles[kind] if counts[kind] == 1 else f"{titles[kind]} #{seen[kind]}"
+        sections.append(_stream_section(stream, title))
+
+    chapters = data.get("chapters") or []
+    if chapters:
+        menu = Section("Menu")
+        for chapter in chapters:
+            millis = int(_seconds(chapter.get("start_time")) * 1000)
+            hours, rest = divmod(millis, 3_600_000)
+            minutes, rest = divmod(rest, 60_000)
+            stamp = f"{hours:02d}:{minutes:02d}:{rest // 1000:02d}.{rest % 1000:03d}"
+            menu.lines.append((stamp, clean((chapter.get("tags") or {}).get("title", ""))))
+        sections.append(menu)
+    return sections
+
+
+# ---------------------------------------------------------------------------
+# reading a file
+# ---------------------------------------------------------------------------
+
+
+def _mediainfo(path: Path) -> Optional[Tuple[str, Optional[float]]]:
+    """Blocking: MediaInfo's text and the duration (ms) of the file, or None when MediaInfo is not usable."""
+    try:
+        from pymediainfo import MediaInfo
+    except ImportError:
+        return None
+    if not MediaInfo.can_parse():
+        return None
+    text = MediaInfo.parse(str(path), output="text", full=False)
+    duration: Optional[float] = None
+    try:
+        first = MediaInfo.parse(str(path)).tracks[0]
+        duration = float(first.duration) if first.duration else None
+    except (IndexError, TypeError, ValueError, AttributeError):
+        duration = None
+    return str(text), duration
+
+
+async def read_file(path: Path, name: str, true_size: int, *, extra: Optional[Section] = None) -> Report:
+    """The report for the file at ``path``, which is all of the file or only its start (``true_size`` is the real size).
+
+    The report may have no streams (``has_streams``): a video whose index is at the end of the file, for one.
+    """
+    sections: List[Section] = []
+    engine = ""
+    duration_ms: Optional[float] = None
+    try:
+        got = await asyncio.to_thread(_mediainfo, path)
+    except Exception as exc:  # noqa: BLE001 - the library is native code; whatever goes wrong, ffprobe is the fallback
+        log.warning("MediaInfo failed on %s: %s", name, exc)
+        got = None
+    if got is not None:
+        sections, duration_ms = parse_text(got[0]), got[1]
+        engine = "MediaInfo" if sections else ""
+    if not sections:
+        try:
+            data = await media.probe_raw(path)
+        except MediaError:
+            data = {}
+        if data.get("format") or data.get("streams"):
+            sections, engine = ffprobe_sections(data, name, true_size), "ffprobe"
+            duration_ms = _seconds((data.get("format") or {}).get("duration")) * 1000 or None
+    report = Report(sections=sections, engine=engine, truncated=bool(true_size and path.stat().st_size < true_size))
+    fix_general(report, name, true_size, duration_ms)
+    if extra is not None:
+        report.sections.append(extra)
+    return report
+
+
+# ---------------------------------------------------------------------------
+# the Telegraph page
+# ---------------------------------------------------------------------------
+
+
+def render_section(section: Section, width: int = WRAP, max_value: int = 0) -> str:
+    """The section as aligned ``label : value`` lines, long values wrapped under the first one."""
+    label_w = max((len(lab) for lab, _ in section.lines if lab and len(lab) <= LABEL_ALIGN), default=0)
+    indent = " " * (label_w + 3)
+    room = max(MIN_VALUE, width - len(indent))
+    out: List[str] = []
+    for label, value in section.lines:
+        if max_value:
+            value = clip(value, max_value)
+        if not label:
+            out.extend(textwrap.wrap(value, width=width, break_long_words=True, break_on_hyphens=False) or [""])
+            continue
+        head = f"{clip(label, 60):<{label_w}} : "
+        parts = textwrap.wrap(value, width=room, break_long_words=True, break_on_hyphens=False) or [""]
+        out.append(head + parts[0])
+        out.extend(indent + part for part in parts[1:])
+    return "\n".join(line.rstrip() for line in out)
+
+
+def render_text(report: Report, **kw: Any) -> str:
+    """The whole report as plain text (what is sent as a file when Telegraph cannot be reached)."""
+    blocks = [f"{s.title}\n{render_section(s, **kw)}" for s in report.sections]
+    blocks.extend(report_notes(report))
+    return "\n\n".join(blocks) + "\n"
+
+
+def report_notes(report: Report) -> List[str]:
+    notes = list(report.notes)
+    if report.truncated:
+        notes.append("Only the start of the file was read; its size and overall bit rate are worked out from the real file size.")
+    notes.append(f"Made by the bot with {report.engine}." if report.engine else "Made by the bot.")
+    return notes
+
+
+def _nodes(report: Report, max_value: int, keep: int, notes: List[str]) -> List[Node]:
+    nodes: List[Node] = []
+    for index, section in enumerate(report.sections):
+        if index >= keep and section.title != "Telegram":
+            continue
+        nodes.append({"tag": "h4", "children": [section.title]})
+        nodes.append({"tag": "pre", "children": [render_section(section, max_value=max_value)]})
+    for note in notes:
+        nodes.append({"tag": "p", "children": [{"tag": "i", "children": [note]}]})
+    return nodes
+
+
+def to_nodes(report: Report, limit: int = CONTENT_LIMIT) -> List[Node]:
+    """Telegraph nodes for the report, shortened step by step until the page fits Telegraph's size limit."""
+    notes = report_notes(report)
+    total = len(report.sections)
+    for max_value in (0, 300, 150, 80):
+        nodes = _nodes(report, max_value, total, notes)
+        if content_size(nodes) <= limit:
+            return nodes
+    keep = total
+    while keep > 1:  # still too big (a file with hundreds of tracks): drop the last sections, keeping General and Telegram
+        keep -= 1
+        left_out = [f"The page size limit was reached, so {total - keep} more section(s) were left out."]
+        nodes = _nodes(report, 80, keep, notes + left_out)
+        if content_size(nodes) <= limit:
+            return nodes
+    return _nodes(report, 80, 1, notes)

bot/panels.py

@@ -67,7 +67,7 @@ def home(s: Dict[str, Any], *, owner: bool) -> Panel:
     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 []),
+        [("Formats", "m:formats"), ("Help", "m:help")] + ([("Admin", "m:admin")] if owner else []),
         [("✖ Close", "x:close")],
     ]
     return text, rows
@@ -183,13 +183,16 @@ 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"
+        "2. /formats — save up to 12 named formats (template, thumbnail, metadata, tracks); "
+        "/rename — pick one, then send a file (send /rename again for the next one).\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"
+        "8. /sequence then /sort — put files in episode order.\n"
+        "9. /check, /mediainfo, /ethumb, /resize, /speed — inspect files and images.\n"
+        "10. /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."
     )
@@ -205,7 +208,7 @@ def admin(owner_id: int, admins: Sequence[int], running: int, waiting: int, log_
         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"
+        "Commands: /addadmin &lt;id&gt; · /deladmin &lt;id&gt; · /admins · /smedia"
     )
     rows: List[Row] = [
         [("📊 Stats", "adm:stats"), ("🟢 Status", "adm:status")],
@@ -214,6 +217,209 @@ def admin(owner_id: int, admins: Sequence[int], running: int, waiting: int, log_
     return text, rows
 
 
+# ---------------------------------------------------------------------------
+# saved formats
+# ---------------------------------------------------------------------------
+
+FORMAT_FIELD_LABELS = (
+    ("title", "Title"), ("author", "Author"), ("artist", "Artist"),
+    ("audio", "Audio"), ("subtitle", "Subtitle"), ("video", "Video"),
+)
+
+
+def _format_buttons(formats: Sequence[Dict[str, Any]], prefix: str) -> List[Row]:
+    rows: List[Row] = []
+    row: Row = []
+    for f in formats:
+        row.append((clip(f["name"], 24), f"{prefix}:{f['id']}"))
+        if len(row) == 2:
+            rows.append(row)
+            row = []
+    if row:
+        rows.append(row)
+    return rows
+
+
+def formats_menu(formats: Sequence[Dict[str, Any]], limit: int) -> Panel:
+    text = (
+        f"<b>🗂 FORMATS</b> ({len(formats)}/{limit})\n\n"
+        "A format saves its own template, thumbnail, metadata titles and Keep Audio / Keep Subtitle lists "
+        "under a name, like <i>One Piece</i> or <i>Dragon Ball</i>.\n"
+        "Tap one to view or edit it, then use /rename to apply it to your files."
+    )
+    if not formats:
+        text += "\n\nYou have no formats yet."
+    rows = _format_buttons(formats, "fm:v")
+    if len(formats) < limit:
+        rows.append([("➕ New format", "fm:new")])
+    else:
+        text += f"\n\nYou have all {limit} formats. Delete one to add another."
+    return text, rows + nav("home")
+
+
+def format_view(fmt: Dict[str, Any]) -> Panel:
+    m = fmt["meta"]
+    lines = [
+        f"<b>🗂 {esc(clip(fmt['name'], 30))}</b>",
+        "",
+        f"{DOT} <b>Template</b> ▸ {_code(fmt['template'], 60)}",
+        f"{DOT} <b>Thumbnail</b> ▸ " + ("✅ saved" if fmt.get("has_thumb") else "— (your default thumbnail is used)"),
+    ]
+    for key, label in FORMAT_FIELD_LABELS:
+        lines.append(f"{DOT} <b>{label}</b> ▸ {_code(m.get(key, ''), 50)}")
+    lines.append(f"{DOT} <b>Keep Audio</b> ▸ {esc(clip(fmt_tokens(fmt['keep_audio']), 50))}")
+    lines.append(f"{DOT} <b>Keep Subtitle</b> ▸ {esc(clip(fmt_tokens(fmt['keep_subtitle']), 50))}")
+    lines += ["", "Use it with /rename. Mode, caption, file type and the rest come from your normal settings."]
+    fid = fmt["id"]
+    thumb_row: Row = [("Thumbnail", f"fm:th:{fid}")]
+    if fmt.get("has_thumb"):
+        thumb_row.append(("🗑 Delete Thumb", f"fm:thd:{fid}"))
+    rows: List[Row] = [
+        [("Name", f"fm:in:{fid}:name"), ("Template", f"fm:in:{fid}:template")],
+        thumb_row,
+        [("Title", f"fm:in:{fid}:title"), ("Author", f"fm:in:{fid}:author"), ("Artist", f"fm:in:{fid}:artist")],
+        [("Audio", f"fm:in:{fid}:audio"), ("Subtitle", f"fm:in:{fid}:subtitle"), ("Video", f"fm:in:{fid}:video")],
+        [("Keep Audio", f"fm:in:{fid}:keep_audio"), ("Keep Subtitle", f"fm:in:{fid}:keep_subtitle")],
+        [("🗑 Delete format", f"fm:del:{fid}")],
+    ] + nav("formats")
+    return "\n".join(lines), rows
+
+
+def format_delete_confirm(fmt: Dict[str, Any]) -> Panel:
+    text = f"<b>Delete the format “{esc(clip(fmt['name'], 30))}”?</b>\n\nIts template, thumbnail and metadata are removed. This can't be undone."
+    return text, [[("🗑 Yes, delete", f"fm:ok:{fmt['id']}"), ("◀ Keep it", f"fm:v:{fmt['id']}")]]
+
+
+def rename_picker(formats: Sequence[Dict[str, Any]]) -> Panel:
+    if not formats:
+        text = (
+            "<b>🏷 RENAME</b>\n\nYou have no saved formats yet.\n"
+            "A format keeps a template, thumbnail and metadata under a name, like <i>One Piece</i>. Create one, then come back here."
+        )
+        return text, [[("➕ Create a format", "fm:new")], [("✖ Close", "x:close")]]
+    text = "<b>🏷 RENAME</b>\n\nChoose the format to rename with. I'll ask for your files next."
+    rows = _format_buttons(formats, "rn:p") + [[("⚙️ Manage formats", "m:formats"), ("✖ Close", "x:close")]]
+    return text, rows
+
+
+def rename_ready(fmt: Dict[str, Any], minutes: int) -> Panel:
+    text = (
+        f"✅ <b>{esc(clip(fmt['name'], 30))}</b> selected.\n\n"
+        "Now send me the file to rename. I'll apply this format to it and send it back.\n"
+        "It works for one file at a time: for another file, send /rename again.\n"
+        f"I'll wait {minutes} minutes. /cancel to stop."
+    )
+    return text, [[("🔄 Change format", "rn:menu"), ("⏹ Stop", "rn:stop")]]
+
+
+def _detail_lines(info: Any) -> str:
+    """Title, Season, Episode and Quality always (``None`` when not found); Year and Codec only when found."""
+    fields = [("Title", info.title), ("Season", info.season), ("Episode", info.episode), ("Quality", info.quality)]
+    fields += [(label, value) for label, value in (("Year", info.year), ("Codec", info.codec)) if value]
+    return "\n".join(f"➦ {label} ⇛ <code>{esc(clip(value, 60)) if value else 'None'}</code>" for label, value in fields)
+
+
+def check_text(mode: str, name_info: Any, caption_info: Any, new_name: str) -> str:
+    """What /check shows: the details read from the file name and from the caption, and the name they give."""
+    return (
+        "<b>Yᴏᴜ Cᴀɴ Cʜᴀɴɢᴇ Mᴏᴅᴇ Bʏ</b> /mode\n\n"
+        f"<b>Rᴇɴᴀᴍɪɴɢ Mᴏᴅᴇ:</b> <code>{esc(mode.upper())}</code>\n\n"
+        f"<b>Fɪʟᴇɴᴀᴍᴇ:</b>\n{_detail_lines(name_info)}\n\n"
+        f"<b>Cᴀᴘᴛɪᴏɴ Mᴏᴅᴇ:</b>\n{_detail_lines(caption_info)}\n\n"
+        f"<b>Nᴇᴡ Nᴀᴍᴇ:</b>\n<code>{esc(clip(new_name, 150))}</code>"
+    )
+
+
+def ethumb_prompt(minutes: int) -> Panel:
+    text = (
+        "<b>🖼 EXTRACT THUMBNAIL</b>\n\n"
+        "Send me a file or video and I'll send back its thumbnail.\n"
+        "It works for one file at a time: for another file, send /ethumb again.\n"
+        f"I'll wait {minutes} minutes. /cancel to stop."
+    )
+    return text, [[("⏹ Stop", "et:stop")]]
+
+
+RESIZE_PRESETS = ((320, "Thumbnail · 320 px"), (640, "640 px"), (1280, "1280 px"))
+
+
+def describe_box(box: Tuple[int, int]) -> str:
+    width, height = box
+    return f"{width} px" if width == height else f"{width}×{height}"
+
+
+def resize_menu() -> Panel:
+    text = (
+        "<b>🖼 RESIZE IMAGE</b>\n\n"
+        "Choose the size. The picture keeps its shape and fits inside it, and comes back as a JPEG. "
+        "Thumbnail size (320 px) stays under 200 KB, which is what Telegram accepts.\n\n"
+        "Or send the size with the command, like <code>/resize 320x180</code>."
+    )
+    rows: List[Row] = [[(label, f"rz:s:{side}")] for side, label in RESIZE_PRESETS]
+    rows.append([("✏️ Custom size", "rz:custom")])
+    return text, rows + [[("✖ Close", "x:close")]]
+
+
+def resize_ready(box: Tuple[int, int], minutes: int) -> Panel:
+    text = (
+        f"✅ Size: <b>{describe_box(box)}</b>\n\n"
+        "Now send me the image (a photo, or an image sent as a file). I'll resize it and send it back.\n"
+        "It works for one image at a time: for another, send /resize again.\n"
+        f"I'll wait {minutes} minutes. /cancel to stop."
+    )
+    return text, [[("🔄 Change size", "rz:menu"), ("⏹ Stop", "rz:stop")]]
+
+
+RESIZE_CUSTOM_PROMPT = (
+    "<b>Send the size</b> as width and height, like <code>320x180</code>, or one number like <code>320</code> "
+    "for a square box (16 to 4096 pixels). The picture keeps its shape and fits inside the box."
+)
+
+
+def smedia_menu(current: str) -> Panel:
+    """/smedia: ``current`` is what /start shows above the menu now: ``image``, ``gif`` or ``""`` (nothing)."""
+    shown = {"image": "an image", "gif": "a GIF"}.get(current, "nothing, just the menu")
+    text = (
+        "<b>🖼 START MEDIA</b>\n\n"
+        f"/start shows: <b>{shown}</b>\n\n"
+        "Choose what goes above the menu. I keep a copy of it, so it survives restarts."
+    )
+    rows: List[Row] = [[("🖼 Image", "sm:image"), ("🎞 GIF", "sm:gif")]]
+    if current:
+        rows.append([("🗑 Remove", "sm:rm")])
+    return text, rows + [[("✖ Close", "x:close")]]
+
+
+def smedia_prompt(kind: str, minutes: int) -> Panel:
+    what = "the image (a photo, or an image sent as a file)" if kind == "image" else "the GIF (a Telegram GIF or animation)"
+    text = (
+        f"<b>{'🖼' if kind == 'image' else '🎞'} Send {what}.</b>\n\n"
+        "I'll set it as the /start media and show you the result.\n"
+        f"I'll wait {minutes} minutes. /cancel to stop."
+    )
+    return text, [[("◀ Back", "sm:menu"), ("⏹ Stop", "sm:stop")]]
+
+
+def sequence_intro(limit: int) -> Panel:
+    text = (
+        "<b>📑 SEQUENCE</b>\n\n"
+        f"Send me the files to put in order (up to {limit}), in any order. I only collect them for now.\n"
+        "When they're all here, send /sort: I'll send them back in episode order, then list the missing and repeated episodes.\n"
+        "The episode is read from the file name, or from the caption when your /mode is Caption.\n"
+        "/cancel to throw them away."
+    )
+    return text, [[("✖ Cancel", "sq:cx")]]
+
+
+def sequence_status(count: int, limit: int) -> Panel:
+    text = f"📥 <b>{count} file{'s' if count != 1 else ''} collected</b>"
+    if count >= limit:
+        text += f"\n\nThat's the most I can sort at once ({limit}). Send /sort now."
+    else:
+        text += "\n\nSend more files, or /sort when you're done."
+    return text, [[("🔢 Sort now", "sq:sort"), ("🗑 Discard", "sq:cx")]]
+
+
 # ---------------------------------------------------------------------------
 # input prompts
 # ---------------------------------------------------------------------------
@@ -261,5 +467,22 @@ def input_prompt(kind: str, back: str) -> Panel:
     return PROMPTS[kind], [[("✖ Cancel", f"in:cancel:{back}")]]
 
 
+FORMAT_PROMPTS: Dict[str, str] = {
+    "new": "<b>Send a name for the new format</b>, like <code>One Piece</code> or <code>Dragon Ball</code> (30 characters max).",
+    "name": "<b>Send the new name</b> for this format (30 characters max).",
+    "thumb": "<b>Send a photo</b> to use as this format's thumbnail.",
+    "template": PROMPTS["template"],
+    "title": PROMPTS["mt_title"], "author": PROMPTS["mt_author"], "artist": PROMPTS["mt_artist"],
+    "audio": PROMPTS["mt_audio"], "subtitle": PROMPTS["mt_subtitle"], "video": PROMPTS["mt_video"],
+    "keep_audio": PROMPTS["keep_audio"], "keep_subtitle": PROMPTS["keep_subtitle"],
+}
+
+
+def format_prompt(field: str, fid: int) -> Panel:
+    """The "send me the value" screen for one field of a format (``fid`` 0 = a format that is being created)."""
+    cancel = f"fm:cx:{fid}" if fid else "m:formats"
+    return FORMAT_PROMPTS[field], [[("✖ Cancel", cancel)]]
+
+
 def known_languages() -> str:
     return ", ".join(sorted(LANGUAGES))

bot/parser.py

@@ -443,14 +443,6 @@ def compute_new_name(
     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
 # ---------------------------------------------------------------------------

bot/pipeline.py

@@ -16,6 +16,7 @@ from . import media
 from .config import Config
 from .db import Database
 from .errors import Cancelled, MediaError
+from .formats import apply_format
 from .parser import build_values, parse_info, render_caption, split_ext
 from .progress import ProgressReporter
 from .queue import Job
@@ -95,6 +96,8 @@ class Renamer:
     # ------------------------------------------------------------------
     async def process(self, job: Job) -> None:
         s = await self.db.get_settings(job.user_id)
+        if job.fmt:
+            s = apply_format(s, job.fmt)
         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)
@@ -178,7 +181,9 @@ class Renamer:
                 )
             )
 
-        thumb = await self.db.get_thumb(job.user_id)
+        thumb = await self.db.get_format_thumb(job.user_id, job.fmt["id"]) if job.fmt else None
+        if thumb is 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):

bot/queue.py

@@ -20,7 +20,7 @@ class Job:
     file_name: str
     size: int
     new_name: str
-    manual: bool = False
+    fmt: Optional[Dict[str, Any]] = None  # the saved /rename format this job uses (a snapshot taken when it was queued)
     notes: List[str] = field(default_factory=list)  # warnings shown with the queued / finished message
     order: int = 0  # id of the message that triggered the job: files are processed oldest message first
     status_msg: Any = None

bot/sequence.py

@@ -0,0 +1,173 @@
+"""/sequence + /sort: put files in episode order and report which episodes are missing or repeated."""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from .parser import parse_caption, parse_info, split_ext
+from .utils import clip, esc
+
+MAX_LISTED = 12  # names shown per section of the report
+
+
+@dataclass
+class SeqItem:
+    msg_id: int
+    name: str
+    caption: str = ""
+    season: Optional[int] = None
+    episode: Optional[int] = None
+
+
+@dataclass
+class SequenceState:
+    """What /sequence has collected so far for one user."""
+
+    items: List[SeqItem] = field(default_factory=list)
+    status_id: Optional[int] = None  # the "N files collected" message, replaced after each burst of files
+    task: Optional["asyncio.Future[None]"] = None  # the debounced status update that is waiting for the burst to end
+    version: int = 0  # bumped for every file, so the status task can tell whether more are still arriving
+    closed: bool = False  # /sort or /cancel ended the collection
+    full_noted: bool = False  # the "limit reached" notice was shown
+
+
+def detect(name: str, caption: str, mode: str) -> Tuple[Optional[int], Optional[int]]:
+    """``(season, episode)`` read from the file name and the caption, the one the rename mode names first.
+
+    The season is 1 when only an episode number is found; both are ``None`` when there is no episode number.
+    """
+    from_name = lambda: parse_info(split_ext(name)[0])  # noqa: E731
+    from_caption = lambda: parse_caption(caption)  # noqa: E731
+    for read in ((from_caption, from_name) if mode == "caption" else (from_name, from_caption)):
+        info = read()
+        if info.episode.isdigit():
+            return (int(info.season) if info.season.isdigit() else 1), int(info.episode)
+    return None, None
+
+
+@dataclass
+class Analysis:
+    ordered: List[SeqItem]  # numbered files by season / episode, then the others in the order they were sent
+    unknown: List[SeqItem]  # no episode number found
+    missing: Dict[int, List[int]]  # season -> episode numbers absent between its first and last
+    repeated: Dict[Tuple[int, int], List[SeqItem]]  # (season, episode) -> the files that share it
+    first: Optional[Tuple[int, int]] = None
+    last: Optional[Tuple[int, int]] = None
+
+
+def analyse(items: Sequence[SeqItem], mode: str) -> Analysis:
+    for item in items:
+        item.season, item.episode = detect(item.name, item.caption, mode)
+    numbered = sorted((i for i in items if i.episode is not None), key=lambda i: (i.season, i.episode, i.msg_id))
+    unknown = sorted((i for i in items if i.episode is None), key=lambda i: i.msg_id)
+
+    by_season: Dict[int, List[int]] = {}
+    groups: Dict[Tuple[int, int], List[SeqItem]] = {}
+    for item in numbered:
+        by_season.setdefault(item.season, []).append(item.episode)
+        groups.setdefault((item.season, item.episode), []).append(item)
+    missing: Dict[int, List[int]] = {}
+    for season, episodes in by_season.items():
+        have = set(episodes)
+        gaps = [n for n in range(min(have), max(have) + 1) if n not in have]
+        if gaps:
+            missing[season] = gaps
+    return Analysis(
+        ordered=numbered + unknown,
+        unknown=unknown,
+        missing=missing,
+        repeated={k: v for k, v in groups.items() if len(v) > 1},
+        first=(numbered[0].season, numbered[0].episode) if numbered else None,
+        last=(numbered[-1].season, numbered[-1].episode) if numbered else None,
+    )
+
+
+def _ep(n: int) -> str:
+    return f"E{n:02d}"
+
+
+def ranges(numbers: Sequence[int], limit: int = 0) -> str:
+    """``[3, 7, 8, 9]`` -> ``E03, E07–E09``; with ``limit`` the text is cut after that many characters."""
+    spans: List[Tuple[int, int]] = []
+    for n in sorted(set(numbers)):
+        if spans and n == spans[-1][1] + 1:
+            spans[-1] = (spans[-1][0], n)
+        else:
+            spans.append((n, n))
+    texts = [_ep(a) if a == b else f"{_ep(a)}–{_ep(b)}" for a, b in spans]
+    if limit and len(", ".join(texts)) > limit:
+        kept: List[str] = []
+        used = 0
+        for i, text in enumerate(texts):
+            if used + len(text) + 2 > limit - 24:
+                kept.append(f"… and {sum(b - a + 1 for a, b in spans[i:])} more")
+                break
+            kept.append(text)
+            used += len(text) + 2
+        return ", ".join(kept)
+    return ", ".join(texts)
+
+
+def _label(season: int, episode: int, multi: bool) -> str:
+    return f"S{season:02d}{_ep(episode)}" if multi else _ep(episode)
+
+
+def _bullets(lines: Sequence[str]) -> List[str]:
+    out = [f"• {line}" for line in lines[:MAX_LISTED]]
+    if len(lines) > MAX_LISTED:
+        out.append(f"… and {len(lines) - MAX_LISTED} more")
+    return out
+
+
+def report_sections(a: Analysis, total: int, sent: int, failed: Sequence[SeqItem] = (), note: str = "") -> List[str]:
+    """The pieces of the message shown after the files were sent (HTML), each short enough on its own."""
+    seasons = {i.season for i in a.ordered if i.season is not None}
+    multi = len(seasons) > 1
+    head = f"✅ <b>Sorted {sent} of {total} files</b>" if sent != total else f"✅ <b>Sorted {total} file{'s' if total != 1 else ''}</b>"
+    if a.first and a.last:
+        head += f" · {_label(*a.first, multi)} → {_label(*a.last, multi)}"
+    parts = [head]
+    if note:
+        parts.append(note)
+
+    if a.missing:
+        lines = []
+        for season in sorted(a.missing)[:MAX_LISTED]:
+            text = ranges(a.missing[season], limit=300)
+            lines.append(f"S{season:02d}: {text}" if multi else text)
+        if len(a.missing) > MAX_LISTED:
+            lines.append(f"… and {len(a.missing) - MAX_LISTED} more seasons")
+        parts.append("⚠️ <b>Missing episodes</b>\n" + "\n".join(lines))
+    if a.repeated:
+        lines = []
+        for (season, episode), files in sorted(a.repeated.items()):
+            names = ", ".join(f"<code>{esc(clip(f.name, 40))}</code>" for f in files[:3])
+            more = f" +{len(files) - 3} more" if len(files) > 3 else ""
+            lines.append(f"{_label(season, episode, multi)} ×{len(files)}: {names}{more}")
+        parts.append("🔁 <b>Repeated episodes</b>\n" + "\n".join(_bullets(lines)))
+    if a.unknown:
+        lines = [f"<code>{esc(clip(i.name, 50))}</code>" for i in a.unknown]
+        parts.append("❓ <b>No episode number found</b> (sent last)\n" + "\n".join(_bullets(lines)))
+    if failed:
+        lines = [f"<code>{esc(clip(i.name, 50))}</code>" for i in failed]
+        parts.append("🚫 <b>Couldn't be sent</b>\n" + "\n".join(_bullets(lines)))
+    if a.first and not (a.missing or a.repeated):
+        parts.append("No missing or repeated episodes.")
+    return parts
+
+
+def format_report(
+    a: Analysis, total: int, sent: int, failed: Sequence[SeqItem] = (), note: str = "", limit: int = 3600
+) -> List[str]:
+    """The report as one message, or a few when the lists are long (Telegram allows about 4000 characters)."""
+    messages: List[str] = []
+    current = ""
+    for part in report_sections(a, total, sent, failed, note):
+        if current and len(current) + 2 + len(part) > limit:
+            messages.append(current)
+            current = part
+        else:
+            current = f"{current}\n\n{part}" if current else part
+    messages.append(current)
+    return messages

bot/speed.py

@@ -0,0 +1,226 @@
+"""/speed: an Ookla Speedtest run from the bot's own network.
+
+The official Speedtest CLI is used when it is installed.  If it is missing or fails, the ``speedtest-cli`` Python
+package (also an Ookla client) is tried.  Both give the same figures; only the parsing differs.
+"""
+from __future__ import annotations
+
+import asyncio
+import html
+import json
+import logging
+import os
+import shutil
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional
+
+from .utils import esc
+
+log = logging.getLogger(__name__)
+
+CLI_TIMEOUT = 120  # seconds for one run of either client
+CANDIDATES = ("ookla-speedtest", "speedtest")  # the Dockerfile installs the official binary as ookla-speedtest
+
+
+class SpeedError(RuntimeError):
+    """The speed test could not be run; the message is safe to show to the user."""
+
+
+@dataclass
+class SpeedResult:
+    download_mbps: float
+    upload_mbps: float
+    ping_ms: float
+    jitter_ms: Optional[float] = None
+    packet_loss: Optional[float] = None
+    isp: str = ""
+    server: str = ""
+    location: str = ""
+    url: str = ""  # the speedtest.net page of this result
+    source: str = ""
+
+
+def _num(value: Any) -> Optional[float]:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def parse_cli(data: Dict[str, Any]) -> SpeedResult:
+    """The JSON the official CLI prints (bandwidth is in bytes per second)."""
+    download = _num((data.get("download") or {}).get("bandwidth"))
+    upload = _num((data.get("upload") or {}).get("bandwidth"))
+    if download is None or upload is None:
+        raise SpeedError("the Speedtest CLI gave no download or upload figure")
+    ping = data.get("ping") or {}
+    server = data.get("server") or {}
+    location = ", ".join(part for part in (server.get("location"), server.get("country")) if part)
+    return SpeedResult(
+        download_mbps=download * 8 / 1e6,
+        upload_mbps=upload * 8 / 1e6,
+        ping_ms=_num(ping.get("latency")) or 0.0,
+        jitter_ms=_num(ping.get("jitter")),
+        packet_loss=_num(data.get("packetLoss")),
+        isp=str(data.get("isp") or ""),
+        server=str(server.get("name") or server.get("host") or ""),
+        location=location,
+        url=str((data.get("result") or {}).get("url") or ""),
+        source="Ookla Speedtest CLI",
+    )
+
+
+def parse_python(data: Dict[str, Any]) -> SpeedResult:
+    """``Speedtest.results.dict()`` of the speedtest-cli package (speeds are in bits per second)."""
+    download, upload = _num(data.get("download")), _num(data.get("upload"))
+    if download is None or upload is None:
+        raise SpeedError("speedtest-cli gave no download or upload figure")
+    server = data.get("server") or {}
+    client = data.get("client") or {}
+    location = ", ".join(part for part in (server.get("name"), server.get("country")) if part)
+    return SpeedResult(
+        download_mbps=download / 1e6,
+        upload_mbps=upload / 1e6,
+        ping_ms=_num(data.get("ping")) or 0.0,
+        isp=str(client.get("isp") or ""),
+        server=str(server.get("sponsor") or ""),
+        location=location,
+        url=str(data.get("share") or ""),
+        source="speedtest-cli (Ookla)",
+    )
+
+
+def _last_result(stdout: str) -> Optional[Dict[str, Any]]:
+    """The ``{"type": "result", ...}`` line of the CLI's JSON output."""
+    found = None
+    for line in stdout.splitlines():
+        line = line.strip()
+        if not line.startswith("{"):
+            continue
+        try:
+            obj = json.loads(line)
+        except ValueError:
+            continue
+        if isinstance(obj, dict) and obj.get("type") == "result":
+            found = obj
+    return found
+
+
+def _log_message(stdout: str, stderr: str) -> str:
+    """Why the CLI failed, as far as it says."""
+    for text in (stdout, stderr):
+        for line in reversed(text.splitlines()):
+            line = line.strip()
+            if line.startswith("{"):
+                try:
+                    obj = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(obj, dict) and obj.get("message"):
+                    return str(obj["message"])
+            elif line:
+                return line
+    return "no output"
+
+
+async def _run(cmd: List[str], timeout: float) -> "tuple[int, str, str]":
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            *cmd, stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE
+        )
+    except (FileNotFoundError, PermissionError, OSError) as exc:
+        raise SpeedError(f"{cmd[0]} cannot be started ({exc})") from exc
+    try:
+        out, err = await asyncio.wait_for(proc.communicate(), timeout)
+    except asyncio.TimeoutError:
+        proc.kill()
+        await proc.wait()
+        raise SpeedError("the speed test took too long") from None
+    return proc.returncode or 0, out.decode("utf-8", "replace"), err.decode("utf-8", "replace")
+
+
+async def find_ookla_cli() -> Optional[str]:
+    """The official CLI, if installed.  ``speedtest`` can also be the Python package's script, so ``--version`` decides."""
+    names = [os.environ.get("SPEEDTEST_BIN", "")] + list(CANDIDATES)
+    for name in dict.fromkeys(n for n in names if n):
+        path = shutil.which(name)
+        if not path:
+            continue
+        try:
+            code, out, _err = await _run([path, "--version"], 15)
+        except SpeedError:
+            continue
+        if code == 0 and "ookla" in out.lower():
+            return path
+    return None
+
+
+async def run_cli(path: str, timeout: float = CLI_TIMEOUT) -> SpeedResult:
+    code, out, err = await _run([path, "--accept-license", "--accept-gdpr", "--format=json"], timeout)
+    result = _last_result(out)
+    if result is None:
+        raise SpeedError(f"the Speedtest CLI failed: {_log_message(out, err)}")
+    return parse_cli(result)
+
+
+def _run_python() -> Dict[str, Any]:
+    """Blocking: one test with the speedtest-cli package."""
+    try:
+        import speedtest  # type: ignore
+    except ImportError as exc:
+        raise SpeedError("the speedtest-cli package is not installed") from exc
+    try:
+        test = speedtest.Speedtest(secure=True)
+        test.get_best_server()
+        test.download()
+        test.upload()
+        return dict(test.results.dict())
+    except Exception as exc:  # noqa: BLE001 - the package raises its own family of errors
+        raise SpeedError(f"speedtest-cli failed: {exc}") from exc
+
+
+async def run_speedtest() -> SpeedResult:
+    """Run a test with the official CLI, or with the Python client when the CLI is missing or fails."""
+    problems: List[str] = []
+    cli = await find_ookla_cli()
+    if cli is not None:
+        try:
+            return await run_cli(cli)
+        except SpeedError as exc:
+            log.warning("Speedtest CLI failed: %s", exc)
+            problems.append(str(exc))
+    else:
+        problems.append("the Speedtest CLI is not installed")
+    try:
+        data = await asyncio.wait_for(asyncio.to_thread(_run_python), CLI_TIMEOUT)
+        return parse_python(data)
+    except asyncio.TimeoutError:
+        problems.append("speedtest-cli took too long")
+    except SpeedError as exc:
+        problems.append(str(exc))
+    raise SpeedError("; ".join(problems))
+
+
+def _mbps(value: float) -> str:
+    return f"{value:,.2f} Mbps"
+
+
+def format_result(r: SpeedResult) -> str:
+    lines = [
+        "<b>⚡ SPEEDTEST</b> · Ookla",
+        "",
+        f"◈ <b>Download</b> ▸ <code>{_mbps(r.download_mbps)}</code>",
+        f"◈ <b>Upload</b> ▸ <code>{_mbps(r.upload_mbps)}</code>",
+        f"◈ <b>Ping</b> ▸ <code>{r.ping_ms:.2f} ms</code>" + (f" · jitter <code>{r.jitter_ms:.2f} ms</code>" if r.jitter_ms is not None else ""),
+    ]
+    if r.packet_loss is not None:
+        lines.append(f"◈ <b>Packet loss</b> ▸ <code>{r.packet_loss:g}%</code>")
+    if r.isp:
+        lines.append(f"◈ <b>ISP</b> ▸ {esc(r.isp)}")
+    server = " · ".join(part for part in (esc(r.server), esc(r.location)) if part)
+    if server:
+        lines.append(f"◈ <b>Server</b> ▸ {server}")
+    if r.url.startswith(("http://", "https://")):
+        lines.append(f"◈ <b>Result</b> ▸ <a href=\"{html.escape(r.url, quote=True)}\">speedtest.net</a>")
+    lines.append(f"\n<i>Measured from the machine the bot runs on · {esc(r.source)}</i>")
+    return "\n".join(lines)

bot/telegraph.py

@@ -0,0 +1,130 @@
+"""A minimal Telegraph (telegra.ph) client: one account for the bot, pages created from node lists."""
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Any, Awaitable, Callable, Dict, List, Optional
+
+import aiohttp
+
+log = logging.getLogger(__name__)
+
+API = "https://api.telegra.ph"
+CONTENT_LIMIT = 60_000  # Telegraph refuses a page whose content is over 64 KB; stay clear of it
+TITLE_LIMIT = 256
+
+Node = Dict[str, Any]
+
+
+class TelegraphError(RuntimeError):
+    """Telegraph refused or could not be reached; the message is safe to show to the user."""
+
+    def __init__(self, message: str, code: str = ""):
+        super().__init__(message)
+        self.code = code
+
+
+def content_size(nodes: List[Node]) -> int:
+    """Bytes the content takes as it is sent."""
+    return len(dump(nodes).encode("utf-8"))
+
+
+def dump(nodes: List[Node]) -> str:
+    return json.dumps(nodes, ensure_ascii=False, separators=(",", ":"))
+
+
+class Telegraph:
+    """Creates pages under one account.  The access token comes from ``load_token`` and is saved with ``save_token``."""
+
+    def __init__(
+        self,
+        load_token: Callable[[], Awaitable[Optional[str]]],
+        save_token: Callable[[str], Awaitable[None]],
+        *,
+        api: str = API,
+        short_name: str = "AutoRename",
+        author: str = "Auto Rename Bot",
+        timeout: float = 30,
+    ):
+        self._load = load_token
+        self._save = save_token
+        self.api = api.rstrip("/")
+        self.short_name = short_name
+        self.author = author
+        self.author_url = ""
+        self.timeout = timeout
+        self._token: Optional[str] = None
+        self._lock = asyncio.Lock()
+
+    def set_author(self, name: str, url: str = "") -> None:
+        """The name (and link) shown under the title of the pages; the bot's own, once it is known."""
+        if name.strip():
+            self.author = name.strip()[:128]
+            self.author_url = url.strip()[:512]
+
+    async def _call(self, method: str, **params: str) -> Dict[str, Any]:
+        try:
+            async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(total=self.timeout)) as session:
+                async with session.post(f"{self.api}/{method}", data=params) as resp:
+                    data = await resp.json(content_type=None)
+        except asyncio.TimeoutError:
+            raise TelegraphError("Telegraph took too long to answer") from None
+        except (aiohttp.ClientError, ValueError) as exc:
+            raise TelegraphError(f"I couldn't reach Telegraph ({type(exc).__name__})") from exc
+        if not isinstance(data, dict) or not data.get("ok"):
+            code = str(data.get("error") if isinstance(data, dict) else "") or "UNKNOWN"
+            if code.startswith("FLOOD_WAIT_"):
+                raise TelegraphError(f"Telegraph asks to wait {code.rsplit('_', 1)[-1]} seconds", code)
+            raise TelegraphError(f"Telegraph said {code}", code)
+        result = data.get("result")
+        if not isinstance(result, dict):
+            raise TelegraphError("Telegraph sent an answer I don't understand")
+        return result
+
+    async def token(self) -> str:
+        """The account's access token: remembered, else loaded, else a new account is made."""
+        async with self._lock:
+            if self._token:
+                return self._token
+            saved = await self._load()
+            if saved:
+                self._token = saved
+                return saved
+            result = await self._call("createAccount", short_name=self.short_name, author_name=self.author)
+            token = str(result.get("access_token") or "")
+            if not token:
+                raise TelegraphError("Telegraph did not give an access token")
+            self._token = token
+            await self._save(token)
+            return token
+
+    async def _forget_token(self) -> None:
+        async with self._lock:
+            self._token = None
+            await self._save("")
+
+    async def create_page(self, title: str, nodes: List[Node]) -> str:
+        """Create a page and return its URL."""
+        content = dump(nodes)
+        if len(content.encode("utf-8")) > 64 * 1024:
+            raise TelegraphError("The page is too big for Telegraph", "CONTENT_TOO_BIG")
+        for attempt in range(2):
+            token = await self.token()
+            params = {"access_token": token, "title": (title.strip() or "MediaInfo")[:TITLE_LIMIT],
+                      "author_name": self.author, "content": content, "return_content": "false"}
+            if self.author_url:
+                params["author_url"] = self.author_url
+            try:
+                result = await self._call("createPage", **params)
+            except TelegraphError as exc:
+                if exc.code == "ACCESS_TOKEN_INVALID" and attempt == 0:
+                    log.warning("the saved Telegraph token was rejected; making a new account")
+                    await self._forget_token()
+                    continue
+                raise
+            url = str(result.get("url") or "")
+            if not url:
+                raise TelegraphError("Telegraph did not return the page address")
+            return url
+        raise TelegraphError("Telegraph rejected the account twice")  # pragma: no cover - the loop returns or raises

requirements.txt

@@ -6,4 +6,6 @@ asyncpg>=0.29
 aiohttp>=3.9
 psutil>=5.9
 Pillow>=10.0
+pymediainfo>=6.1
+speedtest-cli>=2.1.3
 uvloop>=0.19; sys_platform != "win32"

tests/appkit.py

@@ -0,0 +1,72 @@
+"""Shared fixture and helpers for the handler-level tests (real Telethon event builders, fake events and client)."""
+import io
+from types import SimpleNamespace
+
+import pytest
+from PIL import Image
+
+from bot.app import App
+from bot.config import load_config
+from bot.db import Database
+
+from .tgfakes import FakeCallback, FakeClient, FakeEvent, dispatch, document_message, flat_buttons
+
+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.shutdown()
+    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):
+    message = document_message(name, size, **kw)
+    ctx.client.messages[message.id] = message  # so get_messages() can find it again
+    ev = FakeEvent(sender, message=message)
+    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)]

tests/conftest.py

@@ -9,6 +9,10 @@ import pytest
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 
+from .appkit import ctx  # noqa: E402  the handler-level fixture, shared by every test module
+
+__all__ = ["ctx", "needs_ffmpeg"]
+
 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")
 

tests/faketelegraph.py

@@ -0,0 +1,53 @@
+"""A local stand-in for api.telegra.ph (createAccount and createPage), used by the Telegraph and /mediainfo tests."""
+import asyncio
+
+from aiohttp import web
+from aiohttp.test_utils import TestServer
+
+
+class FakeTelegraph:
+    """api.telegra.ph for tests: createAccount and createPage, with switches for the ways it can go wrong."""
+
+    def __init__(self):
+        self.accounts = 0
+        self.valid = set()
+        self.attempts = []  # every createPage form, accepted or not
+        self.pages = []  # the accepted ones
+        self.error = None  # answer every createPage with this error
+        self.reject_all = False  # a token is never good enough
+        self.delay = 0.0
+        self.raw = None  # (status, body) to answer createPage with instead of JSON
+
+    async def create_account(self, request):
+        form = await request.post()
+        self.accounts += 1
+        token = f"token{self.accounts}"
+        self.valid.add(token)
+        return web.json_response({"ok": True, "result": {"short_name": form["short_name"], "access_token": token}})
+
+    async def create_page(self, request):
+        form = dict(await request.post())
+        self.attempts.append(form)
+        if self.delay:
+            await asyncio.sleep(self.delay)
+        if self.raw is not None:
+            return web.Response(status=self.raw[0], text=self.raw[1], content_type="text/html")
+        if self.error:
+            return web.json_response({"ok": False, "error": self.error})
+        if self.reject_all or form.get("access_token") not in self.valid:
+            return web.json_response({"ok": False, "error": "ACCESS_TOKEN_INVALID"})
+        self.pages.append(form)
+        n = len(self.pages)
+        return web.json_response({"ok": True, "result": {"path": f"Page-{n}", "url": f"https://telegra.ph/Page-{n}", "title": form["title"]}})
+
+
+async def serve_fake_telegraph() -> "FakeTelegraph":
+    """Start the fake server; ``fake.url`` is the API address and ``await fake.server.close()`` stops it."""
+    fake = FakeTelegraph()
+    app = web.Application()
+    app.router.add_post("/createAccount", fake.create_account)
+    app.router.add_post("/createPage", fake.create_page)
+    fake.server = TestServer(app)
+    await fake.server.start_server()
+    fake.url = str(fake.server.make_url("")).rstrip("/")
+    return fake

tests/test_app.py

@@ -1,14 +1,10 @@
 """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
@@ -19,69 +15,11 @@ from bot.db import Database
 from bot.queue import JobQueue
 
 from .conftest import needs_ffmpeg
+from .appkit import ADMIN_CFG, ADMIN_DB, EPISODE, EPISODE_NEW, LOG, OWNER, STRANGER, click, data_of, env_for, jpeg, prefs, say, send_doc
 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
 # ---------------------------------------------------------------------------
@@ -186,18 +124,6 @@ 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")
@@ -370,7 +296,7 @@ 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"
+    assert job.file_name == EPISODE and job.size == 50 * 1024 * 1024 and job.fmt is None 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}")]
@@ -407,7 +333,7 @@ async def test_a_template_variable_that_cannot_be_filled_is_flagged(ctx):
     ev = await send_doc(ctx, OWNER, "Plain Movie.mkv")
     (job,) = ctx.app.queue.jobs.values()
     assert job.new_name == "One Piece - E.mkv"
-    assert "⚠️" in ev.texts[0] and "{episode}" in ev.texts[0] and "file name" in ev.texts[0] and "/rename" in ev.texts[0]
+    assert "⚠️" in ev.texts[0] and "{episode}" in ev.texts[0] and "file name" in ev.texts[0] and "change the template" in ev.texts[0]
     assert job.notes and "{episode}" in job.notes[0]
 
     await say(ctx, OWNER, "/mode caption")
@@ -415,12 +341,9 @@ async def test_a_template_variable_that_cannot_be_filled_is_flagged(ctx):
     assert "in the caption" in ev.texts[0]
 
 
-async def test_default_template_and_manual_names_never_warn(ctx):
+async def test_the_default_template_never_warns(ctx):
     ev = await send_doc(ctx, OWNER, "Plain Movie.mkv")
     assert "⚠️" not in ev.texts[0]  # bracket groups vanish on purpose
-    await say(ctx, OWNER, "/template One Piece - E{episode}")
-    ev = await say(ctx, OWNER, "/rename My Name", reply=document_message("Plain Movie.mkv", mid=40), mid=41)
-    assert "⚠️" not in ev.texts[0]
 
 
 class SlowEvent(FakeEvent):
@@ -438,7 +361,7 @@ class SlowEvent(FakeEvent):
 async def test_jobs_are_ordered_by_the_message_that_triggered_them(ctx):
     await send_doc(ctx, OWNER, "B.mkv", mid=31)
     await send_doc(ctx, OWNER, "A.mkv", mid=30)
-    await say(ctx, OWNER, "/rename X", reply=document_message("old.mkv", 1024, mid=5), mid=34)
+    await send_doc(ctx, OWNER, "old.mkv", 1024, mid=34)
     assert sorted(j.order for j in ctx.app.queue.jobs.values()) == [30, 31, 34]
     assert [j.file_name for j in ctx.app.queue.for_user(OWNER)] == ["A.mkv", "B.mkv", "old.mkv"]
 
@@ -467,30 +390,6 @@ async def test_a_forwarded_batch_comes_out_in_the_order_it_was_sent(ctx):
     assert ran == [names[1145], names[1146], names[1147]]
 
 
-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

tests/test_check.py

@@ -0,0 +1,83 @@
+"""/check: what the bot can read from a file's name and caption."""
+from .appkit import OWNER, say
+from .tgfakes import FakeMessage, document_message
+
+NAME = "[S01 E02] Dragon Ball Super Beerus [1080p].mkv"
+
+
+def detail(text, block, label):
+    """The value shown for ``label`` inside the ``block`` ("Fɪʟᴇɴᴀᴍᴇ" / "Cᴀᴘᴛɪᴏɴ Mᴏᴅᴇ") of a /check reply."""
+    section = text.split(f"<b>{block}:</b>\n", 1)[1].split("\n\n", 1)[0]
+    line = next(ln for ln in section.splitlines() if ln.startswith(f"➦ {label} ⇛"))
+    return line.split("<code>", 1)[1].split("</code>", 1)[0]
+
+
+async def test_check_lists_what_it_reads_from_the_name_and_the_caption(ctx):
+    reply = document_message(NAME, caption="Dragon Ball Super Beerus - S01E02 [720p]")
+    ev = await say(ctx, OWNER, "/check", reply=reply)
+    text = ev.texts[0]
+    assert text.startswith("<b>Yᴏᴜ Cᴀɴ Cʜᴀɴɢᴇ Mᴏᴅᴇ Bʏ</b> /mode")
+    assert "<b>Rᴇɴᴀᴍɪɴɢ Mᴏᴅᴇ:</b> <code>FILENAME</code>" in text
+    for label, expected in (("Title", "Dragon Ball Super Beerus"), ("Season", "01"), ("Episode", "02"), ("Quality", "1080p")):
+        assert detail(text, "Fɪʟᴇɴᴀᴍᴇ", label) == expected
+    for label, expected in (("Title", "Dragon Ball Super Beerus"), ("Season", "01"), ("Episode", "02"), ("Quality", "720p")):
+        assert detail(text, "Cᴀᴘᴛɪᴏɴ Mᴏᴅᴇ", label) == expected
+    assert ev.out[0][2]["parse_mode"] == "html"
+
+
+async def test_there_is_no_chapter_field(ctx):
+    ev = await say(ctx, OWNER, "/check", reply=document_message(NAME))
+    assert "Chapter" not in ev.texts[0]
+
+
+async def test_what_is_not_found_shows_as_none(ctx):
+    ev = await say(ctx, OWNER, "/check", reply=document_message("holiday video.mp4"))
+    text = ev.texts[0]
+    assert detail(text, "Fɪʟᴇɴᴀᴍᴇ", "Season") == "None" and detail(text, "Fɪʟᴇɴᴀᴍᴇ", "Episode") == "None"
+    assert all(detail(text, "Cᴀᴘᴛɪᴏɴ Mᴏᴅᴇ", f) == "None" for f in ("Title", "Season", "Episode", "Quality"))
+    assert "Year" not in text and "Codec" not in text  # only listed when there is one
+
+
+async def test_year_and_codec_show_up_when_the_file_has_them(ctx):
+    ev = await say(ctx, OWNER, "/check", reply=document_message("Some Movie (2023) 1080p x265.mkv"))
+    assert detail(ev.texts[0], "Fɪʟᴇɴᴀᴍᴇ", "Year") == "2023" and detail(ev.texts[0], "Fɪʟᴇɴᴀᴍᴇ", "Codec") != "None"
+
+
+async def test_the_current_mode_is_shown_and_decides_the_new_name(ctx):
+    await say(ctx, OWNER, "/template [S{season}E{episode}] {title} [{quality}]")
+    reply = document_message("random.mkv", caption="One Piece - S01E1147 [720p]")
+    ev = await say(ctx, OWNER, "/check", reply=reply)
+    assert "<code>FILENAME</code>" in ev.texts[0]
+    assert "<b>Nᴇᴡ Nᴀᴍᴇ:</b>\n<code>random.mkv</code>" in ev.texts[0]  # nothing to read in the name, so it is left as it is
+
+    await say(ctx, OWNER, "/mode caption")
+    ev = await say(ctx, OWNER, "/check", reply=reply)
+    assert "<b>Rᴇɴᴀᴍɪɴɢ Mᴏᴅᴇ:</b> <code>CAPTION</code>" in ev.texts[0]
+    assert "<code>[S01E1147] One Piece [720p].mkv</code>" in ev.texts[0]
+    assert detail(ev.texts[0], "Fɪʟᴇɴᴀᴍᴇ", "Episode") == "None" and detail(ev.texts[0], "Cᴀᴘᴛɪᴏɴ Mᴏᴅᴇ", "Episode") == "1147"
+
+
+async def test_the_new_name_follows_the_users_template_and_remove_words(ctx):
+    await say(ctx, OWNER, "/template {title} - E{episode}")
+    await say(ctx, OWNER, "/removewords @Anime_X_Universe")
+    reply = document_message("1147 - One Piece [Dual] 720p @Anime_X_Universe.mkv")
+    ev = await say(ctx, OWNER, "/check", reply=reply)
+    assert "<code>One Piece - E1147.mkv</code>" in ev.texts[0]
+    assert detail(ev.texts[0], "Fɪʟᴇɴᴀᴍᴇ", "Episode") == "1147" and detail(ev.texts[0], "Fɪʟᴇɴᴀᴍᴇ", "Title") == "One Piece"
+
+
+async def test_values_are_escaped(ctx):
+    ev = await say(ctx, OWNER, "/check", reply=document_message("Fate <b>Zero</b> & Co - 03.mkv"))
+    assert "<b>Zero</b>" not in ev.texts[0].split("Fɪʟᴇɴᴀᴍᴇ")[1] and "&lt;b&gt;" in ev.texts[0]
+
+
+async def test_check_without_a_file_explains_itself(ctx):
+    for kwargs in ({}, {"reply": FakeMessage("just text")}, {"reply": FakeMessage("", photo=True)}):
+        ev = await say(ctx, OWNER, "/check", **kwargs)
+        assert "Reply to a file with /check" in ev.texts[0] and "Fɪʟᴇɴᴀᴍᴇ" not in ev.texts[0]
+
+
+async def test_check_is_in_the_command_menu(ctx):
+    from bot.app import COMMANDS
+
+    assert "check" in dict(COMMANDS)

tests/test_ethumb.py

@@ -0,0 +1,209 @@
+"""/ethumb: ask for a file or video, send back its thumbnail."""
+import io
+import shutil
+import time
+from pathlib import Path
+from types import SimpleNamespace
+
+from PIL import Image
+from telethon import types
+
+from bot import app as appmod
+
+from .appkit import OWNER, STRANGER, click, data_of, jpeg, say, send_doc
+from .conftest import needs_ffmpeg
+from .tgfakes import FakeEvent, FakeMessage, dispatch, document_message
+
+REAL_THUMB = [SimpleNamespace(type="m")]  # stands in for a PhotoSize
+STRIPPED = [types.PhotoStrippedSize(type="i", bytes=b"\x01\x14\x28abc")]
+
+
+def photos_sent(ctx):
+    return [(entity, file, kw) for entity, file, kw in ctx.client.files if isinstance(file, io.BytesIO)]
+
+
+def temp_leftovers(ctx):
+    root = Path(ctx.cfg.temp_dir)
+    return list(root.glob("ethumb*")) if root.exists() else []
+
+
+def serve(monkeypatch, media_dir, name="sample.mkv"):
+    """Make transfer.download copy a real sample file; returns the list of calls."""
+    calls = []
+
+    async def fake_download(client, message, dest, **kw):
+        calls.append(kw)
+        shutil.copy(media_dir / name, dest)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    return calls
+
+
+# ---------------------------------------------------------------------------
+# the flow
+# ---------------------------------------------------------------------------
+
+
+async def test_ethumb_asks_for_a_file(ctx):
+    ev = await say(ctx, OWNER, "/ethumb")
+    assert "EXTRACT THUMBNAIL" in ev.texts[0] and "one file at a time" in ev.texts[0] and "/cancel" in ev.texts[0]
+    assert data_of(ev.out[0][1]) == ["et:stop"]
+    mode = ctx.app.modes[OWNER]
+    assert mode.kind == "ethumb" and mode.expires > time.time() + 500
+
+
+async def test_the_files_own_telegram_thumbnail_is_sent_when_it_has_one(ctx, monkeypatch):
+    async def no_download(*a, **kw):
+        raise AssertionError("nothing needs downloading when Telegram already has a preview")
+
+    monkeypatch.setattr(appmod.transfer, "download", no_download)
+    await say(ctx, OWNER, "/ethumb")
+    ctx.client.thumb_data[60] = jpeg((320, 180))
+    ev = await send_doc(ctx, OWNER, "Episode 01.mp4", thumbs=REAL_THUMB, mid=60)
+    assert ev.texts == ["🖼 Extracting the thumbnail…"]
+    (entity, file, kw), = photos_sent(ctx)
+    assert entity == OWNER and file.name == "thumbnail.jpg" and Image.open(io.BytesIO(file.getvalue())).size == (320, 180)
+    assert "Thumbnail of <b>Episode 01.mp4</b>" in kw["caption"] and kw["parse_mode"] == "html"
+    assert (OWNER, [1001]) in ctx.client.deleted  # the "Extracting…" message goes
+    assert OWNER not in ctx.app.modes and ctx.client.downloads == [(60, bytes, -1)]
+
+
+@needs_ffmpeg
+async def test_without_a_telegram_thumbnail_a_frame_is_grabbed_from_the_video(ctx, media_dir, monkeypatch):
+    calls = serve(monkeypatch, media_dir)
+    await say(ctx, OWNER, "/ethumb")
+    await send_doc(ctx, OWNER, "Show - 05.mkv", size=(media_dir / "sample.mkv").stat().st_size, mid=61)
+    (_e, file, kw), = photos_sent(ctx)
+    img = Image.open(io.BytesIO(file.getvalue()))
+    assert img.format == "JPEG" and img.size == (320, 240)
+    assert len(calls) == 1 and calls[0]["max_bytes"] == appmod.TRACKS_PROBE_BYTES
+    assert "Show - 05.mkv" in kw["caption"] and (OWNER, [1001]) in ctx.client.deleted
+    assert temp_leftovers(ctx) == []
+
+
+@needs_ffmpeg
+async def test_the_whole_file_is_fetched_when_the_start_has_no_picture(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)  # an mp4 whose index is at the end
+        else:
+            shutil.copy(media_dir / "sample.mp4", dest)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    await say(ctx, OWNER, "/ethumb")
+    await send_doc(ctx, OWNER, "Movie.mp4", size=40 * 1024 * 1024, mid=62)
+    assert len(calls) == 2 and "max_bytes" not in calls[1]
+    assert len(photos_sent(ctx)) == 1 and temp_leftovers(ctx) == []
+
+
+@needs_ffmpeg
+async def test_a_file_with_no_picture_anywhere_gets_an_honest_answer(ctx, monkeypatch):
+    async def junk(client, message, dest, **kw):
+        Path(dest).write_bytes(b"\x00" * 4096)
+
+    monkeypatch.setattr(appmod.transfer, "download", junk)
+    for size in (2 * 1024 * 1024, 900 * 1024 * 1024):  # small / too big to fetch whole
+        ctx.client.edited.clear()
+        await say(ctx, OWNER, "/ethumb")
+        await send_doc(ctx, OWNER, "Broken.mkv", size=size, mid=63)
+        assert "couldn't find a thumbnail" in ctx.client.edited[-1][1], size
+    assert photos_sent(ctx) == [] and temp_leftovers(ctx) == []
+
+
+async def test_files_that_cannot_have_a_frame_are_not_downloaded(ctx, monkeypatch):
+    async def no_download(*a, **kw):
+        raise AssertionError("a zip has no picture to grab")
+
+    monkeypatch.setattr(appmod.transfer, "download", no_download)
+    await say(ctx, OWNER, "/ethumb")
+    await send_doc(ctx, OWNER, "archive.zip", size=5 * 1024 * 1024, video=False, mime="application/zip", mid=64)
+    assert "couldn't find a thumbnail" in ctx.client.edited[-1][1] and photos_sent(ctx) == []
+
+
+@needs_ffmpeg
+async def test_the_tiny_blurred_preview_is_only_the_last_resort(ctx, media_dir, monkeypatch):
+    serve(monkeypatch, media_dir)
+    await say(ctx, OWNER, "/ethumb")
+    ctx.client.thumb_data[65] = b"BLURRY-PREVIEW"
+    await send_doc(ctx, OWNER, "Show.mkv", size=(media_dir / "sample.mkv").stat().st_size, thumbs=STRIPPED, mid=65)
+    (_e, file, _kw), = photos_sent(ctx)
+    assert file.getvalue() != b"BLURRY-PREVIEW" and Image.open(io.BytesIO(file.getvalue())).size == (320, 240)  # a real frame wins
+
+    async def junk(client, message, dest, **kw):
+        Path(dest).write_bytes(b"\x00" * 4096)
+
+    monkeypatch.setattr(appmod.transfer, "download", junk)
+    await say(ctx, OWNER, "/ethumb")
+    await send_doc(ctx, OWNER, "Show2.mkv", size=2 * 1024 * 1024, thumbs=STRIPPED, mid=65)
+    assert photos_sent(ctx)[-1][1].getvalue() == b"BLURRY-PREVIEW"  # nothing better could be made
+
+
+async def test_ethumb_as_a_reply_works_at_once_without_asking(ctx):
+    ctx.client.thumb_data[66] = jpeg((320, 180))
+    reply = document_message("Episode.mp4", mid=66, thumbs=REAL_THUMB)
+    await say(ctx, OWNER, "/ethumb", reply=reply, mid=67)
+    assert len(photos_sent(ctx)) == 1 and OWNER not in ctx.app.modes
+
+
+async def test_it_handles_one_file_per_command(ctx):
+    ctx.client.thumb_data[70] = jpeg()
+    await say(ctx, OWNER, "/ethumb")
+    await send_doc(ctx, OWNER, "One.mp4", thumbs=REAL_THUMB, mid=70)
+    extra = await send_doc(ctx, OWNER, "Two.mp4", thumbs=REAL_THUMB, mid=71)  # right after: a hint, not an auto-rename
+    assert "/ethumb handles one file at a time" in extra.texts[0] and ctx.app.queue.waiting == 0
+    assert (await send_doc(ctx, OWNER, "Three.mp4", thumbs=REAL_THUMB, mid=72)).out == []  # further ones: silence
+    assert len(photos_sent(ctx)) == 1
+    ctx.app._recent[OWNER][1] -= appmod.ONE_SHOT_GRACE + 1
+    later = await send_doc(ctx, OWNER, "Four.mp4", mid=73)
+    assert "Queued" in later.texts[0]  # normal auto-rename is back
+
+
+async def test_a_photo_while_waiting_still_sets_the_thumbnail_as_usual(ctx):
+    await say(ctx, OWNER, "/ethumb")
+    await dispatch(ctx.client, FakeEvent(OWNER, message=FakeMessage("", photo=True, mid=80), photo_bytes=jpeg()))
+    assert await ctx.db.has_thumb(OWNER) and ctx.app.modes[OWNER].kind == "ethumb"
+
+
+async def test_cancel_and_the_stop_button_end_it(ctx):
+    await say(ctx, OWNER, "/ethumb")
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Cancelled" in ev.texts[0] and OWNER not in ctx.app.modes
+    ev = await send_doc(ctx, OWNER, "A.mkv", mid=90)
+    assert "Queued" in ev.texts[0]
+
+    await say(ctx, OWNER, "/ethumb")
+    cb = await click(ctx, OWNER, "et:stop")
+    assert "Stopped" in cb.edits[-1][0] and OWNER not in ctx.app.modes
+
+
+async def test_it_expires(ctx):
+    await say(ctx, OWNER, "/ethumb")
+    ctx.app.modes[OWNER].expires = time.time() - 1
+    ev = await send_doc(ctx, OWNER, "A.mkv", mid=91)
+    assert "Queued" in ev.texts[0]
+
+
+async def test_strangers_cannot_use_it(ctx):
+    ev = await say(ctx, STRANGER, "/ethumb")
+    assert ev.out == [] and STRANGER not in ctx.app.modes
+
+
+async def test_starting_it_ends_a_sequence_and_says_so(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await send_doc(ctx, OWNER, "Show - 01.mkv", mid=92)
+    ev = await say(ctx, OWNER, "/ethumb")
+    assert "1 file(s) was discarded" in ev.texts[0] and ctx.app.modes[OWNER].kind == "ethumb"
+
+
+async def test_a_failing_extraction_is_reported_not_raised(ctx, monkeypatch):
+    async def boom(*a, **kw):
+        raise RuntimeError("network down")
+
+    monkeypatch.setattr(appmod.transfer, "download", boom)
+    await say(ctx, OWNER, "/ethumb")
+    ev = await send_doc(ctx, OWNER, "A.mkv", mid=93)
+    assert ev.texts == ["🖼 Extracting the thumbnail…"] and "couldn't find a thumbnail" in ctx.client.edited[-1][1]
+    assert temp_leftovers(ctx) == []

tests/test_formats.py

@@ -0,0 +1,202 @@
+import pytest
+
+from bot.db import DEFAULT_FORMAT, DEFAULT_SETTINGS, MAX_FORMATS, Database
+from bot.errors import FormatError
+from bot.formats import NAME_MAX, FormatSettings, apply_format, has_metadata, validate_name
+from bot.settings_ops import apply_setting
+
+U, V = 111, 222
+
+
+@pytest.fixture
+async def db(tmp_path):
+    database = Database(f"sqlite+aiosqlite:///{tmp_path}/f.db")
+    await database.init()
+    yield database
+    await database.close()
+
+
+# ---------------------------------------------------------------------------
+# storage
+# ---------------------------------------------------------------------------
+
+
+async def test_a_new_format_has_defaults_and_shows_up_in_the_list(db):
+    fmt = await db.create_format(U, "One Piece")
+    assert fmt["name"] == "One Piece" and fmt["id"] > 0 and fmt["has_thumb"] is False
+    assert {k: fmt[k] for k in DEFAULT_FORMAT} == DEFAULT_FORMAT
+    await db.create_format(U, "Dragon Ball", template="DB - E{episode}")
+    listed = await db.list_formats(U)
+    assert [f["name"] for f in listed] == ["One Piece", "Dragon Ball"]  # creation order
+    assert listed[1]["template"] == "DB - E{episode}"
+    assert await db.count_formats(U) == 2 and await db.count_formats(V) == 0
+    assert (await db.get_format(U, fmt["id"]))["name"] == "One Piece"
+
+
+async def test_names_are_unique_per_user_ignoring_case(db):
+    await db.create_format(U, "One Piece")
+    with pytest.raises(FormatError) as exc:
+        await db.create_format(U, "one piece")
+    assert exc.value.code == "taken"
+    await db.create_format(V, "One Piece")  # someone else may use the same name
+
+
+async def test_a_user_can_save_twelve_formats_and_no_more(db):
+    for i in range(MAX_FORMATS):
+        await db.create_format(U, f"Format {i}")
+    with pytest.raises(FormatError) as exc:
+        await db.create_format(U, "One too many")
+    assert exc.value.code == "limit"
+    first = (await db.list_formats(U))[0]
+    assert await db.delete_format(U, first["id"])
+    await db.create_format(U, "One too many")  # a slot is free again
+    assert await db.count_formats(U) == MAX_FORMATS
+
+
+async def test_update_changes_fields_and_merges_meta(db):
+    fmt = await db.create_format(U, "One Piece")
+    out = await db.update_format(U, fmt["id"], template="One Piece - E{episode}", keep_audio=["japanese", "english"])
+    assert out["template"] == "One Piece - E{episode}" and out["keep_audio"] == ["japanese", "english"]
+    await db.update_format(U, fmt["id"], meta={"title": "One Piece"})
+    out = await db.update_format(U, fmt["id"], meta={"author": "@Me"}, keep_subtitle=["english"])
+    assert out["meta"]["title"] == "One Piece" and out["meta"]["author"] == "@Me" and out["meta"]["artist"] == ""
+    assert out["keep_subtitle"] == ["english"]
+    with pytest.raises(KeyError):
+        await db.update_format(U, fmt["id"], bogus=1)
+
+
+async def test_formats_persist_across_database_instances(db):
+    fmt = await db.create_format(U, "One Piece", template="X {title}")
+    await db.update_format(U, fmt["id"], meta={"video": "V"}, keep_audio=["2", "1"])
+    await db.set_format_thumb(U, fmt["id"], b"jpegbytes")
+    other = Database(db.url)
+    got = await other.get_format(U, fmt["id"])
+    assert got["template"] == "X {title}" and got["meta"]["video"] == "V" and got["keep_audio"] == ["2", "1"] and got["has_thumb"]
+    assert await other.get_format_thumb(U, fmt["id"]) == b"jpegbytes"
+    await other.close()
+
+
+async def test_renaming_a_format_checks_the_other_names_only(db):
+    a = await db.create_format(U, "One Piece")
+    await db.create_format(U, "Dragon Ball")
+    assert (await db.update_format(U, a["id"], name="ONE PIECE"))["name"] == "ONE PIECE"  # its own name, new case
+    with pytest.raises(FormatError):
+        await db.update_format(U, a["id"], name="dragon ball")
+    assert (await db.get_format(U, a["id"]))["name"] == "ONE PIECE"
+
+
+async def test_thumbnails_belong_to_one_format(db):
+    a = await db.create_format(U, "A")
+    b = await db.create_format(U, "B")
+    assert await db.get_format_thumb(U, a["id"]) is None
+    assert await db.set_format_thumb(U, a["id"], b"A-thumb")
+    assert [f["has_thumb"] for f in await db.list_formats(U)] == [True, False]
+    assert await db.get_format_thumb(U, b["id"]) is None
+    assert await db.set_format_thumb(U, a["id"], None)
+    assert (await db.get_format(U, a["id"]))["has_thumb"] is False
+
+
+async def test_nobody_can_touch_another_users_format(db):
+    fmt = await db.create_format(U, "Mine")
+    assert await db.get_format(V, fmt["id"]) is None
+    assert await db.update_format(V, fmt["id"], template="x") is None
+    assert await db.set_format_thumb(V, fmt["id"], b"x") is False
+    assert await db.get_format_thumb(V, fmt["id"]) is None
+    assert await db.delete_format(V, fmt["id"]) is False
+    assert (await db.get_format(U, fmt["id"]))["name"] == "Mine"
+
+
+async def test_delete_and_missing_ids(db):
+    fmt = await db.create_format(U, "Gone")
+    assert await db.delete_format(U, fmt["id"]) is True
+    assert await db.delete_format(U, fmt["id"]) is False
+    assert await db.get_format(U, fmt["id"]) is None and await db.update_format(U, fmt["id"], template="x") is None
+
+
+# ---------------------------------------------------------------------------
+# helpers
+# ---------------------------------------------------------------------------
+
+
+def test_validate_name():
+    assert validate_name("  One   Piece  ") == (True, "One Piece")
+    assert validate_name("")[0] is False and validate_name("   ")[0] is False and validate_name(None)[0] is False
+    ok, msg = validate_name("x" * (NAME_MAX + 1))
+    assert not ok and str(NAME_MAX) in msg
+    assert validate_name("x" * NAME_MAX)[0] is True
+    assert validate_name("one\npiece") == (True, "one piece")
+
+
+def fmt_with(**kw):
+    base = {"id": 1, "name": "F", "has_thumb": False, "template": "T {title}",
+            "meta": dict(DEFAULT_FORMAT["meta"]), "keep_audio": [], "keep_subtitle": []}
+    base.update(kw)
+    return base
+
+
+def test_apply_format_lays_the_format_over_the_settings_without_mutating_them():
+    settings = dict(DEFAULT_SETTINGS, mode="caption", caption="<b>{filename}</b>", file_type="document", remove_words=["x"],
+                    target_channel=-100123, metadata_on=False, keep_audio=["french"])
+    settings["meta"] = dict(DEFAULT_SETTINGS["meta"], title="GLOBAL TITLE")
+    fmt = fmt_with(template="One Piece - E{episode}", meta=dict(DEFAULT_FORMAT["meta"], author="@Me"), keep_subtitle=["english"])
+    out = apply_format(settings, fmt)
+    assert out["template"] == "One Piece - E{episode}"
+    assert out["meta"]["author"] == "@Me" and out["meta"]["title"] == ""  # the format's own metadata, not the global one
+    assert out["keep_audio"] == [] and out["keep_subtitle"] == ["english"]
+    assert out["metadata_on"] is True
+    # everything else is still the user's
+    assert (out["mode"], out["caption"], out["file_type"], out["remove_words"], out["target_channel"]) == (
+        "caption", "<b>{filename}</b>", "document", ["x"], -100123)
+    assert settings["template"] == DEFAULT_SETTINGS["template"] and settings["meta"]["title"] == "GLOBAL TITLE"
+
+
+def test_a_format_without_metadata_leaves_the_file_alone():
+    assert not has_metadata(fmt_with())
+    settings = dict(DEFAULT_SETTINGS, metadata_on=True)  # global metadata on, but the format sets nothing
+    assert apply_format(settings, fmt_with())["metadata_on"] is False
+    assert has_metadata(fmt_with(keep_audio=["1"])) and has_metadata(fmt_with(meta=dict(DEFAULT_FORMAT["meta"], video="v")))
+
+
+# ---------------------------------------------------------------------------
+# editing a format through the shared validation
+# ---------------------------------------------------------------------------
+
+
+async def test_settings_ops_edit_a_format_with_the_same_rules_as_the_global_settings(db):
+    fmt = await db.create_format(U, "One Piece")
+    store = FormatSettings(db, fmt["id"])
+
+    ok, msg = await apply_setting(store, U, "template", "One Piece - E{episode}")
+    assert ok and "Template saved" in msg and "One Piece - E" in msg
+    ok, msg = await apply_setting(store, U, "mt_title", "One Piece")
+    assert ok and "Metadata is Off" not in msg
+    ok, _ = await apply_setting(store, U, "mt_audio", "{lang} Audio")
+    assert ok
+    ok, msg = await apply_setting(store, U, "keep_audio", "Japanese English")
+    assert ok and "turned it On" not in msg
+    ok, _ = await apply_setting(store, U, "keep_subtitle", "2 1")
+    assert ok
+
+    got = await db.get_format(U, fmt["id"])
+    assert got["template"] == "One Piece - E{episode}"
+    assert got["meta"]["title"] == "One Piece" and got["meta"]["audio"] == "{lang} Audio"
+    assert got["keep_audio"] == ["japanese", "english"] and got["keep_subtitle"] == ["2", "1"]
+    # the user's own settings were not touched
+    assert await db.get_settings(U) == DEFAULT_SETTINGS
+
+    ok, msg = await apply_setting(store, U, "keep_audio", "off")
+    assert ok and "cleared" in msg and (await db.get_format(U, fmt["id"]))["keep_audio"] == []
+    ok, msg = await apply_setting(store, U, "mt_title", "off")
+    assert ok and (await db.get_format(U, fmt["id"]))["meta"]["title"] == ""
+    ok, msg = await apply_setting(store, U, "keep_audio", "bad!word")
+    assert not ok and "❌" in msg
+
+
+async def test_editing_a_deleted_format_raises_lookup_error(db):
+    fmt = await db.create_format(U, "Gone")
+    store = FormatSettings(db, fmt["id"])
+    await db.delete_format(U, fmt["id"])
+    with pytest.raises(LookupError):
+        await apply_setting(store, U, "template", "x {title}")
+    with pytest.raises(LookupError):
+        await store.get_settings(U)

tests/test_formats_app.py

@@ -0,0 +1,436 @@
+"""/formats (the manager) and /rename (pick a format, send one file)."""
+import asyncio
+import time
+
+from bot import app as appmod
+from bot import panels
+from bot.db import MAX_FORMATS
+
+from .appkit import ADMIN_CFG, EPISODE, OWNER, click, data_of, jpeg, say, send_doc
+from .tgfakes import FakeEvent, FakeMessage, dispatch, document_message
+
+ONE_PIECE = "1147 - One Piece [Dual] 720p @Anime_X_Universe.mkv"
+
+
+async def make_format(ctx, name="One Piece", uid=OWNER, **changes):
+    fmt = await ctx.db.create_format(uid, name, template="One Piece - E{episode}")
+    if changes:
+        fmt = await ctx.db.update_format(uid, fmt["id"], **changes)
+    return fmt
+
+
+# ---------------------------------------------------------------------------
+# the manager
+# ---------------------------------------------------------------------------
+
+
+async def test_formats_command_lists_the_formats_and_offers_a_new_one(ctx):
+    ev = await say(ctx, OWNER, "/formats")
+    assert "FORMATS" in ev.texts[0] and "(0/12)" in ev.texts[0] and "no formats yet" in ev.texts[0]
+    assert "fm:new" in data_of(ev.out[0][1])
+
+    a, b = await make_format(ctx, "One Piece"), await make_format(ctx, "Dragon Ball")
+    ev = await say(ctx, OWNER, "/formats")
+    data = data_of(ev.out[0][1])
+    assert "(2/12)" in ev.texts[0] and f"fm:v:{a['id']}" in data and f"fm:v:{b['id']}" in data and "fm:new" in data
+    labels = [label for row in ev.out[0][1] for label in [b.text for b in row]]
+    assert "One Piece" in labels and "Dragon Ball" in labels
+
+
+async def test_formats_are_reachable_from_the_home_menu(ctx):
+    ev = await say(ctx, OWNER, "/start")
+    assert "m:formats" in data_of(ev.out[0][1])
+    cb = await click(ctx, OWNER, "m:formats")
+    assert "FORMATS" in cb.edits[-1][0] and cb.answers
+
+
+async def test_creating_a_format_asks_for_a_name_and_opens_it(ctx):
+    await say(ctx, OWNER, "/template Mine - {title}")
+    cb = await click(ctx, OWNER, "fm:new", msg_id=500)
+    p = ctx.app.pending[OWNER]
+    assert p.kind == "fmt:new" and p.fid == 0 and p.msg_id == 500
+    assert cb.edits[-1][0] == panels.FORMAT_PROMPTS["new"] and data_of(cb.edits[-1][1]) == ["m:formats"]
+
+    ev = await say(ctx, OWNER, "  One   Piece ", mid=60)
+    assert ev.deleted and OWNER not in ctx.app.pending
+    (fmt,) = await ctx.db.list_formats(OWNER)
+    assert fmt["name"] == "One Piece" and fmt["template"] == "Mine - {title}"  # starts from the user's current template
+    (chat, text, kw), = ctx.client.edited
+    assert kw["message"] == 500 and "created" in text and "🗂 One Piece" in text and f"fm:in:{fmt['id']}:template" in data_of(kw["buttons"])
+
+
+async def test_a_bad_or_taken_name_keeps_the_prompt_open(ctx):
+    await make_format(ctx, "One Piece")
+    await click(ctx, OWNER, "fm:new")
+    for text, expected in (("x" * 31, "too long"), ("one piece", "already have a format")):
+        ev = await say(ctx, OWNER, text)
+        assert expected in ev.texts[0] and "Try again" in ev.texts[0]
+        assert OWNER in ctx.app.pending and await ctx.db.count_formats(OWNER) == 1
+    cb = await click(ctx, OWNER, "m:formats")  # Cancel
+    assert OWNER not in ctx.app.pending and "FORMATS" in cb.edits[-1][0]
+
+
+async def test_the_twelve_format_limit(ctx):
+    for i in range(MAX_FORMATS):
+        await make_format(ctx, f"F{i}")
+    ev = await say(ctx, OWNER, "/formats")
+    assert "all 12 formats" in ev.texts[0] and "fm:new" not in data_of(ev.out[0][1])
+    cb = await click(ctx, OWNER, "fm:new")
+    assert "already have 12" in cb.alerts[0] and OWNER not in ctx.app.pending
+
+    # the limit is also enforced when it is reached while the name prompt is open
+    await ctx.db.delete_format(OWNER, (await ctx.db.list_formats(OWNER))[0]["id"])
+    await click(ctx, OWNER, "fm:new")
+    await make_format(ctx, "Sneaked in")
+    ev = await say(ctx, OWNER, "Late one")
+    assert "already have 12" in ev.texts[0] and OWNER not in ctx.app.pending
+
+
+async def test_the_format_screen_shows_every_field_and_has_a_button_for_each(ctx):
+    fmt = await make_format(ctx, meta={"title": "One Piece", "video": "HD"}, keep_audio=["japanese", "2"])
+    cb = await click(ctx, OWNER, f"fm:v:{fmt['id']}")
+    text, buttons = cb.edits[-1]
+    for label in ("Template", "Thumbnail", "Title", "Author", "Artist", "Audio", "Subtitle", "Video", "Keep Audio", "Keep Subtitle"):
+        assert label in text, label
+    assert "One Piece - E{episode}" in text and "Japanese, 2" in text and "your default thumbnail" in text
+    assert "<b>Title</b> ▸ <code>One Piece</code>" in text and "<b>Video</b> ▸ <code>HD</code>" in text  # values land on the right line
+    assert "<b>Author</b> ▸ —" in text
+    data = data_of(buttons)
+    i = fmt["id"]
+    for field in ("name", "template", "title", "author", "artist", "audio", "subtitle", "video", "keep_audio", "keep_subtitle"):
+        assert f"fm:in:{i}:{field}" in data, field
+    assert {f"fm:th:{i}", f"fm:del:{i}", "m:formats", "x:close"} <= set(data)
+    assert f"fm:thd:{i}" not in data  # nothing to delete yet
+
+
+async def test_editing_each_field_goes_through_the_same_checks_as_the_settings(ctx):
+    fmt = await make_format(ctx)
+    i = fmt["id"]
+    edits = {
+        "template": ("[S{season}E{episode}] {title}", lambda f: f["template"] == "[S{season}E{episode}] {title}"),
+        "title": ("One Piece", lambda f: f["meta"]["title"] == "One Piece"),
+        "author": ("@Me", lambda f: f["meta"]["author"] == "@Me"),
+        "artist": ("@Me", lambda f: f["meta"]["artist"] == "@Me"),
+        "audio": ("{lang} Audio", lambda f: f["meta"]["audio"] == "{lang} Audio"),
+        "subtitle": ("{lang}", lambda f: f["meta"]["subtitle"] == "{lang}"),
+        "video": ("HD", lambda f: f["meta"]["video"] == "HD"),
+        "keep_audio": ("Japanese English", lambda f: f["keep_audio"] == ["japanese", "english"]),
+        "keep_subtitle": ("2 1", lambda f: f["keep_subtitle"] == ["2", "1"]),
+    }
+    for n, (field, (value, check)) in enumerate(edits.items()):
+        cb = await click(ctx, OWNER, f"fm:in:{i}:{field}", msg_id=700 + n)
+        p = ctx.app.pending[OWNER]
+        assert p.kind == f"fmt:{field}" and p.fid == i and p.msg_id == 700 + n
+        assert cb.edits[-1][0] == panels.FORMAT_PROMPTS[field] and data_of(cb.edits[-1][1]) == [f"fm:cx:{i}"]
+        ev = await say(ctx, OWNER, value)
+        assert ev.deleted and OWNER not in ctx.app.pending, field
+        assert check(await ctx.db.get_format(OWNER, i)), field
+        chat, text, kw = ctx.client.edited[-1]
+        assert kw["message"] == 700 + n and "🗂 One Piece" in text, field  # the format screen is back in the same message
+    # none of this touched the user's own settings
+    assert (await ctx.db.get_settings(OWNER))["meta"]["title"] == "" and (await ctx.db.get_settings(OWNER))["keep_audio"] == []
+
+
+async def test_invalid_values_keep_the_prompt_open_and_cancel_returns_to_the_format(ctx):
+    fmt = await make_format(ctx)
+    i = fmt["id"]
+    await click(ctx, OWNER, f"fm:in:{i}:keep_audio")
+    ev = await say(ctx, OWNER, "bad!word")
+    assert "❌" in ev.texts[0] and "Try again" in ev.texts[0] and OWNER in ctx.app.pending
+    cb = await click(ctx, OWNER, f"fm:cx:{i}")
+    assert OWNER not in ctx.app.pending and "🗂 One Piece" in cb.edits[-1][0]
+
+
+async def test_clearing_a_field_with_off(ctx):
+    fmt = await make_format(ctx, meta={"title": "X"}, keep_audio=["english"])
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:title")
+    await say(ctx, OWNER, "off")
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:keep_audio")
+    await say(ctx, OWNER, "off")
+    got = await ctx.db.get_format(OWNER, fmt["id"])
+    assert got["meta"]["title"] == "" and got["keep_audio"] == []
+
+
+async def test_renaming_a_format(ctx):
+    fmt = await make_format(ctx, "One Piece")
+    await make_format(ctx, "Dragon Ball")
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:name")
+    ev = await say(ctx, OWNER, "dragon ball")
+    assert "already have a format" in ev.texts[0] and OWNER in ctx.app.pending
+    await say(ctx, OWNER, "Straw Hats")
+    assert (await ctx.db.get_format(OWNER, fmt["id"]))["name"] == "Straw Hats"
+    assert "🗂 Straw Hats" in ctx.client.edited[-1][1]
+
+
+async def test_a_format_thumbnail_is_saved_shown_and_deleted(ctx):
+    fmt = await make_format(ctx)
+    i = fmt["id"]
+    cb = await click(ctx, OWNER, f"fm:th:{i}", msg_id=800)
+    assert ctx.app.pending[OWNER].kind == "fmt:thumb"
+    assert cb.edits[-1][0] == panels.FORMAT_PROMPTS["thumb"]
+    ev = await say(ctx, OWNER, "not a photo")  # text while a photo is expected
+    assert "Send a photo" in ev.texts[0] and OWNER in ctx.app.pending
+
+    ev = FakeEvent(OWNER, message=FakeMessage("", mid=801, photo=True), photo_bytes=jpeg((900, 600)))
+    await dispatch(ctx.client, ev)
+    assert OWNER not in ctx.app.pending and ev.out == []  # no "thumbnail saved" for the global one
+    stored = await ctx.db.get_format_thumb(OWNER, i)
+    assert stored[:2] == b"\xff\xd8" and await ctx.db.get_thumb(OWNER) is None  # the format's, not the user's default
+    chat, text, kw = ctx.client.edited[-1]
+    assert kw["message"] == 800 and "Thumbnail saved" in text and "✅ saved" in text and f"fm:thd:{i}" in data_of(kw["buttons"])
+
+    cb = await click(ctx, OWNER, f"fm:thd:{i}")
+    assert cb.toasts == ["Thumbnail deleted."] and await ctx.db.get_format_thumb(OWNER, i) is None
+    assert "your default thumbnail" in cb.edits[-1][0]
+
+
+async def test_a_photo_without_a_pending_format_prompt_is_still_the_global_thumbnail(ctx):
+    await make_format(ctx)
+    ev = FakeEvent(OWNER, message=FakeMessage("", mid=900, photo=True), photo_bytes=jpeg())
+    await dispatch(ctx.client, ev)
+    assert "Thumbnail saved" in ev.texts[0] and (await ctx.db.get_thumb(OWNER)) is not None
+
+
+async def test_deleting_a_format_asks_first(ctx):
+    fmt = await make_format(ctx)
+    i = fmt["id"]
+    cb = await click(ctx, OWNER, f"fm:del:{i}")
+    assert "Delete the format" in cb.edits[-1][0] and set(data_of(cb.edits[-1][1])) == {f"fm:ok:{i}", f"fm:v:{i}"}
+    assert await ctx.db.get_format(OWNER, i) is not None
+    cb = await click(ctx, OWNER, f"fm:v:{i}")  # "Keep it"
+    assert "🗂 One Piece" in cb.edits[-1][0]
+    cb = await click(ctx, OWNER, f"fm:ok:{i}")
+    assert await ctx.db.get_format(OWNER, i) is None
+    assert "FORMATS" in cb.edits[-1][0] and cb.toasts == ["Deleted One Piece."]
+
+
+async def test_buttons_of_a_deleted_format_say_so_and_show_the_list(ctx):
+    fmt = await make_format(ctx)
+    await ctx.db.delete_format(OWNER, fmt["id"])
+    for data in (f"fm:v:{fmt['id']}", f"fm:in:{fmt['id']}:title", f"fm:th:{fmt['id']}", f"fm:del:{fmt['id']}", f"fm:ok:{fmt['id']}"):
+        cb = await click(ctx, OWNER, data)
+        assert cb.alerts == ["That format no longer exists."] and "FORMATS" in cb.edits[-1][0], data
+    assert OWNER not in ctx.app.pending
+
+
+async def test_typing_into_a_prompt_for_a_deleted_format_is_handled(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:title")
+    await ctx.db.delete_format(OWNER, fmt["id"])
+    ev = await say(ctx, OWNER, "Title")
+    assert "no longer exists" in ev.texts[0] and OWNER not in ctx.app.pending
+
+
+async def test_formats_belong_to_one_user(ctx):
+    mine = await make_format(ctx, "Mine")
+    cb = await click(ctx, ADMIN_CFG, f"fm:v:{mine['id']}")
+    assert cb.alerts == ["That format no longer exists."]
+    cb = await click(ctx, ADMIN_CFG, f"fm:ok:{mine['id']}")
+    assert await ctx.db.get_format(OWNER, mine["id"]) is not None
+    ev = await say(ctx, ADMIN_CFG, "/formats")
+    assert "no formats yet" in ev.texts[0]
+    ev = await say(ctx, ADMIN_CFG, "/rename")
+    assert "no saved formats" in ev.texts[0]
+
+
+async def test_any_other_tap_abandons_an_open_prompt(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:title")
+    await click(ctx, OWNER, "fm:new")
+    assert ctx.app.pending[OWNER].kind == "fmt:new"
+    await click(ctx, OWNER, f"fm:v:{fmt['id']}")
+    assert OWNER not in ctx.app.pending
+
+
+# ---------------------------------------------------------------------------
+# /rename: pick a format, send one file
+# ---------------------------------------------------------------------------
+
+
+async def test_rename_without_formats_points_to_creating_one(ctx):
+    ev = await say(ctx, OWNER, "/rename")
+    assert "no saved formats" in ev.texts[0] and "fm:new" in data_of(ev.out[0][1])
+    ev = await say(ctx, OWNER, "/rename New Name", reply=FakeMessage("x", mid=3))  # the old reply-with-a-name form is gone
+    assert "no saved formats" in ev.texts[0] and not ctx.app.queue.jobs
+
+
+async def test_rename_offers_the_saved_formats_by_name(ctx):
+    a, b = await make_format(ctx, "One Piece"), await make_format(ctx, "Dragon Ball")
+    ev = await say(ctx, OWNER, "/rename")
+    assert "Choose the format" in ev.texts[0]
+    data = data_of(ev.out[0][1])
+    assert f"rn:p:{a['id']}" in data and f"rn:p:{b['id']}" in data and "m:formats" in data
+    labels = [btn.text for row in ev.out[0][1] for btn in row]
+    assert "One Piece" in labels and "Dragon Ball" in labels
+    assert not ctx.app.queue.jobs and ctx.app._mode(OWNER) is None  # nothing is armed until a format is chosen
+
+
+async def test_choosing_a_format_then_sending_a_file_renames_it_with_that_format(ctx):
+    await ctx.db.update_settings(OWNER, template="DEFAULT {title}")
+    fmt = await make_format(ctx, meta={"title": "One Piece"})
+    cb = await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    assert cb.toasts == ["Format: One Piece"] and ctx.app._mode(OWNER, "rename") is not None
+    text, buttons = cb.edits[-1]
+    assert "One Piece" in text and "one file at a time" in text and "/rename again" in text
+    assert set(data_of(buttons)) == {"rn:menu", "rn:stop"}
+
+    ev = await send_doc(ctx, OWNER, ONE_PIECE, mid=50)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.new_name == "One Piece - E1147.mkv"  # the format's template, not the default one
+    assert job.fmt["id"] == fmt["id"] and job.fmt["meta"]["title"] == "One Piece" and job.order == 50
+    assert "Queued" in ev.texts[0] and "🗂 Format: <b>One Piece</b>" in ev.texts[0] and "One Piece - E1147.mkv" in ev.texts[0]
+    assert ctx.app._mode(OWNER) is None  # it was for one file
+
+
+async def test_other_settings_still_come_from_the_users_own_settings(ctx):
+    await ctx.db.update_settings(OWNER, mode="caption", remove_words=["@Junk"])
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    await send_doc(ctx, OWNER, "xyz.mkv", caption="1148 - One Piece 720p @Junk", mid=51)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.new_name == "One Piece - E1148.mkv"  # read from the caption (the user's mode)
+
+
+async def test_the_next_file_needs_rename_again(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    await send_doc(ctx, OWNER, ONE_PIECE, mid=50)
+    # a second file straight after is not auto-renamed behind the user's back: one hint, then silence
+    ev = await send_doc(ctx, OWNER, "1148 - One Piece [Dual] 720p.mkv", mid=51)
+    assert "one file at a time" in ev.texts[0] and "/rename again" in ev.texts[0]
+    ev = await send_doc(ctx, OWNER, "1149 - One Piece [Dual] 720p.mkv", mid=52)
+    assert ev.out == []
+    assert [j.file_name for j in ctx.app.queue.jobs.values()] == [ONE_PIECE]
+
+    # once the short grace period is over, files are renamed with the normal settings as usual
+    ctx.app._recent[OWNER][1] -= appmod.ONE_SHOT_GRACE + 1
+    ev = await send_doc(ctx, OWNER, "1150 - One Piece [Dual] 720p.mkv", mid=53)
+    assert "Queued" in ev.texts[0] and "Format" not in ev.texts[0]
+    assert len(ctx.app.queue.jobs) == 2
+
+    # and choosing a format again renames the next one with it
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    ev = await send_doc(ctx, OWNER, "1151 - One Piece [Dual] 720p.mkv", mid=54)
+    assert "🗂 Format: <b>One Piece</b>" in ev.texts[0] and len(ctx.app.queue.jobs) == 3
+
+
+async def test_a_forwarded_batch_gives_the_format_to_exactly_one_file(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    events = [FakeEvent(OWNER, message=document_message(f"114{n} - One Piece 720p.mkv", 1024, mid=60 + n)) for n in range(5, 9)]
+    await asyncio.gather(*(dispatch(ctx.client, ev) for ev in events))
+    jobs = list(ctx.app.queue.jobs.values())
+    assert len(jobs) == 1 and jobs[0].fmt["id"] == fmt["id"]
+    hints = [t for ev in events for t in ev.texts if "one file at a time" in t]
+    assert len(hints) == 1  # one hint for the whole batch, not one per file
+
+
+async def test_the_chosen_format_is_forgotten_after_the_wait(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    ctx.app.modes[OWNER].expires = time.time() - 1
+    ev = await send_doc(ctx, OWNER, ONE_PIECE, mid=50)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.fmt is None and "Format" not in ev.texts[0]  # a normal auto-rename
+    assert ctx.app._mode(OWNER) is None
+
+
+async def test_a_format_deleted_after_choosing_it_is_reported_and_nothing_is_queued(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    await ctx.db.delete_format(OWNER, fmt["id"])
+    ev = await send_doc(ctx, OWNER, ONE_PIECE, mid=50)
+    assert "format was deleted" in ev.texts[0] and not ctx.app.queue.jobs and ctx.app._mode(OWNER) is None
+
+
+async def test_a_template_variable_missing_from_the_file_is_flagged_for_the_format_too(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    ev = await send_doc(ctx, OWNER, "Plain Movie.mkv", mid=50)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.new_name == "One Piece - E.mkv" and "⚠️" in ev.texts[0] and "{episode}" in ev.texts[0]
+
+
+async def test_choosing_a_format_that_is_gone_or_not_yours(ctx):
+    fmt = await make_format(ctx)
+    cb = await click(ctx, ADMIN_CFG, f"rn:p:{fmt['id']}")  # somebody else's
+    assert cb.alerts == ["That format no longer exists."] and ctx.app._mode(ADMIN_CFG) is None
+    await ctx.db.delete_format(OWNER, fmt["id"])
+    cb = await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    assert cb.alerts == ["That format no longer exists."] and "no saved formats" in cb.edits[-1][0]
+
+
+async def test_one_users_chosen_format_does_not_affect_another(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    await send_doc(ctx, ADMIN_CFG, EPISODE, mid=70)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.user_id == ADMIN_CFG and job.fmt is None
+    assert ctx.app._mode(OWNER, "rename") is not None  # still waiting for the owner's file
+
+
+async def test_change_format_and_stop_buttons(ctx):
+    a, b = await make_format(ctx, "One Piece"), await make_format(ctx, "Dragon Ball")
+    await click(ctx, OWNER, f"rn:p:{a['id']}")
+    cb = await click(ctx, OWNER, "rn:menu")
+    assert "Choose the format" in cb.edits[-1][0] and ctx.app._mode(OWNER) is None
+    await click(ctx, OWNER, f"rn:p:{b['id']}")
+    assert ctx.app.modes[OWNER].data["fid"] == b["id"]
+    cb = await click(ctx, OWNER, "rn:stop")
+    assert "Stopped" in cb.edits[-1][0] and ctx.app._mode(OWNER) is None
+    ev = await send_doc(ctx, OWNER, ONE_PIECE, mid=50)
+    (job,) = ctx.app.queue.jobs.values()
+    assert job.fmt is None and "Format" not in ev.texts[0]
+    assert not ctx.app._recent  # stopping is not a finished one-file command: no hint for later files
+
+
+async def test_cancel_ends_the_chosen_format_before_it_touches_queued_files(ctx):
+    fmt = await make_format(ctx)
+    await send_doc(ctx, OWNER, EPISODE, mid=40)  # something is already queued
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Cancelled" in ev.texts[0] and "/rename again" in ev.texts[0] and "/cancel again" in ev.texts[0]
+    assert ctx.app._mode(OWNER) is None and len(ctx.app.queue.jobs) == 1
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Cancelling 1 job" in ev.texts[0] and not ctx.app.queue.jobs
+
+
+async def test_cancel_with_nothing_armed_still_cancels_jobs(ctx):
+    await send_doc(ctx, OWNER, EPISODE, mid=40)
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Cancelling 1 job" in ev.texts[0]
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "no active jobs" in ev.texts[0]
+
+
+async def test_start_and_the_rename_picker_close_an_open_text_prompt(ctx):
+    fmt = await make_format(ctx)
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:title")
+    await say(ctx, OWNER, "/rename")
+    assert OWNER not in ctx.app.pending
+    await click(ctx, OWNER, f"fm:in:{fmt['id']}:title")
+    await say(ctx, OWNER, "/formats")
+    assert OWNER not in ctx.app.pending
+
+
+def test_the_format_screens_fit_in_a_caption_even_with_the_longest_values():
+    from .test_panels import CAPTION_LIMIT, visible
+
+    longest = ["klingon-language-tag-x"] * 12
+    fmt = {
+        "id": 12, "name": "N" * 30, "has_thumb": True, "template": "T" * 200,
+        "meta": {k: "M" * 200 for k in ("title", "author", "artist", "audio", "subtitle", "video")},
+        "keep_audio": longest, "keep_subtitle": longest,
+    }
+    formats = [dict(fmt, id=i, name="F" * 30) for i in range(12)]
+    for name, (text, rows) in {
+        "view": panels.format_view(fmt), "menu": panels.formats_menu(formats, 12), "delete": panels.format_delete_confirm(fmt),
+        "ready": panels.rename_ready(fmt, 10), "picker": panels.rename_picker(formats),
+        **{f"prompt_{k}": panels.format_prompt(k, 12) for k in panels.FORMAT_PROMPTS},
+    }.items():
+        assert len(visible(text)) <= CAPTION_LIMIT, (name, len(visible(text)))
+        assert text.count("<b>") == text.count("</b>") and text.count("<code>") == text.count("</code>"), name
+        for row in rows:
+            assert 1 <= len(row) <= 3, name
+            for label, data in row:
+                assert label.strip() and len(label) <= 32 and 0 < len(data.encode()) <= 64, (name, label, data)

tests/test_media.py

@@ -9,12 +9,16 @@ from bot.media import (
     apply_plan,
     build_plan,
     canonical_lang,
+    extract_frame,
     format_tracks,
+    frame_seeks,
     make_video_thumbnail,
     parse_probe,
+    parse_size,
     parse_track_tokens,
     prepare_thumb,
     probe,
+    resize_image,
     resolve_tokens,
     validate_track_tokens,
 )
@@ -319,3 +323,118 @@ async def test_thumbnail_and_prepare_thumb(media_dir, tmp_path):
     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)
+
+
+# ---------------------------------------------------------------------------
+# /ethumb and /resize helpers
+# ---------------------------------------------------------------------------
+
+
+def test_frame_seeks_start_at_about_a_tenth_and_fall_back_to_earlier_positions():
+    assert frame_seeks(1400) == [60.0, 20.0, 5.0, 0.0]
+    assert frame_seeks(100) == [10.0, 5.0, 0.0]
+    assert frame_seeks(2) == [0.2, 0.0]
+    assert frame_seeks(0) == [1.0, 0.0]  # duration unknown (a cut-off file)
+    assert frame_seeks(-5) == [1.0, 0.0]
+
+
+@pytest.mark.parametrize("text,expected", [
+    ("320", (320, 320)), (" 320 ", (320, 320)), ("320x180", (320, 180)), ("320X180", (320, 180)), ("320×180", (320, 180)),
+    ("320 x 180", (320, 180)), ("320*180", (320, 180)), ("320 180", (320, 180)), ("320,180", (320, 180)),
+    ("16x16", (16, 16)), ("4096x4096", (4096, 4096)),
+    ("15x300", None), ("5000", None), ("99999x99999", None), ("320x", None), ("x180", None), ("320x180x90", None),
+    ("320 px", None), ("-5", None), ("abc", None), ("", None),
+])
+def test_parse_size(text, expected):
+    assert parse_size(text) == expected
+
+
+def _png(size, color=(10, 120, 200), mode="RGB"):
+    import io
+    from PIL import Image
+
+    buf = io.BytesIO()
+    Image.new(mode, size, color).save(buf, "PNG")
+    return buf.getvalue()
+
+
+def test_resize_image_fits_inside_the_box_and_keeps_the_shape():
+    import io
+    from PIL import Image
+
+    data, original, new = resize_image(_png((1920, 1080)), 320, 320)
+    assert original == (1920, 1080) and new == (320, 180)
+    img = Image.open(io.BytesIO(data))
+    assert img.format == "JPEG" and img.size == new
+    assert resize_image(_png((1920, 1080)), 100, 400)[2] == (100, 56)
+    assert resize_image(_png((1000, 2000)), 500, 500)[2] == (250, 500)
+    assert resize_image(_png((100, 50)), 400, 400)[2] == (400, 200)  # small images are scaled up to the size asked for
+
+
+def test_a_thumbnail_sized_result_stays_under_200_kb_even_for_noisy_images():
+    import io
+    from PIL import Image
+
+    noisy = io.BytesIO()
+    Image.effect_noise((2000, 2000), 90).convert("RGB").save(noisy, "PNG")
+    data, _original, new = resize_image(noisy.getvalue(), 320, 320)
+    assert max(new) == 320 and len(data) <= 200 * 1024
+    big, _o, bigsize = resize_image(noisy.getvalue(), 1280, 1280)  # larger results are not squeezed
+    assert max(bigsize) == 1280 and len(big) > 200 * 1024
+
+
+def test_transparent_images_get_a_white_background_not_a_black_one():
+    import io
+    from PIL import Image
+
+    data, _o, _n = resize_image(_png((200, 200), (0, 0, 0, 0), mode="RGBA"), 100, 100)
+    pixel = Image.open(io.BytesIO(data)).getpixel((50, 50))
+    assert min(pixel) > 240
+
+
+def test_exif_orientation_is_applied():
+    import io
+    from PIL import Image
+
+    img = Image.new("RGB", (200, 100), (200, 0, 0))
+    exif = img.getexif()
+    exif[274] = 6  # rotate 90 degrees clockwise when displayed
+    buf = io.BytesIO()
+    img.save(buf, "JPEG", exif=exif)
+    _data, original, new = resize_image(buf.getvalue(), 100, 100)
+    assert original == (100, 200) and new == (50, 100)
+
+
+def test_resize_image_rejects_what_is_not_an_image():
+    with pytest.raises(Exception):
+        resize_image(b"definitely not an image", 100, 100)
+
+
+@needs_ffmpeg
+async def test_extract_frame_writes_a_jpeg_and_tries_the_next_position_after_a_miss(media_dir, tmp_path):
+    out = tmp_path / "f.jpg"
+    assert await extract_frame(media_dir / "sample.mkv", out, [1.0])
+    assert out.read_bytes()[:2] == b"\xff\xd8"
+    from PIL import Image
+
+    assert Image.open(out).size == (320, 240)  # the sample is smaller than the 1280 px limit
+    out.unlink()
+    assert await extract_frame(media_dir / "sample.mkv", out, [500.0, 0.0])  # nothing at 500 s: the next position works
+    assert out.stat().st_size > 0
+
+
+@needs_ffmpeg
+async def test_extract_frame_scales_down_wide_pictures(media_dir, tmp_path):
+    from PIL import Image
+
+    out = tmp_path / "small.jpg"
+    assert await extract_frame(media_dir / "sample.mkv", out, [0.0], width=160)
+    assert Image.open(out).size == (160, 120)
+
+
+@needs_ffmpeg
+async def test_extract_frame_gives_up_on_junk_without_raising(tmp_path):
+    junk = tmp_path / "junk.mkv"
+    junk.write_bytes(b"\x00" * 4096)
+    assert not await extract_frame(junk, tmp_path / "j.jpg", [1.0, 0.0])
+    assert not await extract_frame(tmp_path / "missing.mkv", tmp_path / "m.jpg", [0.0])

tests/test_mediainfo.py

@@ -0,0 +1,383 @@
+"""/mediainfo: reading a file and laying the report out."""
+import pytest
+
+from bot import mediainfo as mi
+from bot import telegraph
+
+from .conftest import needs_ffmpeg
+
+TEXT = """General
+Complete name                            : /tmp/work/minfo1_2/probe.mkv
+Format                                   : Matroska
+Conformance errors                       : 2
+ 0x8538067                               : Yes
+  General compliance                     : Element size 1 is more than maximal permitted size 2 (offset 0x34)
+ Matroska                                : Yes
+CRC_Error_Pos                            : 943
+Writing library                          : Lavf
+
+Video
+ID                                       : 1
+Format                                   : AVC
+Title                                    : \x07bell\x1b[0m here
+
+Menu
+00:00:00.000                             : Intro
+Plain line without a separator
+Empty value                              :
+"""
+
+FFPROBE = {
+    "format": {
+        "format_long_name": "Matroska / WebM", "duration": "1441.419",
+        "tags": {"title": "Show", "ENCODER": "libebml", "creation_time": "2026-01-01T00:00:00Z", "WEIRD_KEY": "x"},
+    },
+    "streams": [
+        {"index": 0, "codec_type": "video", "codec_name": "hevc", "codec_long_name": "H.265 / HEVC", "profile": "Main 10",
+         "level": 123, "width": 1920, "height": 1080, "avg_frame_rate": "24000/1001", "pix_fmt": "yuv420p10le",
+         "bits_per_raw_sample": "10", "display_aspect_ratio": "16:9", "color_space": "bt709",
+         "disposition": {"default": 1}, "tags": {"BPS": "3200000", "DURATION": "00:24:01.419000000"}},
+        {"index": 1, "codec_type": "audio", "codec_name": "aac", "profile": "LC", "channels": 2, "channel_layout": "stereo",
+         "sample_rate": "48000", "disposition": {"default": 1, "forced": 0}, "tags": {"language": "jpn", "title": "Japanese"}},
+        {"index": 2, "codec_type": "audio", "codec_name": "ac3", "channels": 1, "sample_rate": "44100", "tags": {"language": "hin"}},
+        {"index": 3, "codec_type": "subtitle", "codec_name": "ass", "disposition": {"forced": 1}, "tags": {"language": "eng"}},
+        {"index": 4, "codec_type": "attachment", "codec_name": "ttf", "tags": {"filename": "font.ttf"}},
+    ],
+    "chapters": [{"start_time": "0.000000", "tags": {"title": "Intro"}}, {"start_time": "90.5", "tags": {"title": "Main"}}],
+}
+
+
+def lines_of(report, title):
+    return dict(report.section(title).lines)
+
+
+def report_of(*sections, **kw):
+    return mi.Report(sections=list(sections), engine=kw.pop("engine", "MediaInfo"), **kw)
+
+
+# ---------------------------------------------------------------------------
+# MediaInfo's number formats
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("num, text", [
+    (0, "0 Bytes"), (999, "999 Bytes"), (1024, "1.00 KiB"), (71 * 1024, "71.0 KiB"), (93550, "91.4 KiB"),
+    (845 * 1024 ** 2, "845 MiB"), (int(1.46 * 1024 ** 3), "1.46 GiB"), (int(1023.9 * 1024), "1.00 MiB"), (5 * 1024 ** 4, "5.00 TiB"),
+])
+def test_sizes_are_written_like_mediainfo_does(num, text):
+    assert mi.mi_size(num) == text
+
+
+@pytest.mark.parametrize("bps, text", [
+    (62, "62 b/s"), (370_000, "370 kb/s"), (1_936_000, "1 936 kb/s"), (9_999_000, "9 999 kb/s"),
+    (12_340_000, "12.3 Mb/s"), (150_000_000, "150 Mb/s"),
+])
+def test_bit_rates_are_written_like_mediainfo_does(bps, text):
+    assert mi.mi_rate(bps) == text
+
+
+@pytest.mark.parametrize("ms, text", [
+    (2023, "2 s 23 ms"), (1_441_000, "24 min 1 s"), (5_040_000, "1 h 24 min"), (0, "0 s 0 ms"), (59_999.6, "1 min 0 s"),
+])
+def test_durations_are_written_like_mediainfo_does(ms, text):
+    assert mi.mi_duration(ms) == text
+
+
+# ---------------------------------------------------------------------------
+# reading MediaInfo's text
+# ---------------------------------------------------------------------------
+
+
+def test_the_text_is_split_into_sections_of_labels_and_values():
+    sections = mi.parse_text(TEXT)
+    assert [s.title for s in sections] == ["General", "Video", "Menu"]
+    general = sections[0].lines
+    assert general[0] == ("Complete name", "/tmp/work/minfo1_2/probe.mkv")
+    assert (" 0x8538067", "Yes") in general and ("  General compliance", general[4][1]) == general[4]  # nesting is kept
+    video = dict(sections[1].lines)
+    assert video["Title"] == "bell[0m here"  # control characters are gone
+    menu = sections[2].lines
+    assert menu[0] == ("00:00:00.000", "Intro") and ("", "Plain line without a separator") in menu and ("Empty value", "") in menu
+
+
+def test_windows_line_endings_and_blank_runs_are_fine():
+    sections = mi.parse_text("General\r\nFormat : MPEG-4\r\n\r\n\r\nAudio\r\nFormat : AAC\r\n")
+    assert [(s.title, s.lines) for s in sections] == [("General", [("Format", "MPEG-4")]), ("Audio", [("Format", "AAC")])]
+
+
+# ---------------------------------------------------------------------------
+# the General section of a file we only have the start of
+# ---------------------------------------------------------------------------
+
+
+def test_a_cut_short_file_gets_its_real_name_and_size_and_no_false_alarms():
+    report = report_of(*mi.parse_text(TEXT), truncated=True)
+    mi.fix_general(report, "Show 01.mkv", 700 * 1024 ** 2, 1_440_000.0)
+    general = report.section("General")
+    assert [label for label, _ in general.lines] == ["Complete name", "Format", "Writing library", "File size", "Overall bit rate"]
+    values = dict(general.lines)
+    assert values["Complete name"] == "Show 01.mkv" and values["File size"] == "700 MiB"
+    assert values["Overall bit rate"] == "4 078 kb/s"  # 700 MiB over 24 minutes
+
+
+def test_a_cut_short_file_with_no_duration_loses_a_bit_rate_that_would_be_wrong():
+    report = report_of(*mi.parse_text("General\nFormat : X\nOverall bit rate : 11.9 kb/s\nOverall bit rate mode : Constant\n"), truncated=True)
+    mi.fix_general(report, "a.bin", 5000, None)
+    assert [label for label, _ in report.section("General").lines] == ["Complete name", "Format", "Overall bit rate mode", "File size"]
+
+
+def test_a_whole_file_keeps_everything_mediainfo_says_about_it():
+    report = report_of(*mi.parse_text(TEXT))
+    mi.fix_general(report, "x.mkv", 1000, 1000.0)
+    labels = [label for label, _ in report.section("General").lines]
+    assert "Conformance errors" in labels and "CRC_Error_Pos" in labels and " 0x8538067" in labels  # real problems stay visible
+    assert dict(report.section("General").lines)["File size"] == "1000 Bytes" and "Overall bit rate" not in labels
+
+
+def test_a_report_with_no_general_section_gets_one():
+    report = report_of(truncated=False, engine="")
+    mi.fix_general(report, "mystery.bin", 2048, None)
+    assert report.sections[0].title == "General" and report.sections[0].lines == [("Complete name", "mystery.bin"), ("File size", "2.00 KiB")]
+
+
+# ---------------------------------------------------------------------------
+# the report
+# ---------------------------------------------------------------------------
+
+
+def test_the_summary_line_counts_the_streams():
+    general = mi.Section("General", [("Format", "Matroska"), ("Duration", "24 min 1 s")])
+    streams = [mi.Section("Video"), mi.Section("Audio #1"), mi.Section("Audio #2"), mi.Section("Text #1"), mi.Section("Menu")]
+    assert report_of(general, *streams).summary() == "Matroska · 24 min 1 s · 1 video · 2 audio · 1 subtitle"
+    assert report_of(general).summary() == "Matroska · 24 min 1 s"
+    assert report_of().summary() == ""
+
+
+def test_only_real_streams_count_as_streams():
+    assert not report_of(mi.Section("General"), mi.Section("Menu"), mi.Section("Telegram")).has_streams
+    assert report_of(mi.Section("General"), mi.Section("Image")).has_streams
+    assert report_of(mi.Section("General"), mi.Section("Text #12")).has_streams
+
+
+def test_the_telegram_section_lists_what_telegram_knows_and_skips_the_rest():
+    full = mi.telegram_section("Show 01.mkv", 93550, mime="video/x-matroska", sent_as="Video", sent_on="2026-10-21 09:00:00 UTC",
+                               dc="4", caption="[HDR] Dual")
+    assert full.title == "Telegram" and full.lines == [
+        ("File name", "Show 01.mkv"), ("File size", "91.4 KiB (93 550 bytes)"), ("MIME type", "video/x-matroska"),
+        ("Sent as", "Video"), ("Sent on", "2026-10-21 09:00:00 UTC"), ("Data center", "4"), ("Caption", "[HDR] Dual"),
+    ]
+    assert mi.telegram_section("x", 0).lines == [("File name", "x")]
+
+
+# ---------------------------------------------------------------------------
+# laying a section out
+# ---------------------------------------------------------------------------
+
+
+def test_values_line_up_after_the_labels():
+    section = mi.Section("Video", [("Format", "AVC"), ("Duration", "2 s"), ("ID", "1")])
+    assert mi.render_section(section) == "Format   : AVC\nDuration : 2 s\nID       : 1"
+
+
+def test_long_values_wrap_under_the_start_of_the_value():
+    section = mi.Section("Video", [("Encoding settings", " / ".join(f"option{i}={i}" for i in range(40))), ("ID", "1")])
+    lines = mi.render_section(section, width=64).splitlines()
+    assert lines[0].startswith("Encoding settings : option0=0 / ") and len(lines) > 3
+    indent = " " * len("Encoding settings : ")
+    assert all(line.startswith(indent) for line in lines[1:-1]) and lines[-1].startswith("ID")
+    assert all(len(line) <= 64 + 8 for line in lines)  # a wrapped value gets at least MIN_VALUE columns
+
+
+def test_a_very_long_label_does_not_push_every_value_to_the_right():
+    section = mi.Section("Video", [("ID", "1"), ("Format settings, Reference frames", "1 frame"), ("Format", "AVC")])
+    lines = mi.render_section(section).splitlines()
+    assert lines == ["ID     : 1", "Format settings, Reference frames : 1 frame", "Format : AVC"]
+
+
+def test_unbroken_text_is_still_wrapped_and_lines_end_cleanly():
+    section = mi.Section("Menu", [("", "x" * 150), ("Blank", ""), ("Name", "y" * 200)])
+    lines = mi.render_section(section, width=64).splitlines()
+    assert max(len(line) for line in lines) <= 64 + 8 and all(line == line.rstrip() for line in lines)
+    assert "".join(line.strip() for line in lines).count("y") == 200
+
+
+def test_values_can_be_shortened_to_fit():
+    section = mi.Section("General", [("Comment", "z" * 500)])
+    line = mi.render_section(section, max_value=50)
+    assert line.endswith("…") and len(line.split(" : ")[1]) == 50
+
+
+# ---------------------------------------------------------------------------
+# the Telegraph page
+# ---------------------------------------------------------------------------
+
+
+def test_every_section_becomes_a_heading_and_a_block_and_the_notes_come_last():
+    report = report_of(mi.Section("General", [("Format", "Matroska")]), mi.Section("Telegram", [("File name", "a.mkv")]), truncated=True)
+    nodes = mi.to_nodes(report)
+    assert [n["tag"] for n in nodes] == ["h4", "pre", "h4", "pre", "p", "p"]
+    assert nodes[0]["children"] == ["General"] and nodes[1]["children"] == ["Format : Matroska"]
+    notes = [n["children"][0]["children"][0] for n in nodes if n["tag"] == "p"]
+    assert "Only the start of the file was read" in notes[0] and notes[1] == "Made by the bot with MediaInfo."
+
+
+def test_extra_notes_are_kept_and_an_unknown_engine_is_not_named():
+    report = report_of(mi.Section("General", [("Format", "x")]), engine="", notes=["No tracks could be read."])
+    notes = [n["children"][0]["children"][0] for n in mi.to_nodes(report) if n["tag"] == "p"]
+    assert notes == ["No tracks could be read.", "Made by the bot."]
+
+
+def test_a_page_that_is_too_big_has_its_long_values_shortened_first():
+    big = mi.Section("Video", [(f"Setting {i}", "v" * 600) for i in range(60)])
+    report = report_of(mi.Section("General", [("Format", "x")]), big, mi.Section("Telegram", [("File name", "a")]))
+    assert telegraph.content_size(mi.to_nodes(report, limit=10 ** 9)) > 30_000
+    nodes = mi.to_nodes(report, limit=30_000)
+    assert telegraph.content_size(nodes) <= 30_000
+    titles = [n["children"][0] for n in nodes if n["tag"] == "h4"]
+    assert titles == ["General", "Video", "Telegram"]  # nothing dropped, only shortened
+    assert "…" in nodes[3]["children"][0]
+
+
+def test_a_file_with_hundreds_of_tracks_drops_the_last_sections_but_keeps_the_ends():
+    sections = [mi.Section("General", [("Format", "Matroska")])]
+    sections += [mi.Section(f"Text #{i}", [("Format", "UTF-8"), ("Title", "t" * 80), ("Language", "English")]) for i in range(1, 301)]
+    sections.append(mi.Section("Telegram", [("File name", "big.mkv")]))
+    nodes = mi.to_nodes(report_of(*sections), limit=12_000)
+    assert telegraph.content_size(nodes) <= 12_000
+    titles = [n["children"][0] for n in nodes if n["tag"] == "h4"]
+    assert titles[0] == "General" and titles[-1] == "Telegram" and 3 < len(titles) < 302
+    notes = [n["children"][0]["children"][0] for n in nodes if n["tag"] == "p"]
+    assert any("page size limit" in note for note in notes)
+
+
+def test_the_default_limit_is_what_telegraph_accepts():
+    report = report_of(mi.Section("General", [("Format", "x")]))
+    assert telegraph.content_size(mi.to_nodes(report)) <= telegraph.CONTENT_LIMIT < 64 * 1024
+
+
+def test_the_plain_text_version_has_everything_the_page_has():
+    report = report_of(mi.Section("General", [("Format", "Matroska"), ("Duration", "2 s")]), mi.Section("Telegram", [("File name", "a.mkv")]), truncated=True)
+    text = mi.render_text(report)
+    assert text.startswith("General\nFormat   : Matroska\nDuration : 2 s\n\nTelegram\nFile name : a.mkv\n")
+    assert "Only the start of the file was read" in text and text.rstrip().endswith("Made by the bot with MediaInfo.") and text.endswith("\n")
+
+
+# ---------------------------------------------------------------------------
+# the ffprobe fallback
+# ---------------------------------------------------------------------------
+
+
+def test_ffprobe_output_becomes_mediainfo_style_sections():
+    sections = mi.ffprobe_sections(FFPROBE, "Show 01.mkv", 700 * 1024 ** 2)
+    assert [s.title for s in sections] == ["General", "Video", "Audio #1", "Audio #2", "Text", "Menu"]
+    report = report_of(*sections)
+    general = lines_of(report, "General")
+    assert general["Complete name"] == "Show 01.mkv" and general["Format"] == "Matroska / WebM" and general["File size"] == "700 MiB"
+    assert general["Duration"] == "24 min 1 s" and general["Overall bit rate"] == "4 074 kb/s"
+    assert general["Title"] == "Show" and general["Writing application"] == "libebml" and general["Encoded date"] == "2026-01-01T00:00:00Z"
+    assert general["Weird Key"] == "x" and general["Attachments"] == "font.ttf"
+    video = lines_of(report, "Video")
+    assert video["Format"] == "H.265 / HEVC" and video["Format profile"] == "Main 10@L4.1" and video["Frame rate"] == "23.976 FPS"
+    assert video["Width"] == "1920 pixels" and video["Height"] == "1080 pixels" and video["Bit depth"] == "10 bits"
+    assert video["Bit rate"] == "3 200 kb/s" and video["Duration"] == "24 min 1 s" and video["Default"] == "Yes" and video["Forced"] == "No"
+    first, second = lines_of(report, "Audio #1"), lines_of(report, "Audio #2")
+    assert first["Language"] == "Japanese" and first["Title"] == "Japanese" and first["Channel(s)"] == "2 channels"
+    assert first["Sampling rate"] == "48 kHz" and first["Format profile"] == "LC" and first["Default"] == "Yes"
+    assert second["Language"] == "Hindi" and second["Channel(s)"] == "1 channel" and second["Sampling rate"] == "44.1 kHz"
+    text = lines_of(report, "Text")
+    assert text["Language"] == "English" and text["Forced"] == "Yes" and text["Default"] == "No"
+    assert report.section("Menu").lines == [("00:00:00.000", "Intro"), ("00:01:30.500", "Main")]
+
+
+@pytest.mark.parametrize("codec, level, shown", [
+    ("h264", 41, "L4.1"), ("h264", 40, "L4"), ("h264", 12, "L1.2"), ("hevc", 120, "L4"), ("hevc", 153, "L5.1"),
+    ("h264", -99, ""), ("vp9", 41, ""), ("h264", None, ""),
+])
+def test_codec_levels_are_shown_the_way_each_codec_counts_them(codec, level, shown):
+    assert mi._level({"codec_name": codec, "level": level}) == shown
+
+
+def test_ffprobe_with_nothing_to_show_gives_just_a_general_section():
+    sections = mi.ffprobe_sections({"format": {"format_name": "mp3"}}, "a.mp3", 0)
+    assert [s.title for s in sections] == ["General"] and sections[0].lines == [("Complete name", "a.mp3"), ("Format", "mp3")]
+
+
+# ---------------------------------------------------------------------------
+# real files
+# ---------------------------------------------------------------------------
+
+
+@needs_ffmpeg
+async def test_a_real_mkv_is_read_by_mediainfo(media_dir):
+    pytest.importorskip("pymediainfo")
+    path = media_dir / "sample.mkv"
+    report = await mi.read_file(path, "Show 01.mkv", path.stat().st_size, extra=mi.telegram_section("Show 01.mkv", path.stat().st_size))
+    assert report.engine == "MediaInfo" and report.has_streams and not report.truncated
+    assert [s.title for s in report.sections] == ["General", "Video", "Audio #1", "Audio #2", "Audio #3", "Text #1", "Text #2", "Menu", "Telegram"]
+    general = lines_of(report, "General")
+    assert general["Complete name"] == "Show 01.mkv" and general["Format"] == "Matroska"  # not the path it was read from
+    assert lines_of(report, "Audio #1")["Language"] == "Japanese" and lines_of(report, "Text #2")["Language"] == "English"
+    assert "AVC" in lines_of(report, "Video")["Format"] and lines_of(report, "Video")["Width"] == "320 pixels"
+    assert report.summary().startswith("Matroska · 2 s") and report.summary().endswith("1 video · 3 audio · 2 subtitle")
+
+
+@needs_ffmpeg
+async def test_without_mediainfo_ffprobe_gives_the_same_layout(media_dir, monkeypatch):
+    monkeypatch.setattr(mi, "_mediainfo", lambda path: None)
+    path = media_dir / "sample.mkv"
+    report = await mi.read_file(path, "Show 01.mkv", path.stat().st_size)
+    assert report.engine == "ffprobe" and report.has_streams
+    assert [s.title for s in report.sections] == ["General", "Video", "Audio #1", "Audio #2", "Audio #3", "Text #1", "Text #2", "Menu"]
+    assert lines_of(report, "General")["Complete name"] == "Show 01.mkv" and lines_of(report, "Audio #3")["Language"] == "Hindi"
+    assert report.section("Menu").lines == [("00:00:00.000", "Intro"), ("00:00:01.000", "Main")]
+
+
+@needs_ffmpeg
+async def test_a_failing_mediainfo_falls_back_to_ffprobe(media_dir, monkeypatch):
+    def boom(path):
+        raise RuntimeError("libmediainfo crashed")
+
+    monkeypatch.setattr(mi, "_mediainfo", boom)
+    report = await mi.read_file(media_dir / "sample.mp4", "Movie.mp4", (media_dir / "sample.mp4").stat().st_size)
+    assert report.engine == "ffprobe" and report.has_streams and lines_of(report, "Audio #2")["Language"] == "English"
+
+
+@needs_ffmpeg
+async def test_an_audio_file_shows_its_tags(media_dir):
+    path = media_dir / "sample.mp3"
+    report = await mi.read_file(path, "Song.mp3", path.stat().st_size)
+    assert report.has_streams and report.section("Audio") is not None
+    assert "Old" in lines_of(report, "General").values()  # the title tag, however the engine labels it
+
+
+@needs_ffmpeg
+async def test_only_the_start_of_an_mkv_still_gets_the_real_size_and_bit_rate(media_dir, tmp_path):
+    pytest.importorskip("pymediainfo")
+    whole = media_dir / "sample.mkv"
+    cut = tmp_path / "probe.mkv"
+    cut.write_bytes(whole.read_bytes()[:3000])
+    real = whole.stat().st_size
+    expected = await mi.read_file(whole, "Show 01.mkv", real)
+    report = await mi.read_file(cut, "Show 01.mkv", real)
+    assert report.truncated and report.has_streams
+    general, reference = lines_of(report, "General"), lines_of(expected, "General")
+    assert general["File size"] == reference["File size"] and general["Overall bit rate"] == reference["Overall bit rate"]
+    assert not any("Conformance" in label or label.strip() == "CRC_Error_Pos" for label, _ in report.section("General").lines)
+
+
+@needs_ffmpeg
+async def test_an_mp4_cut_before_its_index_has_no_streams_but_still_a_report(media_dir, tmp_path):
+    cut = tmp_path / "probe.mp4"
+    cut.write_bytes((media_dir / "sample.mp4").read_bytes()[:3000])
+    report = await mi.read_file(cut, "Movie.mp4", 40 * 1024 * 1024)
+    assert report.truncated and not report.has_streams
+    assert lines_of(report, "General")["Complete name"] == "Movie.mp4" and lines_of(report, "General")["File size"] == "40.0 MiB"
+
+
+async def test_a_file_that_is_not_media_still_gets_a_general_section(tmp_path):
+    path = tmp_path / "notes.txt"
+    path.write_text("hello\n" * 100)
+    report = await mi.read_file(path, "notes.txt", path.stat().st_size)
+    assert not report.has_streams and not report.truncated
+    general = lines_of(report, "General")
+    assert general["Complete name"] == "notes.txt" and general["File size"] == "600 Bytes"

tests/test_mediainfo_app.py

@@ -0,0 +1,276 @@
+"""/mediainfo in the chat: reply to a file, get a Telegraph link."""
+import io
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+
+import pytest
+
+from bot import app as appmod
+from bot.telegraph import Telegraph, TelegraphError
+
+from .appkit import OWNER, STRANGER, say, send_doc
+from .conftest import needs_ffmpeg
+from .faketelegraph import serve_fake_telegraph
+from .tgfakes import FakeMessage, document_message
+
+URL = "https://telegra.ph/Show-05-10-21"
+HINT = "Reply to a file or video with /mediainfo"
+
+
+class StubTelegraph:
+    """What the bot talks to instead of Telegraph: remembers the pages it was asked for."""
+
+    def __init__(self, url=URL, error=None):
+        self.url, self.error, self.calls = url, error, []
+
+    async def create_page(self, title, nodes):
+        self.calls.append((title, nodes))
+        if self.error is not None:
+            raise self.error
+        return self.url
+
+
+def blocks(nodes):
+    """{heading: text of its block} for a page's nodes."""
+    return {n["children"][0]: nodes[i + 1]["children"][0] for i, n in enumerate(nodes) if n["tag"] == "h4"}
+
+
+def notes(nodes):
+    return [n["children"][0]["children"][0] for n in nodes if n["tag"] == "p"]
+
+
+def serve(monkeypatch, media_dir, name="sample.mkv"):
+    """Make transfer.download copy a real sample file; returns the list of calls."""
+    calls = []
+
+    async def fake_download(client, message, dest, **kw):
+        calls.append(kw)
+        shutil.copy(media_dir / name, dest)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    return calls
+
+
+def serve_junk(monkeypatch, content=b"\x00" * 4096):
+    calls = []
+
+    async def fake_download(client, message, dest, **kw):
+        calls.append(kw)
+        Path(dest).write_bytes(content)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    return calls
+
+
+def leftovers(ctx):
+    root = Path(ctx.cfg.temp_dir)
+    return list(root.glob("minfo*")) if root.exists() else []
+
+
+def use_stub(ctx, **kw):
+    ctx.app.telegraph = StubTelegraph(**kw)
+    return ctx.app.telegraph
+
+
+def real_size(media_dir, name="sample.mkv"):
+    return (media_dir / name).stat().st_size
+
+
+# ---------------------------------------------------------------------------
+# the flow
+# ---------------------------------------------------------------------------
+
+
+@needs_ffmpeg
+async def test_reply_to_a_video_and_the_telegraph_link_comes_back(ctx, media_dir, monkeypatch):
+    calls = serve(monkeypatch, media_dir)
+    tg = use_stub(ctx)
+    video = document_message("Show - 05.mkv", real_size(media_dir), mid=70, caption="Dual Audio")
+    video.date = datetime(2026, 10, 19, 21, 30, 12, tzinfo=timezone.utc)
+    video.document.dc_id = 4
+    ev = await say(ctx, OWNER, "/mediainfo", reply=video)
+    assert ev.texts == ["🔎 Reading the file…"]
+
+    entity, text, kw = ctx.client.edited[-1]
+    assert entity.id == 1001  # the "Reading…" message became the answer
+    assert "🔎 <b>MediaInfo</b> · Show - 05.mkv" in text and URL in text and "Matroska" in text and "1 video · 3 audio · 2 subtitle" in text
+    assert kw["parse_mode"] == "html" and kw["link_preview"] is False
+    (button,), = kw["buttons"]
+    assert button.type.url == URL and button.text.startswith("📄")
+
+    (title, nodes), = tg.calls
+    assert title == "MediaInfo – Show - 05.mkv"
+    page = blocks(nodes)
+    assert list(page) == ["General", "Video", "Audio #1", "Audio #2", "Audio #3", "Text #1", "Text #2", "Menu", "Telegram"]
+    assert "Show - 05.mkv" in page["General"] and "probe.mkv" not in page["General"]  # the file's own name, not the temp copy
+    telegram = page["Telegram"]
+    for line in ("File name   : Show - 05.mkv", "MIME type   : video/x-matroska", "Sent as     : Video",
+                 "Sent on     : 2026-10-19 21:30:12 UTC", "Data center : 4", "Caption     : Dual Audio"):
+        assert line in telegram, line
+    assert len(calls) == 1 and calls[0]["max_bytes"] == appmod.TRACKS_PROBE_BYTES  # the start of the file was enough
+    assert leftovers(ctx) == []
+
+
+async def test_without_a_file_there_is_a_hint_and_nothing_is_downloaded(ctx, monkeypatch):
+    async def no_download(*a, **kw):
+        raise AssertionError("there is nothing to read")
+
+    monkeypatch.setattr(appmod.transfer, "download", no_download)
+    tg = use_stub(ctx)
+    for reply in (None, FakeMessage("just some text")):
+        ev = await say(ctx, OWNER, "/mediainfo", reply=reply)
+        assert HINT in ev.texts[0] and "Telegraph" in ev.texts[0]
+    assert tg.calls == [] and ctx.client.edited == []
+
+
+@needs_ffmpeg
+async def test_a_file_sent_with_the_command_as_its_caption_is_read_not_renamed(ctx, media_dir, monkeypatch):
+    serve(monkeypatch, media_dir)
+    tg = use_stub(ctx)
+    for mid, caption in ((71, "/mediainfo"), (72, "/mediainfo@my_rename_bot")):
+        ev = await send_doc(ctx, OWNER, "Show.mkv", size=real_size(media_dir), caption=caption, mid=mid)
+        assert ev.texts == ["🔎 Reading the file…"]  # no "Queued" message from the auto-renamer
+    assert ctx.app.queue.waiting == 0 and len(tg.calls) == 2
+    assert "Caption" not in blocks(tg.calls[0][1])["Telegram"]  # the caption was only the command
+
+
+async def test_other_captions_still_rename_the_file(ctx):
+    ev = await send_doc(ctx, OWNER, "Show.mkv", size=5 * 1024 * 1024, caption="/mediainfoX", mid=73)
+    assert ev.texts[0].startswith("📥 <b>Queued</b>") and ctx.app.queue.waiting == 1
+
+
+@needs_ffmpeg
+async def test_a_video_whose_index_is_at_the_end_is_read_from_the_whole_file(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((media_dir / "sample.mp4").read_bytes()[:3000])  # an mp4 cut before its index
+        else:
+            shutil.copy(media_dir / "sample.mp4", dest)
+
+    monkeypatch.setattr(appmod.transfer, "download", fake_download)
+    tg = use_stub(ctx)
+    await say(ctx, OWNER, "/mediainfo", reply=document_message("Movie.mp4", 40 * 1024 * 1024, mid=74, mime="video/mp4"))
+    assert len(calls) == 2 and "max_bytes" in calls[0] and "max_bytes" not in calls[1]
+    assert any("needs the whole file" in text for _e, text, _k in ctx.client.edited)
+    (_title, nodes), = tg.calls
+    assert list(blocks(nodes))[:2] == ["General", "Video"] and "No tracks" not in " ".join(notes(nodes))
+    assert URL in ctx.client.edited[-1][1] and leftovers(ctx) == []
+
+
+@pytest.mark.parametrize("size, why", [(2 * 1024 * 1024, "may be damaged"), (900 * 1024 * 1024, "too big for me to download completely")])
+async def test_a_video_with_no_readable_tracks_still_gets_a_page_that_says_so(ctx, monkeypatch, size, why):
+    calls = serve_junk(monkeypatch)
+    tg = use_stub(ctx)
+    await say(ctx, OWNER, "/mediainfo", reply=document_message("Broken.mkv", size, mid=75))
+    assert len(calls) == 1  # too small to need more, or too big to fetch whole
+    (_title, nodes), = tg.calls
+    assert any(why in note for note in notes(nodes))
+    assert list(blocks(nodes)) == ["General", "Telegram"] and URL in ctx.client.edited[-1][1]
+    assert leftovers(ctx) == []
+
+
+async def test_a_file_that_is_not_media_is_read_from_its_start_only(ctx, monkeypatch):
+    calls = serve_junk(monkeypatch, b"PK\x03\x04" + b"\x00" * 4000)
+    tg = use_stub(ctx)
+    await say(ctx, OWNER, "/mediainfo", reply=document_message("archive.zip", 50 * 1024 * 1024, mid=76, video=False, mime="application/zip"))
+    assert len(calls) == 1 and "max_bytes" in calls[0]
+    (_title, nodes), = tg.calls
+    page = blocks(nodes)
+    assert list(page) == ["General", "Telegram"] and "archive.zip" in page["General"] and "50.0 MiB" in page["General"]
+    assert "Sent as   : Document" in page["Telegram"] and "No tracks" not in " ".join(notes(nodes))
+    assert any("Only the start of the file was read" in note for note in notes(nodes))
+
+
+async def test_a_download_that_fails_is_reported_and_cleaned_up(ctx, monkeypatch):
+    async def fail(client, message, dest, **kw):
+        Path(dest).write_bytes(b"partial")
+        raise ConnectionError("connection reset")
+
+    monkeypatch.setattr(appmod.transfer, "download", fail)
+    tg = use_stub(ctx)
+    await say(ctx, OWNER, "/mediainfo", reply=document_message("Show.mkv", 5 * 1024 * 1024, mid=77))
+    assert ctx.client.edited[-1][1] == "❌ I couldn't read that file." and tg.calls == [] and leftovers(ctx) == []
+
+
+# ---------------------------------------------------------------------------
+# when Telegraph does not work
+# ---------------------------------------------------------------------------
+
+
+@needs_ffmpeg
+async def test_when_telegraph_fails_the_report_comes_as_a_text_file(ctx, media_dir, monkeypatch):
+    serve(monkeypatch, media_dir)
+    use_stub(ctx, error=TelegraphError("Telegraph asks to wait 5 seconds", "FLOOD_WAIT_5"))
+    await say(ctx, OWNER, "/mediainfo", reply=document_message("Show: 05?.mkv", real_size(media_dir), mid=78))
+    (entity, file, kw), = [f for f in ctx.client.files if isinstance(f[1], io.BytesIO)]
+    assert entity == OWNER and file.name == "Show_ 05_ - MediaInfo.txt" and kw["force_document"] is True
+    assert "Telegraph asks to wait 5 seconds, so here it is as a text file." in kw["caption"] and kw["parse_mode"] == "html"
+    text = file.getvalue().decode()
+    assert text.startswith("General\n") and "\nVideo\n" in text and "\nTelegram\nFile name" in text and "Show: 05?.mkv" in text
+    assert (OWNER, [1001]) in ctx.client.deleted  # the "Reading…" message goes
+    assert leftovers(ctx) == []
+
+
+async def test_another_telegraph_failure_does_not_show_its_details(ctx, monkeypatch):
+    serve_junk(monkeypatch)
+    use_stub(ctx, error=RuntimeError("secret token abc123 rejected"))
+    await say(ctx, OWNER, "/mediainfo", reply=document_message("Show.mkv", 2 * 1024 * 1024, mid=79))
+    (_e, _file, kw), = [f for f in ctx.client.files if isinstance(f[1], io.BytesIO)]
+    assert "Telegraph is not available, so here it is as a text file." in kw["caption"] and "abc123" not in kw["caption"]
+
+
+async def test_an_unexpected_error_does_not_leave_the_reading_message_hanging(ctx, monkeypatch):
+    def broken(message, caption=True):
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(appmod, "telegram_facts", broken)
+    ev = await say(ctx, OWNER, "/mediainfo", reply=document_message("Show.mkv", 2 * 1024 * 1024, mid=80))
+    assert ev.texts == ["🔎 Reading the file…"]
+    assert ctx.client.edited[-1][1] == "⚠️ Something went wrong while reading that file."
+
+
+# ---------------------------------------------------------------------------
+# access and plumbing
+# ---------------------------------------------------------------------------
+
+
+async def test_only_allowed_users_can_use_it(ctx, monkeypatch):
+    tg = use_stub(ctx)
+    ev = await say(ctx, STRANGER, "/mediainfo", reply=document_message("Show.mkv", 1024, mid=81))
+    assert ev.out == [] and tg.calls == []
+
+
+async def test_the_command_is_in_the_menu():
+    commands = dict(appmod.COMMANDS)
+    assert "mediainfo" in commands and 3 <= len(commands["mediainfo"]) <= 256
+
+
+async def test_the_telegraph_token_lives_in_the_database(ctx):
+    assert await ctx.app._load_telegraph_token() is None
+    await ctx.app._save_telegraph_token("abc")
+    assert await ctx.app._load_telegraph_token() == "abc" and await ctx.db.kv_get("telegraph_token") == "abc"
+    await ctx.app._save_telegraph_token("")  # what the client does when Telegraph rejects the token
+    assert await ctx.db.kv_get("telegraph_token") is None
+
+
+@needs_ffmpeg
+async def test_the_whole_chain_with_the_real_client_and_a_fake_telegraph(ctx, media_dir, monkeypatch):
+    serve(monkeypatch, media_dir, "sample.mp4")
+    fake = await serve_fake_telegraph()
+    try:
+        ctx.app.telegraph = Telegraph(ctx.app._load_telegraph_token, ctx.app._save_telegraph_token, api=fake.url)
+        ctx.app.telegraph.set_author("Rename Bot", "https://t.me/rename_bot")
+        await say(ctx, OWNER, "/mediainfo", reply=document_message("Movie.mp4", real_size(media_dir, "sample.mp4"), mid=82, mime="video/mp4"))
+        await say(ctx, OWNER, "/mediainfo", reply=document_message("Movie 2.mp4", real_size(media_dir, "sample.mp4"), mid=83, mime="video/mp4"))
+        assert fake.accounts == 1 and len(fake.pages) == 2  # one account, kept for the second page
+        assert await ctx.db.kv_get("telegraph_token") == "token1"
+        page = fake.pages[0]
+        assert page["title"] == "MediaInfo – Movie.mp4" and page["author_name"] == "Rename Bot" and page["author_url"] == "https://t.me/rename_bot"
+        assert "Audio #2" in page["content"] and "Movie.mp4" in page["content"]
+        assert "https://telegra.ph/Page-1" in ctx.client.edited[-2][1] and "https://telegra.ph/Page-2" in ctx.client.edited[-1][1]
+    finally:
+        await fake.server.close()

tests/test_parser.py

@@ -3,7 +3,6 @@ import pytest
 from bot.parser import (
     DEFAULT_TEMPLATE,
     apply_remove_words,
-    build_manual_name,
     compute_new_name,
     finalize_name,
     missing_variables,
@@ -186,18 +185,6 @@ def test_finalize_truncates_by_bytes_and_keeps_ext():
     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

@@ -286,3 +286,84 @@ def test_helpers():
     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"
+
+
+# ---------------------------------------------------------------------------
+# saved /rename formats
+# ---------------------------------------------------------------------------
+
+
+async def make_fmt(env, name="One Piece", **changes):
+    fmt = await env.db.create_format(42, name, template="One Piece - E{episode}")
+    if changes:
+        await env.db.update_format(42, fmt["id"], **changes)
+    return await env.db.get_format(42, fmt["id"])
+
+
+@needs_ffmpeg
+async def test_a_format_brings_its_own_metadata_tracks_and_thumbnail(env):
+    # the global metadata is off and has a different title: the format must not depend on either
+    await env.db.update_settings(42, metadata_on=False, meta={"title": "GLOBAL"}, keep_audio=["hindi"])
+    await env.db.set_thumb(42, b"\xff\xd8global")
+    fmt = await make_fmt(env, meta={"title": "One Piece", "audio": "{lang}"}, keep_audio=["english", "japanese"], keep_subtitle=["2"])
+    await env.db.set_format_thumb(42, fmt["id"], b"\xff\xd8format")
+    fmt = await env.db.get_format(42, fmt["id"])
+
+    client, renamer, job = make(env)
+    job.fmt = fmt
+    await renamer.process(job)
+
+    out = await probe(client.uploads[0])
+    assert [s.lang for s in out.audio] == ["eng", "jpn"] and [s.lang for s in out.subtitles] == ["eng"]
+    assert out.tags.get("title") == "One Piece" and [s.title for s in out.audio] == ["English", "Japanese"]
+    (_t, _f, kw), = client.sent
+    assert kw["thumb"] == b"\xff\xd8format"
+    assert job.state == "done"
+
+
+@needs_ffmpeg
+async def test_a_format_without_a_thumbnail_uses_the_users_default_one(env):
+    await env.db.set_thumb(42, b"\xff\xd8global")
+    fmt = await make_fmt(env)
+    client, renamer, job = make(env)
+    job.fmt = fmt
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    assert kw["thumb"] == b"\xff\xd8global"
+
+
+@needs_ffmpeg
+async def test_a_format_that_sets_no_metadata_leaves_the_file_untouched_even_if_global_metadata_is_on(env):
+    await env.db.update_settings(42, metadata_on=True, meta={"title": "GLOBAL"}, keep_audio=["english"])
+    fmt = await make_fmt(env)
+    client, renamer, job = make(env)
+    job.fmt = fmt
+    await renamer.process(job)
+    assert client.uploads[0].read_bytes() == (env.media_dir / "sample.mkv").read_bytes()  # no ffmpeg pass
+    assert job.state == "done"
+
+
+@needs_ffmpeg
+async def test_everything_else_still_comes_from_the_users_settings(env):
+    await env.db.update_settings(42, file_type="document", caption="<b>{filename}</b> by me", target_channel=-100777)
+    fmt = await make_fmt(env, meta={"title": "T"})
+    client, renamer, job = make(env)
+    job.fmt = fmt
+    job.new_name = "One Piece - E5.mkv"
+    await renamer.process(job)
+    (target, _f, kw), = client.sent
+    assert target == -100777 and kw["force_document"] is True and kw["caption"] == "<b>One Piece - E5</b> by me"
+
+
+@needs_ffmpeg
+async def test_a_format_deleted_while_queued_falls_back_to_the_users_thumbnail_and_still_finishes(env):
+    await env.db.set_thumb(42, b"\xff\xd8global")
+    fmt = await make_fmt(env, meta={"title": "One Piece"})
+    await env.db.delete_format(42, fmt["id"])
+    client, renamer, job = make(env)
+    job.fmt = fmt  # the snapshot taken when the file was queued
+    await renamer.process(job)
+    (_t, _f, kw), = client.sent
+    assert kw["thumb"] == b"\xff\xd8global" and job.state == "done"
+    out = await probe(client.uploads[0])
+    assert out.tags.get("title") == "One Piece"  # the snapshot's metadata is still applied

tests/test_resize.py

@@ -0,0 +1,225 @@
+"""/resize: pick a size, send an image, get it back resized."""
+import io
+import time
+
+from PIL import Image
+
+from bot import app as appmod
+from bot import panels
+
+from .appkit import OWNER, STRANGER, click, data_of, jpeg, say, send_doc
+from .tgfakes import FakeEvent, FakeMessage, dispatch
+
+FULL_HD = (1920, 1080)
+
+
+def results(ctx):
+    return [(entity, file, kw) for entity, file, kw in ctx.client.files if isinstance(file, io.BytesIO)]
+
+
+def size_of(file):
+    return Image.open(io.BytesIO(file.getvalue())).size
+
+
+async def send_photo(ctx, mid=50, data=None, sender=OWNER):
+    ctx.client.media[mid] = data if data is not None else jpeg(FULL_HD)
+    ev = FakeEvent(sender, message=FakeMessage("", photo=True, mid=mid), photo_bytes=jpeg())
+    await dispatch(ctx.client, ev)
+    return ev
+
+
+async def send_image_file(ctx, name="poster.png", mid=51, data=None, size=200 * 1024):
+    ctx.client.media[mid] = data if data is not None else jpeg(FULL_HD)
+    return await send_doc(ctx, OWNER, name, size=size, video=False, mime="image/png", mid=mid)
+
+
+# ---------------------------------------------------------------------------
+# choosing the size
+# ---------------------------------------------------------------------------
+
+
+async def test_resize_offers_the_sizes(ctx):
+    ev = await say(ctx, OWNER, "/resize")
+    text, buttons = ev.texts[0], data_of(ev.out[0][1])
+    assert "RESIZE IMAGE" in text and "200 KB" in text and "/resize 320x180" in text
+    assert buttons == ["rz:s:320", "rz:s:640", "rz:s:1280", "rz:custom", "x:close"]
+    assert OWNER not in ctx.app.modes  # nothing is waiting for an image until a size is chosen
+
+
+async def test_a_preset_button_makes_the_bot_wait_for_the_image(ctx):
+    cb = await click(ctx, OWNER, "rz:s:320")
+    assert "Size: <b>320 px</b>" in cb.edits[-1][0] and "one image at a time" in cb.edits[-1][0]
+    assert data_of(cb.edits[-1][1]) == ["rz:menu", "rz:stop"]
+    mode = ctx.app.modes[OWNER]
+    assert mode.kind == "resize" and mode.data == {"box": (320, 320)} and mode.expires > time.time() + 500
+    await click(ctx, OWNER, "rz:s:1280")
+    assert ctx.app.modes[OWNER].data["box"] == (1280, 1280)
+
+
+async def test_unknown_presets_are_ignored(ctx):
+    cb = await click(ctx, OWNER, "rz:s:999")
+    assert cb.edits == [] and OWNER not in ctx.app.modes
+
+
+async def test_the_size_can_be_given_with_the_command(ctx):
+    ev = await say(ctx, OWNER, "/resize 320x180")
+    assert "<b>320×180</b>" in ev.texts[0] and ctx.app.modes[OWNER].data["box"] == (320, 180)
+    ev = await say(ctx, OWNER, "/resize 640")
+    assert "<b>640 px</b>" in ev.texts[0] and ctx.app.modes[OWNER].data["box"] == (640, 640)
+    for bad in ("tiny", "10x10", "99999", "320 px"):
+        ev = await say(ctx, OWNER, f"/resize {bad}")
+        assert "❌" in ev.texts[0] and "/resize 320x180" in ev.texts[0], bad
+    assert ctx.app.modes[OWNER].data["box"] == (640, 640)  # a bad size does not disturb the one that was set
+
+
+async def test_a_custom_size_is_typed_in(ctx):
+    cb = await click(ctx, OWNER, "rz:custom", msg_id=500)
+    p = ctx.app.pending[OWNER]
+    assert p.kind == "resize:size" and p.msg_id == 500 and cb.edits[-1][0] == panels.RESIZE_CUSTOM_PROMPT
+    assert data_of(cb.edits[-1][1]) == ["rz:menu"]
+
+    ev = await say(ctx, OWNER, "nonsense", mid=60)
+    assert "couldn't read that size" in ev.texts[0] and "Try again" in ev.texts[0] and OWNER in ctx.app.pending
+
+    ev = await say(ctx, OWNER, "300 x 200", mid=61)
+    assert ev.deleted and OWNER not in ctx.app.pending
+    assert ctx.app.modes[OWNER].data["box"] == (300, 200)
+    (chat, text, kw), = ctx.client.edited
+    assert kw["message"] == 500 and "<b>300×200</b>" in text and data_of(kw["buttons"]) == ["rz:menu", "rz:stop"]
+
+
+async def test_cancelling_the_custom_prompt_goes_back_to_the_sizes(ctx):
+    await click(ctx, OWNER, "rz:custom")
+    cb = await click(ctx, OWNER, "rz:menu")
+    assert OWNER not in ctx.app.pending and "RESIZE IMAGE" in cb.edits[-1][0]
+
+
+async def test_change_size_and_stop_buttons(ctx):
+    await click(ctx, OWNER, "rz:s:320")
+    cb = await click(ctx, OWNER, "rz:menu")
+    assert "RESIZE IMAGE" in cb.edits[-1][0] and OWNER not in ctx.app.modes
+    await click(ctx, OWNER, "rz:s:320")
+    cb = await click(ctx, OWNER, "rz:stop")
+    assert "Stopped" in cb.edits[-1][0] and OWNER not in ctx.app.modes
+
+
+# ---------------------------------------------------------------------------
+# resizing
+# ---------------------------------------------------------------------------
+
+
+async def test_a_photo_comes_back_resized(ctx):
+    await say(ctx, OWNER, "/resize 320")
+    await send_photo(ctx)
+    (entity, file, kw), = results(ctx)
+    assert entity == OWNER and file.name == "resized.jpg" and size_of(file) == (320, 180)
+    assert len(file.getvalue()) <= 200 * 1024
+    assert "<b>320×180</b>" in kw["caption"] and "was 1920×1080" in kw["caption"] and kw["parse_mode"] == "html"
+    assert kw["force_document"] is False
+    assert OWNER not in ctx.app.modes
+    assert ctx.client.downloads == [(50, bytes, None)]
+
+
+async def test_an_image_sent_as_a_file_works_too(ctx):
+    await say(ctx, OWNER, "/resize 640x360")
+    ev = await send_image_file(ctx)
+    assert ev.out == [] and ctx.app.queue.waiting == 0  # not renamed
+    (_e, file, _kw), = results(ctx)
+    assert size_of(file) == (640, 360)
+
+
+async def test_what_is_not_an_image_does_not_use_up_the_request(ctx):
+    await say(ctx, OWNER, "/resize 320")
+    ev = await send_doc(ctx, OWNER, "Episode.mkv", mid=52)
+    assert "isn't an image" in ev.texts[0] and ctx.app.queue.waiting == 0 and results(ctx) == []
+    assert ctx.app.modes[OWNER].kind == "resize"
+    await send_photo(ctx)
+    assert len(results(ctx)) == 1
+
+
+async def test_it_handles_one_image_per_command_and_extra_photos_do_not_replace_the_thumbnail(ctx):
+    await say(ctx, OWNER, "/resize 320")
+    await send_photo(ctx, mid=50)
+    extra = await send_photo(ctx, mid=51)
+    assert "/resize handles one file at a time" in extra.texts[0]
+    assert (await send_photo(ctx, mid=52)).out == []
+    assert len(results(ctx)) == 1
+    assert not await ctx.db.has_thumb(OWNER)  # none of the extra photos became the saved thumbnail
+    doc = await send_image_file(ctx, mid=53)
+    assert doc.out == [] and ctx.app.queue.waiting == 0  # an image file right after is skipped as well, not auto-renamed
+
+    ctx.app._recent[OWNER][1] -= appmod.ONE_SHOT_GRACE + 1
+    await send_photo(ctx, mid=54)
+    assert await ctx.db.has_thumb(OWNER)  # after the grace a photo is a thumbnail again
+
+
+async def test_large_results_are_sent_as_files_so_telegram_does_not_shrink_them(ctx):
+    await say(ctx, OWNER, "/resize 2000")
+    await send_photo(ctx, data=jpeg((3000, 2000)))
+    (_e, file, kw), = results(ctx)
+    assert size_of(file) == (2000, 1333) and kw["force_document"] is True
+
+
+async def test_resize_as_a_reply_works_at_once(ctx):
+    ctx.client.media[40] = jpeg(FULL_HD)
+    reply = FakeMessage("", photo=True, mid=40)
+    await say(ctx, OWNER, "/resize", reply=reply, mid=41)
+    (_e, file, _kw), = results(ctx)
+    assert size_of(file) == (320, 180) and OWNER not in ctx.app.modes  # thumbnail size unless told otherwise
+    await say(ctx, OWNER, "/resize 640x640", reply=reply, mid=42)
+    assert size_of(results(ctx)[-1][1]) == (640, 360)
+
+
+async def test_a_picture_that_cannot_be_read_gets_an_honest_answer(ctx):
+    await say(ctx, OWNER, "/resize 320")
+    ev = await send_photo(ctx, data=b"not a picture at all")
+    assert "couldn't read that image" in ev.texts[0] and results(ctx) == []
+    ctx.client.media[50] = None
+    await say(ctx, OWNER, "/resize 320")
+    ev = await send_photo(ctx, data=b"")
+    assert "couldn't download" in ev.texts[0]
+
+
+async def test_very_large_files_are_refused_before_downloading(ctx):
+    await say(ctx, OWNER, "/resize 320")
+    ev = await send_image_file(ctx, size=appmod.RESIZE_MAX_BYTES + 1)
+    assert "I can resize images up to 20.00 MB" in ev.texts[0] and ctx.client.downloads == []
+
+
+async def test_it_expires_and_cancel_ends_it(ctx):
+    await say(ctx, OWNER, "/resize 320")
+    ctx.app.modes[OWNER].expires = time.time() - 1
+    ev = await send_doc(ctx, OWNER, "A.mkv", mid=60)
+    assert "Queued" in ev.texts[0]
+
+    await say(ctx, OWNER, "/resize 320")
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Cancelled" in ev.texts[0] and OWNER not in ctx.app.modes
+    await send_photo(ctx)
+    assert results(ctx) == [] and await ctx.db.has_thumb(OWNER)
+
+
+async def test_a_format_thumbnail_prompt_takes_priority_over_a_waiting_resize(ctx):
+    fmt = await ctx.db.create_format(OWNER, "One Piece")
+    await say(ctx, OWNER, "/resize 320")
+    await click(ctx, OWNER, f"fm:th:{fmt['id']}")  # opened later: the user is setting the format's thumbnail now
+    await dispatch(ctx.client, FakeEvent(OWNER, message=FakeMessage("", photo=True, mid=70), photo_bytes=jpeg()))
+    assert (await ctx.db.get_format(OWNER, fmt["id"]))["has_thumb"] and results(ctx) == []
+
+
+async def test_strangers_cannot_use_it(ctx):
+    ev = await say(ctx, STRANGER, "/resize 320")
+    assert ev.out == [] and STRANGER not in ctx.app.modes
+
+
+async def test_starting_it_ends_a_sequence_and_says_so(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await send_doc(ctx, OWNER, "Show - 01.mkv", mid=92)
+    ev = await say(ctx, OWNER, "/resize 320")
+    assert "1 file(s) was discarded" in ev.texts[0] and ctx.app.modes[OWNER].kind == "resize"
+    cb = await click(ctx, OWNER, "rz:s:640")  # via the menu too
+    assert "discarded" not in cb.edits[-1][0]  # the sequence was already dropped by the first command
+
+
+async def test_both_commands_are_in_the_command_menu(ctx):
+    assert "resize" in dict(appmod.COMMANDS) and "ethumb" in dict(appmod.COMMANDS)

tests/test_sequence.py

@@ -0,0 +1,199 @@
+import pytest
+
+from bot.sequence import MAX_LISTED, SeqItem, analyse, detect, format_report, ranges
+
+
+def item(mid, name, caption=""):
+    return SeqItem(msg_id=mid, name=name, caption=caption)
+
+
+def names(items):
+    return [i.name for i in items]
+
+
+# ---------------------------------------------------------------------------
+# reading the episode
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "name,expected",
+    [
+        ("1147 - One Piece [Dual] 720p @Anime_X_Universe.mkv", (1, 1147)),
+        ("[SubsPlease] Tokyo Revengers - 05 (1080p) [ABCD1234].mkv", (1, 5)),
+        ("Show.S02E14.720p.mkv", (2, 14)),
+        ("Show 1x07.mkv", (1, 7)),
+        ("One Piece [1146] 720p.mkv", (1, 1146)),
+        ("Some Movie 2023 1080p.mkv", (None, None)),
+        ("holiday video.mp4", (None, None)),
+    ],
+)
+def test_detect_from_the_file_name(name, expected):
+    assert detect(name, "", "filename") == expected
+
+
+def test_the_rename_mode_decides_which_source_is_read_first_and_the_other_is_the_fallback():
+    assert detect("Show S01E02.mkv", "Show S01E09", "filename") == (1, 2)
+    assert detect("Show S01E02.mkv", "Show S01E09", "caption") == (1, 9)
+    assert detect("random name.mkv", "One Piece - 1147", "filename") == (1, 1147)  # nothing in the name: use the caption
+    assert detect("Show S01E02.mkv", "just words", "caption") == (1, 2)  # nothing in the caption: use the name
+    assert detect("random.mkv", "", "caption") == (None, None)
+
+
+# ---------------------------------------------------------------------------
+# ordering
+# ---------------------------------------------------------------------------
+
+
+def test_files_come_out_in_ascending_episode_order_whatever_order_they_were_sent():
+    sent = [item(5, "1147 - One Piece.mkv"), item(6, "1145 - One Piece.mkv"), item(7, "1146 - One Piece.mkv"), item(8, "1148 - One Piece.mkv")]
+    a = analyse(sent, "filename")
+    assert names(a.ordered) == ["1145 - One Piece.mkv", "1146 - One Piece.mkv", "1147 - One Piece.mkv", "1148 - One Piece.mkv"]
+    assert a.missing == {} and a.repeated == {} and a.unknown == []
+    assert a.first == (1, 1145) and a.last == (1, 1148)
+
+
+def test_episode_ten_sorts_after_nine_not_after_one():
+    a = analyse([item(1, "Show - 10.mkv"), item(2, "Show - 9.mkv"), item(3, "Show - 1.mkv"), item(4, "Show - 100.mkv")], "filename")
+    assert [i.episode for i in a.ordered] == [1, 9, 10, 100]
+
+
+def test_seasons_sort_before_episodes():
+    sent = [item(1, "Show S02E01.mkv"), item(2, "Show S01E03.mkv"), item(3, "Show S01E01.mkv"), item(4, "Show S02E02.mkv")]
+    a = analyse(sent, "filename")
+    assert [(i.season, i.episode) for i in a.ordered] == [(1, 1), (1, 3), (2, 1), (2, 2)]
+    assert a.missing == {1: [2]}  # S01E02 is missing; the jump from S01 to S02 is not a gap
+    assert a.first == (1, 1) and a.last == (2, 2)
+
+
+def test_files_without_an_episode_number_go_last_in_the_order_they_were_sent():
+    sent = [item(9, "zzz.mkv"), item(3, "Show - 02.mkv"), item(4, "aaa.mkv"), item(2, "Show - 01.mkv")]
+    a = analyse(sent, "filename")
+    assert names(a.ordered) == ["Show - 01.mkv", "Show - 02.mkv", "aaa.mkv", "zzz.mkv"]
+    assert names(a.unknown) == ["aaa.mkv", "zzz.mkv"]
+
+
+def test_nothing_is_numbered():
+    a = analyse([item(1, "b.mkv"), item(2, "a.mkv")], "filename")
+    assert names(a.ordered) == ["b.mkv", "a.mkv"] and a.first is None and a.last is None and a.missing == {}
+
+
+# ---------------------------------------------------------------------------
+# gaps and repeats
+# ---------------------------------------------------------------------------
+
+
+def test_missing_episodes_are_the_gaps_between_the_first_and_the_last():
+    sent = [item(i, f"One Piece - {n}.mkv") for i, n in enumerate((1145, 1146, 1148, 1151, 1152, 1156), start=1)]
+    a = analyse(sent, "filename")
+    assert a.missing == {1: [1147, 1149, 1150, 1153, 1154, 1155]}
+    # an episode before the first one you sent is not "missing"
+    assert analyse([item(1, "S - 5.mkv"), item(2, "S - 6.mkv")], "filename").missing == {}
+    assert analyse([item(1, "S - 5.mkv")], "filename").missing == {}
+
+
+def test_repeated_episodes_list_every_file_that_shares_the_number():
+    sent = [item(1, "Show - 05 [A].mkv"), item(2, "Show - 05 [B].mkv"), item(3, "Show - 06.mkv"), item(4, "Show - 05 [C].mkv")]
+    a = analyse(sent, "filename")
+    assert list(a.repeated) == [(1, 5)] and names(a.repeated[(1, 5)]) == ["Show - 05 [A].mkv", "Show - 05 [B].mkv", "Show - 05 [C].mkv"]
+    assert names(a.ordered)[:3] == ["Show - 05 [A].mkv", "Show - 05 [B].mkv", "Show - 05 [C].mkv"]  # both copies are kept, in send order
+    assert a.missing == {}
+
+
+def test_the_same_episode_number_in_different_seasons_is_not_a_repeat():
+    a = analyse([item(1, "Show S01E01.mkv"), item(2, "Show S02E01.mkv")], "filename")
+    assert a.repeated == {}
+
+
+def test_ranges():
+    assert ranges([3, 7, 8, 9]) == "E03, E07–E09"
+    assert ranges([1147]) == "E1147"
+    assert ranges([9, 3, 4]) == "E03–E04, E09"
+    assert ranges([]) == ""
+
+
+# ---------------------------------------------------------------------------
+# the report
+# ---------------------------------------------------------------------------
+
+
+def reports(files, mode="filename", failed=()):
+    sent = [item(i, n) for i, n in enumerate(files, start=1)]
+    a = analyse(sent, mode)
+    return format_report(a, len(sent), len(sent) - len(failed), [item(0, n) for n in failed])
+
+
+def report(files, mode="filename", failed=()):
+    messages = reports(files, mode, failed)
+    assert len(messages) == 1
+    return messages[0]
+
+
+def test_a_clean_sequence_says_so():
+    text = report(["One Piece - 1145.mkv", "One Piece - 1146.mkv", "One Piece - 1147.mkv"])
+    assert "Sorted 3 files" in text and "E1145 → E1147" in text and "No missing or repeated episodes." in text
+    assert "Missing" not in text and "Repeated" not in text
+
+
+def test_files_without_a_number_do_not_hide_that_the_rest_is_complete():
+    text = report(["S - 01.mkv", "S - 02.mkv", "notes.mkv"])
+    assert "No missing or repeated episodes." in text and "No episode number found" in text
+
+
+def test_nothing_numbered_means_nothing_to_say_about_gaps():
+    text = report(["a.mkv", "b.mkv"])
+    assert "No missing or repeated" not in text and "No episode number found" in text and "→" not in text
+
+
+def test_one_file_is_not_plural():
+    assert "Sorted 1 file</b>" in report(["One Piece - 1145.mkv"])
+
+
+def test_the_report_lists_missing_repeated_and_unnumbered_files():
+    text = report(["S - 01.mkv", "S - 02 a.mkv", "S - 02 b.mkv", "S - 05.mkv", "S - 08.mkv", "notes.mkv"])
+    assert "Sorted 6 files" in text and "E01 → E08" in text
+    assert "Missing episodes</b>\nE03–E04, E06–E07" in text
+    assert "Repeated episodes" in text and "E02 ×2" in text and "S - 02 a.mkv" in text and "S - 02 b.mkv" in text
+    assert "No episode number found" in text and "notes.mkv" in text
+    assert "No missing or repeated" not in text
+
+
+def test_the_report_labels_seasons_only_when_there_are_several():
+    one = report(["S S01E01.mkv", "S S01E03.mkv"])
+    assert "E02" in one and "S01E02" not in one
+    two = report(["S S01E01.mkv", "S S01E03.mkv", "S S02E01.mkv", "S S02E02.mkv", "S S02E02 x.mkv"])
+    assert "S01: E02" in two and "S02E02 ×2" in two and "S01E01 → S02E02" in two
+
+
+def test_the_report_mentions_files_that_could_not_be_sent():
+    text = report(["S - 01.mkv", "S - 02.mkv"], failed=["S - 02.mkv"])
+    assert "Sorted 1 of 2 files" in text and "Couldn't be sent" in text and "S - 02.mkv" in text
+
+
+def test_names_are_escaped_and_long_lists_are_cut():
+    files = ["a&b <x>.mkv"] + [f"Dup {n}.mkv" for n in range(40)]
+    text = report(files)
+    assert "a&amp;b &lt;x&gt;.mkv" in text and "<x>" not in text
+    assert "… and 29 more" in text and text.count("• ") == MAX_LISTED
+
+
+def test_ranges_are_cut_when_there_are_too_many_gaps():
+    text = ranges(range(2, 2000, 2), limit=300)
+    assert len(text) <= 300 and text.endswith(" more") and text.startswith("E02, E04")
+    shown = text.count("E")
+    assert shown > 10
+    assert ranges([3, 7], limit=300) == "E03, E07"
+
+
+def test_a_huge_report_is_split_into_messages_telegram_accepts():
+    files = []
+    files += [f"Long Running Show Name With A Rather Long Title - {n}.mkv" for n in range(1, 400, 2)]  # 200 gaps
+    for n in range(1, 30):  # many repeated numbers
+        files += [f"Another Show S02E{n:02d} [v{k}] with a very long name indeed.mkv" for k in range(5)]
+    files += [f"unknown file number {n} with quite a long name for a file.mkv" for n in range(50)]
+    messages = reports(files, failed=[f"deleted file {n}.mkv" for n in range(30)])
+    assert len(messages) > 1
+    assert all(len(m) <= 4000 for m in messages)
+    joined = "\n\n".join(messages)
+    assert "Missing episodes" in joined and "Repeated episodes" in joined and "No episode number found" in joined and "Couldn't be sent" in joined
+    assert messages[0].startswith("✅ <b>Sorted")

tests/test_sequence_app.py

@@ -0,0 +1,442 @@
+"""/sequence (collect files) and /sort (send them back in episode order, then report gaps and repeats)."""
+import asyncio
+import time
+
+import pytest
+from telethon import errors
+
+from bot import app as appmod
+
+from .appkit import ADMIN_CFG, OWNER, STRANGER, click, data_of, say, send_doc
+
+OP = "{n} - One Piece [Dual] 720p @Anime_X_Universe.mkv"
+
+
+@pytest.fixture(autouse=True)
+def quick(monkeypatch):
+    monkeypatch.setattr(appmod, "SEQUENCE_STATUS_DELAY", 0.02)
+    monkeypatch.setattr(appmod, "SORT_GAP", 0)
+
+
+async def settle(delay=0.12):
+    await asyncio.sleep(delay)
+
+
+async def feed(ctx, numbers, uid=OWNER, first_id=100):
+    """Send One Piece episodes in this order; returns {episode: message id} (the last id wins for repeats)."""
+    ids = {}
+    for k, n in enumerate(numbers):
+        await send_doc(ctx, uid, OP.format(n=n), mid=first_id + k)
+        ids[n] = first_id + k
+    return ids
+
+
+def sent_ids(ctx, uid=OWNER):
+    return [f.id for entity, f, _kw in ctx.client.files if entity == uid]
+
+
+def texts(ctx):
+    return [t for _e, t, _k in ctx.client.sent]
+
+
+def last_text(ctx):
+    return ctx.client.sent[-1][1]
+
+
+# ---------------------------------------------------------------------------
+# collecting
+# ---------------------------------------------------------------------------
+
+
+async def test_sequence_asks_for_files_and_collects_them_instead_of_renaming(ctx):
+    ev = await say(ctx, OWNER, "/sequence")
+    assert "SEQUENCE" in ev.texts[0] and "/sort" in ev.texts[0] and data_of(ev.out[0][1]) == ["sq:cx"]
+    assert ctx.app.modes[OWNER].kind == "sequence"
+
+    for k, n in enumerate((1147, 1145, 1146)):
+        got = await send_doc(ctx, OWNER, OP.format(n=n), mid=100 + k)
+        assert got.out == []  # nothing is queued, nothing is said per file
+    assert ctx.app.queue.waiting == 0 and ctx.app.queue.running == 0
+    assert [i.msg_id for i in ctx.app.modes[OWNER].data.items] == [100, 101, 102]
+
+
+async def test_one_status_message_follows_each_burst_of_files_and_replaces_the_last(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1, 2, 3))
+    await settle()
+    (status,) = [(t, k) for _e, t, k in ctx.client.sent if "collected" in t]
+    assert "3 files collected" in status[0] and "/sort" in status[0]
+    assert data_of(status[1]["buttons"]) == ["sq:sort", "sq:cx"]
+    assert ctx.client.deleted == []
+
+    await send_doc(ctx, OWNER, OP.format(n=4), mid=200)
+    await settle()
+    assert [t for t in texts(ctx) if "collected" in t][-1].startswith("📥 <b>4 files collected")
+    assert ctx.client.deleted == [(OWNER, [2001])]  # the old status goes, so the newest one is at the bottom
+
+
+async def test_a_second_sequence_command_keeps_the_files_already_collected(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1, 2))
+    ev = await say(ctx, OWNER, "/sequence")
+    assert "already collecting" in ev.texts[0] and "2 files collected" in ev.texts[0] and data_of(ev.out[0][1]) == ["sq:sort", "sq:cx"]
+    assert len(ctx.app.modes[OWNER].data.items) == 2
+
+
+async def test_the_limit_is_announced_once_and_extra_files_are_ignored(ctx, monkeypatch):
+    monkeypatch.setattr(appmod, "SEQUENCE_MAX", 3)
+    await say(ctx, OWNER, "/sequence")
+    replies = []
+    for k in range(6):
+        replies += (await send_doc(ctx, OWNER, OP.format(n=k + 1), mid=100 + k)).texts
+    assert len(ctx.app.modes[OWNER].data.items) == 3
+    assert len(replies) == 1 and "limit: 3 files" in replies[0]
+    await settle()
+    assert "3 files collected" in texts(ctx)[-1] and "most I can sort" in texts(ctx)[-1]
+
+
+async def test_every_user_has_their_own_sequence(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await say(ctx, ADMIN_CFG, "/sequence")
+    await feed(ctx, (3, 1, 2), uid=OWNER, first_id=100)
+    await feed(ctx, (9, 8), uid=ADMIN_CFG, first_id=500)
+    await say(ctx, ADMIN_CFG, "/sort")
+    assert sent_ids(ctx, ADMIN_CFG) == [501, 500] and sent_ids(ctx, OWNER) == []
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx, OWNER) == [101, 102, 100]
+
+
+async def test_strangers_cannot_start_a_sequence(ctx):
+    ev = await say(ctx, STRANGER, "/sequence")
+    assert ev.out == [] and STRANGER not in ctx.app.modes
+
+
+# ---------------------------------------------------------------------------
+# /sort
+# ---------------------------------------------------------------------------
+
+
+async def test_sort_sends_the_files_back_in_ascending_episode_order(ctx):
+    await say(ctx, OWNER, "/sequence")
+    ids = await feed(ctx, (1147, 1145, 1148, 1146))
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [ids[1145], ids[1146], ids[1147], ids[1148]]
+    assert OWNER not in ctx.app.modes
+    assert "Sorted 4 files" in last_text(ctx) and "E1145 → E1148" in last_text(ctx) and "No missing or repeated episodes." in last_text(ctx)
+
+
+async def test_sort_reports_missing_and_repeated_episodes_after_the_files(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1147, 1145, 1149, 1146, 1146, 1152))
+    await say(ctx, OWNER, "/sort")
+    assert len(sent_ids(ctx)) == 6
+    report = last_text(ctx)
+    assert "Sorted 6 files" in report and "E1145 → E1152" in report
+    assert "Missing episodes</b>\nE1148, E1150–E1151" in report
+    assert "Repeated episodes" in report and "E1146 ×2" in report
+    assert "No missing or repeated" not in report
+    assert ctx.client.sent[-1][2]["parse_mode"] == "html"
+
+
+async def test_files_without_an_episode_number_are_sent_last_and_listed(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await send_doc(ctx, OWNER, "notes.mkv", mid=100)
+    await send_doc(ctx, OWNER, OP.format(n=2), mid=101)
+    await send_doc(ctx, OWNER, OP.format(n=1), mid=102)
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [102, 101, 100]
+    assert "No episode number found" in last_text(ctx) and "notes.mkv" in last_text(ctx)
+
+
+async def test_captions_and_their_formatting_travel_with_each_file(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await send_doc(ctx, OWNER, OP.format(n=2), mid=100, caption="Episode two <b>bold</b>")
+    await send_doc(ctx, OWNER, OP.format(n=1), mid=101)
+    ctx.client.messages[100].entities = ["BOLD-ENTITY"]
+    await say(ctx, OWNER, "/sort")
+    (_e1, first, kw1), (_e2, second, kw2) = ctx.client.files
+    assert (first.id, second.id) == (101, 100)
+    assert kw1["caption"] == "" and kw2["caption"] == "Episode two <b>bold</b>"
+    assert kw2["formatting_entities"] == ["BOLD-ENTITY"] and kw2["parse_mode"] is None  # the text is not parsed a second time
+
+
+async def test_sort_fetches_the_messages_again_so_old_file_references_still_work(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (2, 1, 3))
+    await say(ctx, OWNER, "/sort")
+    (chat, ids), = ctx.client.get_calls
+    assert chat == OWNER and sorted(ids) == [100, 101, 102] and ids == [101, 100, 102]
+
+
+async def test_the_rename_mode_decides_where_the_episode_is_read_from(ctx):
+    await say(ctx, OWNER, "/mode caption")
+    await say(ctx, OWNER, "/sequence")
+    await send_doc(ctx, OWNER, "video.mkv", mid=100, caption="One Piece - 1147")
+    await send_doc(ctx, OWNER, "other.mkv", mid=101, caption="One Piece - 1145")
+    await send_doc(ctx, OWNER, "clip.mkv", mid=102, caption="One Piece - 1146")
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [101, 102, 100]
+    assert "E1145 → E1147" in last_text(ctx)
+
+
+async def test_sort_with_nothing_collected_explains_how_it_works(ctx):
+    for _ in range(2):
+        await say(ctx, OWNER, "/sort")
+        assert "Nothing to sort yet" in last_text(ctx) and "/sequence" in last_text(ctx)
+        await say(ctx, OWNER, "/sequence")  # started but empty: still nothing to sort
+    assert ctx.client.files == []
+
+
+async def test_after_a_sort_files_are_renamed_as_usual_again(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1, 2))
+    await say(ctx, OWNER, "/sort")
+    ev = await send_doc(ctx, OWNER, OP.format(n=3), mid=300)
+    assert "Queued" in ev.texts[0] and ctx.app.queue.waiting == 1
+    # and a new sequence starts from scratch
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (7,), first_id=400)
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx)[-1] == 400 and "Sorted 1 file" in last_text(ctx)
+
+
+async def test_a_sequence_that_nobody_finished_is_forgotten_after_its_time(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1, 2))
+    ctx.app.modes[OWNER].expires = time.time() - 1
+    await say(ctx, OWNER, "/sort")
+    assert "Nothing to sort yet" in last_text(ctx) and ctx.client.files == []
+    ev = await send_doc(ctx, OWNER, OP.format(n=3), mid=300)
+    assert "Queued" in ev.texts[0]
+
+
+async def test_every_new_file_gives_the_sequence_more_time(ctx):
+    await say(ctx, OWNER, "/sequence")
+    mode = ctx.app.modes[OWNER]
+    mode.expires = time.time() + 5
+    await feed(ctx, (1,))
+    assert mode.expires > time.time() + appmod.SEQUENCE_WAIT - 60
+
+
+async def test_the_status_message_is_removed_and_a_progress_message_replaces_it(ctx, monkeypatch):
+    monkeypatch.setattr(appmod, "SORT_PROGRESS_EVERY", 2)
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (5, 4, 3, 2, 1))
+    await settle()
+    status_id = [2000 + i + 1 for i, (_e, t, _k) in enumerate(ctx.client.sent) if "collected" in t][-1]
+    await say(ctx, OWNER, "/sort")
+    assert (OWNER, [status_id]) in ctx.client.deleted
+    progress = [t for _c, t, _k in ctx.client.edited]
+    assert progress == ["🔢 <b>Sorting…</b> 2 of 5 sent", "🔢 <b>Sorting…</b> 4 of 5 sent"]
+    sorting_id = [2000 + i + 1 for i, (_e, t, _k) in enumerate(ctx.client.sent) if "Sorting 5 files" in t][0]
+    assert (OWNER, [sorting_id]) in ctx.client.deleted  # the progress message goes before the report
+
+
+# ---------------------------------------------------------------------------
+# buttons
+# ---------------------------------------------------------------------------
+
+
+async def test_the_sort_button_does_the_same_as_the_command(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (3, 1, 2))
+    cb = await click(ctx, OWNER, "sq:sort")
+    assert cb.answers and sent_ids(ctx) == [101, 102, 100] and "Sorted 3 files" in last_text(ctx)
+
+
+async def test_the_discard_button_throws_the_files_away(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (3, 1))
+    cb = await click(ctx, OWNER, "sq:cx")
+    assert "2 files discarded" in cb.edits[-1][0] and cb.edits[-1][1] == []
+    assert OWNER not in ctx.app.modes
+    await say(ctx, OWNER, "/sort")
+    assert "Nothing to sort yet" in last_text(ctx)
+
+
+async def test_old_buttons_say_the_sequence_is_over(ctx):
+    for data in ("sq:sort", "sq:cx"):
+        cb = await click(ctx, OWNER, data)
+        assert cb.alerts == ["That sequence is over."]
+    assert ctx.client.files == [] and ctx.client.sent == []
+
+
+# ---------------------------------------------------------------------------
+# /cancel
+# ---------------------------------------------------------------------------
+
+
+async def test_cancel_discards_the_collected_files(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (2, 1))
+    await settle()
+    status_id = 2001  # the "2 files collected" message
+    before = len([t for t in texts(ctx) if "collected" in t])
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Sequence cancelled" in ev.texts[0] and "2 files discarded" in ev.texts[0]
+    assert (OWNER, [status_id]) in ctx.client.deleted  # its buttons would be dead, so it goes
+    await say(ctx, OWNER, "/sort")
+    assert "Nothing to sort yet" in last_text(ctx)
+    await settle()
+    assert len([t for t in texts(ctx) if "collected" in t]) == before == 1  # no new status after the cancel
+    ev = await send_doc(ctx, OWNER, OP.format(n=1), mid=300)
+    assert "Queued" in ev.texts[0]
+
+
+async def test_cancel_leaves_queued_jobs_for_the_next_cancel(ctx):
+    await send_doc(ctx, OWNER, OP.format(n=9), mid=50)
+    assert ctx.app.queue.waiting == 1
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (2,))
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Sequence cancelled" in ev.texts[0] and "/cancel again" in ev.texts[0] and ctx.app.queue.waiting == 1
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Cancelling 1 job" in ev.texts[0]
+
+
+async def test_cancel_stops_a_sort_that_is_sending(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (5, 4, 3, 2, 1))
+    gate = asyncio.Event()
+    original = ctx.client.send_file
+    calls = []
+
+    async def slow(entity, file, **kw):
+        calls.append(file.id)
+        if len(calls) == 2:
+            await gate.wait()
+        return await original(entity, file, **kw)
+
+    ctx.client.send_file = slow
+    sorting = asyncio.ensure_future(say(ctx, OWNER, "/sort"))
+    await settle(0.05)
+    assert calls == [104, 103]  # episode 1, then 2 is in flight
+
+    again = await say(ctx, OWNER, "/sort")  # a second /sort while one is running
+    assert again.out == [] and "still sorting" in last_text(ctx)
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Stopping the sort" in ev.texts[0]
+    gate.set()
+    await sorting
+    assert sent_ids(ctx) == [104, 103] and "Stopped after 2 of 5 files" in last_text(ctx)
+    assert "Sorted" not in last_text(ctx) and OWNER not in ctx.app._sorting
+
+
+# ---------------------------------------------------------------------------
+# things going wrong while sending
+# ---------------------------------------------------------------------------
+
+
+async def test_a_short_flood_wait_is_waited_out_and_the_file_is_sent_again(ctx):
+    slept = []
+
+    async def pause(seconds):
+        slept.append(seconds)
+
+    ctx.app._pause = pause
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (2, 1, 3))
+    ctx.client.file_errors[100] = [errors.FloodWaitError(None, 90)]
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [101, 100, 102] and slept == [91]
+    assert "Sorted 3 files" in last_text(ctx) and "Couldn't be sent" not in last_text(ctx)
+
+
+async def test_a_very_long_flood_wait_stops_the_sort_and_lists_what_was_not_sent(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (4, 3, 2, 1))
+    ctx.client.file_errors[102] = [errors.FloodWaitError(None, 3600)]  # episode 2
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [103]  # episode 1 went out, the wait hit at episode 2
+    report = last_text(ctx)
+    assert "Sorted 1 of 4 files" in report and "wait 1h 0m 0s" in report and "Couldn't be sent" in report
+    assert report.count(OP.format(n=2)[:20]) >= 1 and OP.format(n=4)[:4] in report
+
+
+async def test_a_status_that_is_still_being_sent_when_sort_starts_is_cleaned_up(ctx):
+    original = ctx.client.send_message
+    release = asyncio.Event()
+
+    async def slow_status(entity, text="", **kw):
+        if "collected" in text:
+            await release.wait()
+        return await original(entity, text, **kw)
+
+    ctx.client.send_message = slow_status
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (2, 1))
+    await settle()  # the status message is on its way, not sent yet
+    await say(ctx, OWNER, "/sort")
+    release.set()
+    await settle()
+    collected = [i + 1 + 2000 for i, (_e, t, _k) in enumerate(ctx.client.sent) if "collected" in t]
+    assert len(collected) == 1 and (OWNER, collected) in ctx.client.deleted
+    assert "Sorted 2 files" in last_text(ctx) or sent_ids(ctx) == [101, 100]
+
+
+async def test_a_file_that_fails_is_listed_and_the_others_still_arrive(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (3, 2, 1))
+    ctx.client.file_errors[101] = [RuntimeError("MEDIA_EMPTY")]  # episode 2
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [102, 100]
+    report = last_text(ctx)
+    assert "Sorted 2 of 3 files" in report and "Couldn't be sent" in report and "2 - One Piece" in report
+
+
+async def test_a_file_deleted_before_sorting_is_listed_not_fatal(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (3, 2, 1))
+    del ctx.client.messages[101]
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [102, 100]
+    assert "Sorted 2 of 3 files" in last_text(ctx) and "Couldn't be sent" in last_text(ctx)
+    assert OWNER not in ctx.app._sorting
+
+
+async def test_sort_that_blows_up_does_not_leave_the_user_locked_out(ctx):
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (2, 1))
+
+    async def boom(*a, **kw):
+        raise RuntimeError("telegram is down")
+
+    original, ctx.client.get_messages = ctx.client.get_messages, boom
+    ev = await say(ctx, OWNER, "/sort")
+    assert "Something went wrong" in ev.texts[-1] and OWNER not in ctx.app._sorting
+    ctx.client.get_messages = original
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1,), first_id=300)
+    await say(ctx, OWNER, "/sort")
+    assert sent_ids(ctx) == [300]
+
+
+# ---------------------------------------------------------------------------
+# other commands that wait for a file
+# ---------------------------------------------------------------------------
+
+
+async def test_starting_a_rename_ends_the_sequence_and_says_so(ctx):
+    fmt = await ctx.db.create_format(OWNER, "One Piece")
+    await say(ctx, OWNER, "/sequence")
+    await feed(ctx, (1, 2))
+    cb = await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    assert "One Piece" in cb.edits[-1][0] and "2 file(s) was discarded" in cb.edits[-1][0]
+    assert ctx.app.modes[OWNER].kind == "rename"
+    await settle()
+    assert [t for t in texts(ctx) if "collected" in t] == []
+
+
+async def test_a_rename_with_no_sequence_has_no_such_note(ctx):
+    fmt = await ctx.db.create_format(OWNER, "One Piece")
+    cb = await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    assert "discarded" not in cb.edits[-1][0]
+
+
+async def test_starting_a_sequence_over_a_rename_session_replaces_it(ctx):
+    fmt = await ctx.db.create_format(OWNER, "One Piece")
+    await click(ctx, OWNER, f"rn:p:{fmt['id']}")
+    ev = await say(ctx, OWNER, "/sequence")
+    assert "discarded" not in ev.texts[0] and ctx.app.modes[OWNER].kind == "sequence"
+    await send_doc(ctx, OWNER, OP.format(n=1), mid=100)
+    assert ctx.app.queue.waiting == 0  # collected, not renamed

tests/test_smedia.py

@@ -0,0 +1,337 @@
+"""/smedia: the owner picks an image or a GIF, and /start shows it above the menu."""
+import base64
+import io
+import json
+import time
+from types import SimpleNamespace
+
+from PIL import Image
+from telethon import types
+
+from bot import app as appmod
+
+from .appkit import ADMIN_CFG, OWNER, STRANGER, click, data_of, jpeg, say, send_doc
+from .tgfakes import FakeEvent, FakeMessage, dispatch, make_file
+
+GIF_BYTES = b"\x00\x00\x00\x18ftypmp42-fake-animation-bytes"
+
+
+def uploads(ctx):
+    """The files the bot uploaded (bytes), as (chat, file, kwargs)."""
+    return [(entity, file, kw) for entity, file, kw in ctx.client.files if isinstance(file, io.BytesIO)]
+
+
+async def send_photo(ctx, mid=50, data=None, sender=OWNER):
+    ctx.client.media[mid] = data if data is not None else jpeg((800, 600))
+    ev = FakeEvent(sender, message=FakeMessage("", photo=True, mid=mid), photo_bytes=jpeg())  # photo_bytes: what a thumbnail is made of
+    await dispatch(ctx.client, ev)
+    return ev
+
+
+async def send_image_file(ctx, name="banner.png", mid=51, data=None, size=200 * 1024, sender=OWNER):
+    ctx.client.media[mid] = data if data is not None else jpeg((800, 600))
+    return await send_doc(ctx, sender, name, size=size, video=False, mime="image/png", mid=mid)
+
+
+async def send_gif(ctx, mid=60, data=GIF_BYTES, size=1024 * 1024, sender=OWNER):
+    ctx.client.media[mid] = data
+    file = make_file("anim.mp4", size, "video/mp4", width=480, height=270, duration=3.5)
+    ev = FakeEvent(sender, message=FakeMessage("", mid=mid, file=file, video=True, gif=True))
+    await dispatch(ctx.client, ev)
+    return ev
+
+
+async def choose(ctx, kind):
+    return await click(ctx, OWNER, f"sm:{kind}")
+
+
+async def stored(ctx):
+    """(description, file bytes) of the saved /start media, or (None, None)."""
+    meta = await ctx.db.kv_get("start_media")
+    data = await ctx.db.kv_get("start_media_data")
+    return (json.loads(meta) if meta else None), (base64.b64decode(data) if data else None)
+
+
+def telegram_gives_ids(ctx, *ids):
+    """Make send_file answer like Telegram does: with a message whose file has an id."""
+    original, wanted = ctx.client.send_file, iter(ids)
+
+    async def send_file(entity, file, **kw):
+        sent = await original(entity, file, **kw)
+        sent.file = SimpleNamespace(id=next(wanted, "FILEID-LATER"))
+        return sent
+
+    ctx.client.send_file = send_file
+
+
+def file_ids_go_stale(ctx):
+    """Sending by file id fails (an expired reference); uploading still works."""
+    original = ctx.client.send_file
+
+    async def send_file(entity, file, **kw):
+        if isinstance(file, str):
+            raise RuntimeError("FILE_REFERENCE_EXPIRED")
+        return await original(entity, file, **kw)
+
+    ctx.client.send_file = send_file
+
+
+# ---------------------------------------------------------------------------
+# the menu
+# ---------------------------------------------------------------------------
+
+
+async def test_the_menu_offers_image_and_gif(ctx):
+    ev = await say(ctx, OWNER, "/smedia")
+    assert "START MEDIA" in ev.texts[0] and "/start shows: <b>nothing, just the menu</b>" in ev.texts[0]
+    assert data_of(ev.out[0][1]) == ["sm:image", "sm:gif", "x:close"]  # nothing to remove yet
+    assert OWNER not in ctx.app.modes
+
+
+async def test_only_the_owner_can_use_it(ctx):
+    assert "smedia" in appmod.OWNER_COMMANDS and "smedia" not in dict(appmod.COMMANDS)  # not in the public command menu
+    ev = await say(ctx, ADMIN_CFG, "/smedia")
+    assert ev.texts == ["⛔ Only the owner can do that."]
+    assert (await say(ctx, STRANGER, "/smedia")).out == []
+    cb = await click(ctx, ADMIN_CFG, "sm:image")  # an allowed user who got hold of the buttons
+    assert cb.alerts == ["Owner only."] and ADMIN_CFG not in ctx.app.modes
+    assert not hasattr(ctx.cfg, "start_image")  # the START_IMAGE setting is gone
+
+
+async def test_choosing_makes_the_bot_wait_for_that_kind_of_media(ctx):
+    cb = await choose(ctx, "image")
+    assert "Send the image" in cb.edits[-1][0] and "/cancel to stop" in cb.edits[-1][0]
+    assert data_of(cb.edits[-1][1]) == ["sm:menu", "sm:stop"]
+    mode = ctx.app.modes[OWNER]
+    assert mode.kind == "smedia" and mode.data == {"kind": "image"} and mode.expires > time.time() + 500
+    cb = await choose(ctx, "gif")
+    assert "Send the GIF" in cb.edits[-1][0] and ctx.app.modes[OWNER].data == {"kind": "gif"}
+
+
+async def test_back_stop_and_cancel_leave_nothing_waiting(ctx):
+    await choose(ctx, "image")
+    cb = await click(ctx, OWNER, "sm:menu")
+    assert "START MEDIA" in cb.edits[-1][0] and OWNER not in ctx.app.modes
+    await choose(ctx, "gif")
+    cb = await click(ctx, OWNER, "sm:stop")
+    assert "Stopped" in cb.edits[-1][0] and OWNER not in ctx.app.modes
+    await choose(ctx, "gif")
+    ev = await say(ctx, OWNER, "/cancel")
+    assert "Send /smedia again" in ev.texts[0] and OWNER not in ctx.app.modes
+
+
+# ---------------------------------------------------------------------------
+# an image
+# ---------------------------------------------------------------------------
+
+
+async def test_a_photo_becomes_the_start_image_and_is_shown_right_away(ctx):
+    await choose(ctx, "image")
+    photo = jpeg((800, 600))
+    ev = await send_photo(ctx, data=photo)
+    (entity, file, kw), = uploads(ctx)
+    assert entity == OWNER and file.name == "start.jpg" and file.getvalue() == photo
+    assert "Auto Rename Bot" in kw["caption"] and "m:rename" in data_of(kw["buttons"]) and kw["parse_mode"] == "html"
+    assert ev.texts == ["✅ Done: /start shows this image from now on."]
+    assert OWNER not in ctx.app.modes and ctx.client.downloads == [(50, bytes, None)]
+    meta, data = await stored(ctx)
+    assert meta == {"kind": "image", "file_id": ""} and data == photo
+
+
+async def test_the_menu_then_shows_what_is_set_and_offers_to_remove_it(ctx):
+    await choose(ctx, "image")
+    await send_photo(ctx)
+    ev = await say(ctx, OWNER, "/smedia")
+    assert "/start shows: <b>an image</b>" in ev.texts[0] and data_of(ev.out[0][1]) == ["sm:image", "sm:gif", "sm:rm", "x:close"]
+
+
+async def test_an_image_sent_as_a_file_is_made_to_fit_without_being_enlarged(ctx):
+    await choose(ctx, "image")
+    ev = await send_image_file(ctx, data=jpeg((3000, 2000)))
+    assert ev.texts == ["✅ Done: /start shows this image from now on."] and ctx.app.queue.waiting == 0  # not renamed
+    _meta, data = await stored(ctx)
+    img = Image.open(io.BytesIO(data))
+    assert img.format == "JPEG" and img.size == (1280, 853)
+    await choose(ctx, "image")
+    await send_image_file(ctx, mid=52, data=jpeg((400, 300)))
+    assert Image.open(io.BytesIO((await stored(ctx))[1])).size == (400, 300)  # smaller pictures stay as they are
+
+
+async def test_what_is_not_an_image_does_not_use_up_the_request(ctx):
+    await choose(ctx, "image")
+    ev = await send_doc(ctx, OWNER, "Episode.mkv", mid=53)
+    assert "isn't an image" in ev.texts[0] and ctx.app.queue.waiting == 0 and uploads(ctx) == []  # not renamed either
+    ev = await send_gif(ctx)
+    assert "isn't an image" in ev.texts[0]
+    assert ctx.app.modes[OWNER].kind == "smedia"
+    await send_photo(ctx)
+    assert len(uploads(ctx)) == 1 and (await stored(ctx))[0]["kind"] == "image"
+
+
+async def test_a_picture_that_cannot_be_read_is_refused(ctx):
+    await choose(ctx, "image")
+    ev = await send_image_file(ctx, data=b"this is not a picture")
+    assert "couldn't read that image" in ev.texts[0] and await stored(ctx) == (None, None) and uploads(ctx) == []
+
+
+async def test_a_download_that_gives_nothing_is_reported(ctx):
+    await choose(ctx, "image")
+    ev = await send_photo(ctx, data=b"")
+    assert "couldn't download that" in ev.texts[0] and "/smedia" in ev.texts[0]
+    assert await stored(ctx) == (None, None) and OWNER not in ctx.app.modes
+
+
+async def test_a_file_that_is_too_big_is_refused_and_the_request_stays(ctx):
+    await choose(ctx, "image")
+    ev = await send_image_file(ctx, size=appmod.START_MEDIA_MAX_BYTES + 1)
+    assert "the biggest I can keep is 10.00 MB" in ev.texts[0] and await stored(ctx) == (None, None)
+    assert ctx.app.modes[OWNER].kind == "smedia" and ctx.client.downloads == []  # refused before downloading
+
+
+# ---------------------------------------------------------------------------
+# a GIF
+# ---------------------------------------------------------------------------
+
+
+async def test_a_gif_becomes_the_start_gif_and_is_sent_as_an_animation(ctx):
+    await choose(ctx, "gif")
+    ev = await send_gif(ctx)
+    assert ev.texts == ["✅ Done: /start shows this GIF from now on."]
+    (entity, file, kw), = uploads(ctx)
+    assert entity == OWNER and file.name == "start.mp4" and file.getvalue() == GIF_BYTES and kw["mime_type"] == "video/mp4"
+    video = next(a for a in kw["attributes"] if isinstance(a, types.DocumentAttributeVideo))
+    assert (video.duration, video.w, video.h, video.supports_streaming) == (3.5, 480, 270, True)
+    assert any(isinstance(a, types.DocumentAttributeAnimated) for a in kw["attributes"])
+    assert "Auto Rename Bot" in kw["caption"] and kw["buttons"]
+    meta, data = await stored(ctx)
+    assert meta == {"kind": "gif", "mime": "video/mp4", "width": 480, "height": 270, "duration": 3.5, "file_id": ""} and data == GIF_BYTES
+    assert "/start shows: <b>a GIF</b>" in (await say(ctx, OWNER, "/smedia")).texts[0]
+
+
+async def test_what_is_not_a_gif_does_not_use_up_the_request(ctx):
+    await choose(ctx, "gif")
+    for ev in (await send_photo(ctx), await send_doc(ctx, OWNER, "Episode.mkv", mid=54)):
+        assert "isn't a GIF" in ev.texts[0]
+    assert ctx.app.queue.waiting == 0 and ctx.app.modes[OWNER].data == {"kind": "gif"} and await stored(ctx) == (None, None)
+    await send_gif(ctx)
+    assert (await stored(ctx))[0]["kind"] == "gif"
+
+
+async def test_a_gif_nobody_asked_for_is_ignored(ctx):
+    ev = await send_gif(ctx)
+    assert ev.out == [] and await stored(ctx) == (None, None)
+    assert (await send_gif(ctx, sender=STRANGER)).out == []
+
+
+# ---------------------------------------------------------------------------
+# one file per request
+# ---------------------------------------------------------------------------
+
+
+async def test_extra_files_right_after_are_skipped_and_do_not_become_the_thumbnail(ctx):
+    await choose(ctx, "image")
+    await send_photo(ctx, mid=50)
+    extra = await send_photo(ctx, mid=51)
+    assert "/smedia handles one file at a time" in extra.texts[0]
+    assert (await send_photo(ctx, mid=52)).out == []  # the hint is given once
+    assert (await send_gif(ctx)).out == [] and (await send_image_file(ctx, mid=53)).out == []
+    assert len(uploads(ctx)) == 1 and not await ctx.db.has_thumb(OWNER) and ctx.app.queue.waiting == 0
+    ctx.app._recent[OWNER][1] -= appmod.ONE_SHOT_GRACE + 1
+    await send_photo(ctx, mid=54)
+    assert await ctx.db.has_thumb(OWNER)  # after the grace a photo is a thumbnail again
+
+
+# ---------------------------------------------------------------------------
+# /start
+# ---------------------------------------------------------------------------
+
+
+async def test_start_without_media_is_just_the_menu(ctx):
+    ev = await say(ctx, OWNER, "/start")
+    assert "Auto Rename Bot" in ev.texts[0] and ctx.client.files == []
+
+
+async def test_start_reuses_the_telegram_file_instead_of_uploading_again(ctx):
+    telegram_gives_ids(ctx, "FILEID-1")
+    await choose(ctx, "image")
+    await send_photo(ctx)
+    assert (await stored(ctx))[0]["file_id"] == "FILEID-1"  # remembered from the preview
+    ev = await say(ctx, ADMIN_CFG, "/start")  # every allowed user sees it
+    assert ev.out == [] and len(uploads(ctx)) == 1
+    (entity, file, kw) = ctx.client.files[-1]
+    assert entity == ADMIN_CFG and file == "FILEID-1" and "Auto Rename Bot" in kw["caption"] and "m:rename" in data_of(kw["buttons"])
+    assert "m:admin" not in data_of(kw["buttons"])
+
+
+async def test_a_stale_file_id_falls_back_to_the_stored_copy_and_is_replaced(ctx):
+    telegram_gives_ids(ctx, "FILEID-1", "FILEID-2")
+    await choose(ctx, "gif")
+    await send_gif(ctx)
+    file_ids_go_stale(ctx)
+    ev = await say(ctx, OWNER, "/start")
+    assert ev.out == []  # still shown with its picture
+    entity, file, kw = ctx.client.files[-1]
+    assert isinstance(file, io.BytesIO) and file.getvalue() == GIF_BYTES and kw["mime_type"] == "video/mp4"
+    assert (await stored(ctx))[0]["file_id"] == "FILEID-2"  # the next /start can use the fresh one
+
+
+async def test_when_nothing_can_be_sent_start_still_shows_the_menu(ctx):
+    await choose(ctx, "image")
+    await send_photo(ctx)
+    ctx.client.fail_send_file = True
+    ev = await say(ctx, OWNER, "/start")
+    assert "Auto Rename Bot" in ev.texts[0] and data_of(ev.out[0][1])[0] == "m:rename"
+
+
+async def test_damaged_saved_media_never_breaks_start(ctx):
+    for meta, data in (
+        ("not json", "AAAA"), (json.dumps({"kind": "video", "file_id": ""}), "AAAA"), (json.dumps(["kind"]), "AAAA"),
+        (json.dumps({"kind": "image", "file_id": ""}), "!!! not base64 !!!"), (json.dumps({"kind": "image", "file_id": ""}), ""),
+    ):
+        await ctx.app._store_start_media(meta, data)
+        ev = await say(ctx, OWNER, "/start")
+        assert "Auto Rename Bot" in ev.texts[0], meta
+    assert ctx.client.files == []
+
+
+async def test_the_menu_fits_in_a_caption(ctx):
+    await choose(ctx, "image")
+    await send_photo(ctx)
+    await say(ctx, OWNER, "/template " + "{title} " * 30)
+    await say(ctx, OWNER, "/start")
+    assert appmod.visible_len(ctx.client.files[-1][2]["caption"]) < 1024
+
+
+# ---------------------------------------------------------------------------
+# when Telegram refuses it, and removing it
+# ---------------------------------------------------------------------------
+
+
+async def test_a_picture_telegram_refuses_leaves_the_old_one_in_place(ctx):
+    await choose(ctx, "image")
+    first = jpeg((640, 480))
+    await send_photo(ctx, data=first)
+    before = await stored(ctx)
+    ctx.client.fail_send_file = True
+    await choose(ctx, "image")
+    ev = await send_photo(ctx, mid=55, data=jpeg((300, 300)))
+    assert "wouldn't take that" in ev.texts[0] and "nothing was changed" in ev.texts[0]
+    assert await stored(ctx) == before == ({"kind": "image", "file_id": ""}, first)
+
+
+async def test_a_picture_telegram_refuses_is_not_kept_when_there_was_none(ctx):
+    ctx.client.fail_send_file = True
+    await choose(ctx, "gif")
+    ev = await send_gif(ctx)
+    assert "wouldn't take that" in ev.texts[0] and await stored(ctx) == (None, None)
+
+
+async def test_remove_goes_back_to_the_plain_menu(ctx):
+    await choose(ctx, "image")
+    await send_photo(ctx)
+    cb = await click(ctx, OWNER, "sm:rm")
+    assert "nothing, just the menu" in cb.edits[-1][0] and data_of(cb.edits[-1][1]) == ["sm:image", "sm:gif", "x:close"]
+    assert cb.toasts == ["Start media removed."] and await stored(ctx) == (None, None)
+    count = len(ctx.client.files)
+    ev = await say(ctx, OWNER, "/start")
+    assert "Auto Rename Bot" in ev.texts[0] and len(ctx.client.files) == count

tests/test_speed.py

@@ -0,0 +1,255 @@
+import asyncio
+import json
+import os
+import shutil
+import stat
+import sys
+import time
+
+import pytest
+
+from bot import speed
+from bot.speed import SpeedError, SpeedResult
+
+CLI_RESULT = {
+    "type": "result", "timestamp": "2026-10-21T04:00:00Z",
+    "ping": {"jitter": 0.52, "latency": 4.21, "low": 3.9, "high": 5.0},
+    "download": {"bandwidth": 31_250_000, "bytes": 400_000_000, "elapsed": 12000},
+    "upload": {"bandwidth": 12_500_000, "bytes": 150_000_000, "elapsed": 11000},
+    "packetLoss": 0, "isp": "Hetzner Online GmbH",
+    "server": {"id": 1234, "host": "speed.example.net", "name": "Example Telecom", "location": "Frankfurt", "country": "Germany"},
+    "result": {"id": "abc", "url": "https://www.speedtest.net/result/c/abc"},
+}
+PY_RESULT = {
+    "download": 245_310_000.0, "upload": 118_200_000.0, "ping": 11.5, "share": "http://www.speedtest.net/result/1.png",
+    "server": {"sponsor": "Example Telecom", "name": "Frankfurt", "country": "Germany"},
+    "client": {"isp": "Hetzner Online GmbH", "ip": "1.2.3.4"},
+}
+
+
+def fake_binary(directory, name, version_text, body):
+    """An executable `name` that answers --version with ``version_text`` and anything else by running ``body`` (sh)."""
+    path = directory / name
+    path.write_text(f'#!/bin/sh\nif [ "$1" = "--version" ]; then\n  echo "{version_text}"\n  exit 0\nfi\n{body}\n')
+    path.chmod(path.stat().st_mode | stat.S_IEXEC)
+    return path
+
+
+SLEEP = shutil.which("sleep") or "/bin/sleep"  # PATH is replaced in these tests, so scripts need absolute paths
+CAT = shutil.which("cat") or "/bin/cat"
+
+
+def emit(bindir, obj):
+    """Shell line that prints ``obj`` as one JSON line (it lives in a file, so quotes inside cannot break the script)."""
+    path = bindir.parent / f"out{len(list(bindir.parent.glob('out*.json')))}.json"
+    path.write_text(json.dumps(obj) + "\n")
+    return f"{CAT} {path}"
+
+
+@pytest.fixture
+def bindir(tmp_path, monkeypatch):
+    d = tmp_path / "bin"
+    d.mkdir()
+    monkeypatch.setenv("PATH", str(d))  # only our fakes can be found
+    monkeypatch.delenv("SPEEDTEST_BIN", raising=False)
+    return d
+
+
+# ---------------------------------------------------------------------------
+# parsing
+# ---------------------------------------------------------------------------
+
+
+def test_parse_cli_converts_bytes_per_second_to_megabits():
+    r = speed.parse_cli(CLI_RESULT)
+    assert round(r.download_mbps, 2) == 250.0 and round(r.upload_mbps, 2) == 100.0
+    assert r.ping_ms == 4.21 and r.jitter_ms == 0.52 and r.packet_loss == 0
+    assert r.isp == "Hetzner Online GmbH" and r.server == "Example Telecom" and r.location == "Frankfurt, Germany"
+    assert r.url == "https://www.speedtest.net/result/c/abc" and r.source == "Ookla Speedtest CLI"
+
+
+def test_parse_cli_copes_with_missing_details_but_not_missing_speeds():
+    r = speed.parse_cli({"download": {"bandwidth": 1_000_000}, "upload": {"bandwidth": 500_000}})
+    assert r.ping_ms == 0.0 and r.jitter_ms is None and r.packet_loss is None and r.isp == "" and r.url == "" and r.location == ""
+    for broken in ({}, {"download": {"bandwidth": 1}}, {"download": {"bandwidth": "x"}, "upload": {"bandwidth": 1}}):
+        with pytest.raises(SpeedError):
+            speed.parse_cli(broken)
+
+
+def test_parse_python_converts_bits_per_second_to_megabits():
+    r = speed.parse_python(PY_RESULT)
+    assert round(r.download_mbps, 2) == 245.31 and round(r.upload_mbps, 2) == 118.2 and r.ping_ms == 11.5
+    assert r.isp == "Hetzner Online GmbH" and r.server == "Example Telecom" and r.location == "Frankfurt, Germany"
+    assert r.url.endswith("1.png") and "speedtest-cli" in r.source
+    with pytest.raises(SpeedError):
+        speed.parse_python({"ping": 3})
+
+
+def test_the_result_line_is_picked_out_of_the_cli_output():
+    out = "\n".join(["noise", json.dumps({"type": "log", "message": "x"}), json.dumps(CLI_RESULT), "", "{broken json"])
+    assert speed._last_result(out)["isp"] == "Hetzner Online GmbH"
+    assert speed._last_result("nothing useful") is None
+    assert speed._last_result(json.dumps({"type": "log", "message": "x"})) is None
+
+
+def test_the_reason_for_a_failure_comes_from_the_log_line():
+    out = json.dumps({"type": "log", "level": "error", "message": "Configuration - Couldn't resolve host name"})
+    assert speed._log_message(out, "") == "Configuration - Couldn't resolve host name"
+    assert speed._log_message("", "segmentation fault") == "segmentation fault"
+    assert speed._log_message("", "") == "no output"
+
+
+# ---------------------------------------------------------------------------
+# finding and running the CLI
+# ---------------------------------------------------------------------------
+
+
+async def test_the_official_cli_is_found_by_its_version_text(bindir):
+    assert await speed.find_ookla_cli() is None
+    fake_binary(bindir, "speedtest", "speedtest-cli 2.1.3\nPython 3.12", "exit 1")  # the pip package's script is not the CLI
+    assert await speed.find_ookla_cli() is None
+    ookla = fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84 (5ae238b) Linux/x86_64", "exit 1")
+    assert await speed.find_ookla_cli() == str(ookla)
+
+
+async def test_a_plain_speedtest_binary_is_accepted_when_it_is_the_ookla_one(bindir):
+    path = fake_binary(bindir, "speedtest", "Speedtest by Ookla 1.2.0.84", "exit 1")
+    assert await speed.find_ookla_cli() == str(path)
+
+
+async def test_the_speedtest_bin_variable_wins(bindir, tmp_path, monkeypatch):
+    other = tmp_path / "elsewhere"
+    other.mkdir()
+    chosen = fake_binary(other, "mytest", "Speedtest by Ookla 1.2.0.84", "exit 1")
+    fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", "exit 1")
+    monkeypatch.setenv("SPEEDTEST_BIN", str(chosen))
+    assert await speed.find_ookla_cli() == str(chosen)
+
+
+async def test_run_cli_returns_the_parsed_result(bindir):
+    path = fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", emit(bindir, CLI_RESULT))
+    r = await speed.run_cli(str(path))
+    assert round(r.download_mbps) == 250 and r.server == "Example Telecom"
+
+
+async def test_run_cli_passes_the_flags_that_make_it_non_interactive(bindir, tmp_path):
+    args_file = tmp_path / "args.txt"
+    path = fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", f'echo "$@" > {args_file}\n{emit(bindir, CLI_RESULT)}')
+    await speed.run_cli(str(path))
+    args = args_file.read_text().split()
+    assert "--accept-license" in args and "--accept-gdpr" in args and "--format=json" in args
+
+
+async def test_run_cli_reports_why_it_failed(bindir):
+    log = {"type": "log", "level": "error", "message": "Configuration - Couldn't resolve host name"}
+    path = fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", f"{emit(bindir, log)}\nexit 1")
+    with pytest.raises(SpeedError, match="Couldn't resolve host name"):
+        await speed.run_cli(str(path))
+
+
+async def test_run_cli_gives_up_after_the_timeout_and_kills_the_process(bindir, tmp_path):
+    pid_file = tmp_path / "pid"
+    path = fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", f"echo $$ > {pid_file}\nexec {SLEEP} 30")
+    started = time.monotonic()
+    with pytest.raises(SpeedError, match="took too long"):
+        await speed.run_cli(str(path), timeout=0.5)
+    assert time.monotonic() - started < 5
+    pid = int(pid_file.read_text())
+    await asyncio.sleep(0.2)
+    with pytest.raises(ProcessLookupError):
+        os.kill(pid, 0)
+
+
+async def test_a_binary_that_cannot_start_is_a_speed_error(tmp_path):
+    broken = tmp_path / "broken"
+    broken.write_text("not executable")
+    with pytest.raises(SpeedError):
+        await speed.run_cli(str(broken))
+
+
+# ---------------------------------------------------------------------------
+# run_speedtest: CLI first, Python client second
+# ---------------------------------------------------------------------------
+
+
+async def test_the_cli_is_used_when_it_works(bindir, monkeypatch):
+    fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", emit(bindir, CLI_RESULT))
+
+    def boom():
+        raise AssertionError("the Python client is not needed")
+
+    monkeypatch.setattr(speed, "_run_python", boom)
+    r = await speed.run_speedtest()
+    assert r.source == "Ookla Speedtest CLI"
+
+
+async def test_the_python_client_takes_over_when_the_cli_is_missing(bindir, monkeypatch):
+    monkeypatch.setattr(speed, "_run_python", lambda: PY_RESULT)
+    r = await speed.run_speedtest()
+    assert "speedtest-cli" in r.source and round(r.download_mbps) == 245
+
+
+async def test_the_python_client_takes_over_when_the_cli_fails(bindir, monkeypatch):
+    fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", "exit 1")
+    monkeypatch.setattr(speed, "_run_python", lambda: PY_RESULT)
+    assert "speedtest-cli" in (await speed.run_speedtest()).source
+
+
+async def test_when_both_fail_the_reasons_are_all_given(bindir, monkeypatch):
+    fake_binary(bindir, "ookla-speedtest", "Speedtest by Ookla 1.2.0.84", "echo 'server unreachable'\nexit 1")
+
+    def failing():
+        raise SpeedError("speedtest-cli failed: HTTP Error 403: Forbidden")
+
+    monkeypatch.setattr(speed, "_run_python", failing)
+    with pytest.raises(SpeedError) as exc:
+        await speed.run_speedtest()
+    assert "server unreachable" in str(exc.value) and "403" in str(exc.value)
+
+
+async def test_a_missing_python_client_is_explained(bindir, monkeypatch):
+    monkeypatch.setitem(sys.modules, "speedtest", None)  # makes `import speedtest` fail, installed or not
+    with pytest.raises(SpeedError) as exc:
+        await speed.run_speedtest()
+    assert "Speedtest CLI is not installed" in str(exc.value) and "speedtest-cli package is not installed" in str(exc.value)
+
+
+async def test_errors_from_the_python_client_are_wrapped(bindir, monkeypatch):
+    class FakeSpeedtest:
+        def __init__(self, *a, **kw):
+            raise RuntimeError("HTTP Error 403: Forbidden")
+
+    monkeypatch.setitem(sys.modules, "speedtest", type(sys)("speedtest"))
+    sys.modules["speedtest"].Speedtest = FakeSpeedtest
+    with pytest.raises(SpeedError, match="speedtest-cli failed: HTTP Error 403"):
+        await speed.run_speedtest()
+
+
+async def test_a_python_client_that_hangs_is_given_up_on(bindir, monkeypatch):
+    monkeypatch.setattr(speed, "CLI_TIMEOUT", 0.1)
+    monkeypatch.setattr(speed, "_run_python", lambda: time.sleep(0.4) or PY_RESULT)
+    with pytest.raises(SpeedError, match="took too long"):
+        await speed.run_speedtest()
+
+
+# ---------------------------------------------------------------------------
+# the message
+# ---------------------------------------------------------------------------
+
+
+def test_format_result_lists_every_detail():
+    text = speed.format_result(speed.parse_cli(CLI_RESULT))
+    assert "SPEEDTEST" in text and "Ookla" in text
+    assert "<code>250.00 Mbps</code>" in text and "<code>100.00 Mbps</code>" in text
+    assert "<code>4.21 ms</code>" in text and "jitter <code>0.52 ms</code>" in text and "<code>0%</code>" in text
+    assert "Hetzner Online GmbH" in text and "Example Telecom · Frankfurt, Germany" in text
+    assert '<a href="https://www.speedtest.net/result/c/abc">speedtest.net</a>' in text
+
+
+def test_format_result_skips_what_is_unknown_and_escapes_the_rest():
+    r = SpeedResult(download_mbps=1234.5, upload_mbps=2.0, ping_ms=30, isp="A&B <ISP>", server="", location="", url="javascript:alert(1)")
+    text = speed.format_result(r)
+    assert "<code>1,234.50 Mbps</code>" in text and "A&amp;B &lt;ISP&gt;" in text
+    assert "Server" not in text and "Packet loss" not in text and "jitter" not in text and "<a " not in text
+    quoted = SpeedResult(download_mbps=1, upload_mbps=1, ping_ms=1, url='https://x.test/a"b')
+    assert 'href="https://x.test/a&quot;b"' in speed.format_result(quoted)

tests/test_speed_app.py

@@ -0,0 +1,83 @@
+"""/speed: the command around the speed test."""
+import asyncio
+
+from bot import app as appmod
+from bot import speed
+from bot.speed import SpeedResult
+
+from .appkit import ADMIN_CFG, OWNER, STRANGER, say
+
+RESULT = SpeedResult(
+    download_mbps=250.0, upload_mbps=100.0, ping_ms=4.2, jitter_ms=0.5, packet_loss=0.0, isp="Hetzner",
+    server="Example Telecom", location="Frankfurt, Germany", url="https://www.speedtest.net/result/c/abc", source="Ookla Speedtest CLI",
+)
+
+
+def serve(monkeypatch, result=RESULT, error=None, gate=None):
+    calls = []
+
+    async def fake():
+        calls.append(1)
+        if gate is not None:
+            await gate.wait()
+        if error is not None:
+            raise error
+        return result
+
+    monkeypatch.setattr(speed, "run_speedtest", fake)
+    return calls
+
+
+async def test_speed_shows_a_status_and_then_the_figures(ctx, monkeypatch):
+    calls = serve(monkeypatch)
+    ev = await say(ctx, OWNER, "/speed")
+    assert ev.texts == ["⚡ Running the speed test… this takes about half a minute."]
+    (status, text, kw), = ctx.client.edited
+    assert status.id == 1001 and kw["parse_mode"] == "html" and kw["link_preview"] is False
+    assert "SPEEDTEST" in text and "250.00 Mbps" in text and "100.00 Mbps" in text and "speedtest.net/result/c/abc" in text
+    assert len(calls) == 1 and "may be lower" not in text
+
+
+async def test_a_failed_test_says_why(ctx, monkeypatch):
+    serve(monkeypatch, error=speed.SpeedError("the Speedtest CLI is not installed; the speedtest-cli package is not installed <x>"))
+    await say(ctx, OWNER, "/speed")
+    text = ctx.client.edited[-1][1]
+    assert text.startswith("❌ I couldn't run the speed test: the Speedtest CLI is not installed") and "&lt;x&gt;" in text
+
+
+async def test_an_unexpected_crash_is_reported_and_does_not_leave_the_lock_taken(ctx, monkeypatch):
+    serve(monkeypatch, error=RuntimeError("boom"))
+    await say(ctx, OWNER, "/speed")
+    assert "failed unexpectedly" in ctx.client.edited[-1][1]
+    serve(monkeypatch)
+    await say(ctx, OWNER, "/speed")
+    assert "250.00 Mbps" in ctx.client.edited[-1][1]
+
+
+async def test_only_one_test_runs_at_a_time(ctx, monkeypatch):
+    gate = asyncio.Event()
+    calls = serve(monkeypatch, gate=gate)
+    first = asyncio.ensure_future(say(ctx, OWNER, "/speed"))
+    await asyncio.sleep(0.05)
+    second = await say(ctx, ADMIN_CFG, "/speed")
+    assert "already running" in second.texts[0] and len(calls) == 1
+    gate.set()
+    await first
+    assert "250.00 Mbps" in ctx.client.edited[-1][1]
+    again = await say(ctx, ADMIN_CFG, "/speed")  # free again
+    assert again.texts[0].startswith("⚡")
+
+
+async def test_the_result_mentions_a_running_job(ctx, monkeypatch):
+    serve(monkeypatch)
+    await say(ctx, OWNER, "/speed")
+    assert "A rename job was running" not in ctx.client.edited[-1][1]
+    monkeypatch.setattr(type(ctx.app.queue), "running", property(lambda self: 1))
+    await say(ctx, OWNER, "/speed")
+    assert "A rename job was running during the test" in ctx.client.edited[-1][1]
+
+
+async def test_strangers_cannot_run_it_and_it_is_in_the_menu(ctx, monkeypatch):
+    calls = serve(monkeypatch)
+    assert (await say(ctx, STRANGER, "/speed")).out == [] and calls == []
+    assert "speed" in dict(appmod.COMMANDS)

tests/test_telegraph.py

@@ -0,0 +1,157 @@
+"""The Telegraph client, against a local server that answers like api.telegra.ph."""
+import asyncio
+import json
+
+import pytest
+
+from bot import telegraph
+from bot.telegraph import Telegraph, TelegraphError
+
+from .faketelegraph import serve_fake_telegraph
+
+NODES = [{"tag": "h4", "children": ["General"]}, {"tag": "pre", "children": ["Format : Matroska"]}]
+
+
+@pytest.fixture
+async def server():
+    fake = await serve_fake_telegraph()
+    yield fake
+    await fake.server.close()
+
+
+def make(server, store=None, **kw):
+    store = {} if store is None else store
+
+    async def load():
+        return store.get("token")
+
+    async def save(token):
+        store["token"] = token
+
+    return Telegraph(load, save, api=server.url, **kw), store
+
+
+# ---------------------------------------------------------------------------
+
+
+async def test_the_first_page_makes_an_account_and_remembers_its_token(server):
+    tg, store = make(server)
+    url = await tg.create_page("MediaInfo – Episode 01.mkv", NODES)
+    assert url == "https://telegra.ph/Page-1"
+    assert server.accounts == 1 and store == {"token": "token1"}
+    form = server.pages[0]
+    assert form["access_token"] == "token1" and form["title"] == "MediaInfo – Episode 01.mkv"
+    assert form["author_name"] == "Auto Rename Bot" and form["return_content"] == "false" and "author_url" not in form
+    assert json.loads(form["content"]) == NODES
+
+
+async def test_later_pages_use_the_same_account(server):
+    tg, store = make(server)
+    await tg.create_page("one", NODES)
+    await tg.create_page("two", NODES)
+    assert server.accounts == 1 and [p["access_token"] for p in server.pages] == ["token1", "token1"]
+
+
+async def test_a_token_saved_by_an_earlier_run_is_used_without_a_new_account(server):
+    server.valid.add("kept")
+    tg, store = make(server, {"token": "kept"})
+    await tg.create_page("x", NODES)
+    assert server.accounts == 0 and server.pages[0]["access_token"] == "kept"
+
+
+async def test_a_rejected_token_is_replaced_once_and_the_page_still_gets_made(server):
+    tg, store = make(server, {"token": "stale"})
+    url = await tg.create_page("x", NODES)
+    assert url == "https://telegra.ph/Page-1"
+    assert server.accounts == 1 and store == {"token": "token1"}
+    assert [a["access_token"] for a in server.attempts] == ["stale", "token1"]
+
+
+async def test_a_token_that_is_rejected_again_is_an_error(server):
+    server.reject_all = True
+    tg, store = make(server, {"token": "stale"})
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", NODES)
+    assert err.value.code == "ACCESS_TOKEN_INVALID" and server.accounts == 1 and len(server.attempts) == 2
+
+
+async def test_the_first_use_from_several_places_makes_one_account(server):
+    tg, _store = make(server)
+    urls = await asyncio.gather(*(tg.create_page(f"p{i}", NODES) for i in range(6)))
+    assert server.accounts == 1 and len(set(urls)) == 6
+
+
+async def test_a_flood_wait_says_how_long(server):
+    server.error = "FLOOD_WAIT_7"
+    tg, _store = make(server)
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", NODES)
+    assert str(err.value) == "Telegraph asks to wait 7 seconds" and err.value.code == "FLOOD_WAIT_7"
+
+
+async def test_other_errors_keep_their_code(server):
+    server.error = "PAGE_SAVE_FAILED"
+    tg, _store = make(server)
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", NODES)
+    assert str(err.value) == "Telegraph said PAGE_SAVE_FAILED" and err.value.code == "PAGE_SAVE_FAILED"
+
+
+async def test_a_page_over_the_size_limit_is_not_even_sent(server):
+    tg, _store = make(server)
+    big = [{"tag": "pre", "children": ["x" * 70_000]}]
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", big)
+    assert err.value.code == "CONTENT_TOO_BIG" and server.attempts == [] and server.accounts == 0
+
+
+async def test_an_answer_that_is_not_json_is_an_error(server):
+    server.raw = (502, "<html>Bad gateway</html>")
+    tg, _store = make(server)
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", NODES)
+    assert "couldn't reach Telegraph" in str(err.value)
+
+
+async def test_a_slow_server_times_out(server):
+    server.delay = 1.0
+    tg, _store = make(server, timeout=0.2)
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", NODES)
+    assert "too long" in str(err.value)
+
+
+async def test_an_unreachable_server_is_an_error():
+    async def load():
+        return "token"
+
+    async def save(token):
+        pass
+
+    tg = Telegraph(load, save, api="http://127.0.0.1:9", timeout=2)  # nothing listens on the discard port
+    with pytest.raises(TelegraphError) as err:
+        await tg.create_page("x", NODES)
+    assert "couldn't reach Telegraph" in str(err.value)
+
+
+async def test_the_author_and_its_link_are_sent_and_kept_within_telegraphs_limits(server):
+    tg, _store = make(server)
+    tg.set_author("Anime Rename Bot", "https://t.me/rename_bot")
+    await tg.create_page("x", NODES)
+    assert server.pages[0]["author_name"] == "Anime Rename Bot" and server.pages[0]["author_url"] == "https://t.me/rename_bot"
+    tg.set_author("N" * 300)
+    tg.set_author("   ")  # a blank name changes nothing
+    await tg.create_page("y", NODES)
+    assert server.pages[1]["author_name"] == "N" * 128 and "author_url" not in server.pages[1]  # no link was given this time
+
+
+async def test_titles_are_never_empty_or_too_long(server):
+    tg, _store = make(server)
+    await tg.create_page("   ", NODES)
+    await tg.create_page("T" * 400, NODES)
+    assert server.pages[0]["title"] == "MediaInfo" and len(server.pages[1]["title"]) == 256
+
+
+def test_content_size_counts_bytes_not_characters():
+    nodes = [{"tag": "p", "children": ["日本語"]}]
+    assert telegraph.content_size(nodes) == len(json.dumps(nodes, ensure_ascii=False, separators=(",", ":")).encode()) > len("日本語")

tests/tgfakes.py

@@ -14,24 +14,27 @@ 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:
+              ext: Optional[str] = None, *, width: Optional[int] = None, height: Optional[int] = None,
+              duration: Optional[float] = 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)
+    return SimpleNamespace(name=name, size=size, mime_type=mime, ext=ext, width=width, height=height, duration=duration)
 
 
 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):
+                 voice: bool = False, video_note: bool = False, fwd: bool = False, out: bool = False,
+                 entities: Any = None, thumbs: Any = None):
         self.id = mid
         self.message = text
         self.raw_text = text
+        self.entities = entities
         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.document = SimpleNamespace(thumbs=thumbs) 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
@@ -43,8 +46,8 @@ class FakeMessage:
 
 
 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)
+                     video: bool = True, mime: str = "video/x-matroska", thumbs: Any = None) -> FakeMessage:
+    return FakeMessage(caption, mid=mid, file=make_file(name, size, mime), video=video, thumbs=thumbs)
 
 
 class FakeEvent:
@@ -135,6 +138,13 @@ class FakeClient:
         self.requests: List[Any] = []   # raw MTProto requests
         self.bad_entities: set = set()
         self.fail_send_file = False
+        self.messages: dict = {}        # id -> message that get_messages() can find (a missing id comes back as None)
+        self.deleted: List[tuple] = []  # delete_messages(entity, ids)
+        self.file_errors: dict = {}     # message id -> exceptions send_file() raises for it, one per call
+        self.get_calls: List[tuple] = []
+        self.media: dict = {}           # message id -> bytes that download_media() returns
+        self.thumb_data: dict = {}      # message id -> bytes that download_media(thumb=...) returns
+        self.downloads: List[tuple] = []
 
     def add_event_handler(self, callback: Any, event: Any = None) -> None:
         self.handlers.append((callback, event))
@@ -152,9 +162,26 @@ class FakeClient:
         self.sent.append((entity, text, kw))
         return SimpleNamespace(id=2000 + len(self.sent))
 
+    async def get_messages(self, entity: Any, ids: Any = None, **kw: Any) -> Any:
+        self.get_calls.append((entity, ids))
+        if isinstance(ids, (list, tuple)):
+            return [self.messages.get(i) for i in ids]
+        return self.messages.get(ids)
+
+    async def download_media(self, message: Any, file: Any = None, thumb: Any = None, **kw: Any) -> Any:
+        self.downloads.append((getattr(message, "id", None), file, thumb))
+        source = self.thumb_data if thumb is not None else self.media
+        return source.get(getattr(message, "id", None))
+
+    async def delete_messages(self, entity: Any, ids: Any, **kw: Any) -> None:
+        self.deleted.append((entity, list(ids) if isinstance(ids, (list, tuple)) else [ids]))
+
     async def send_file(self, entity: Any, file: Any, **kw: Any) -> SimpleNamespace:
         if self.fail_send_file:
             raise RuntimeError("cannot send file")
+        errors_for = self.file_errors.get(getattr(file, "id", None))
+        if errors_for:
+            raise errors_for.pop(0)
         self.files.append((entity, file, kw))
         return SimpleNamespace(id=3000 + len(self.files))