راهنمای استفاده

رابط وب

رابط وب WZML-X چه کارهایی می‌کند؛ انتخاب فایل تورنت و NZB با پین، صفحه‌های پخش آنلاین، پنل‌های qBittorrent و SABnzbd، و نقش BASE_URL و تونل Cloudflare.

ربات در کنار خودش یک وب‌سرور کوچک اجرا می‌کند (برنامهٔ FastAPI در web/wserver.py که با gunicorn اجرا می‌شود). این وب‌سرور روی پورت متغیر محیطی PORT یا در نبود آن روی 8080 گوش می‌دهد و صفحه‌هایش از قالب‌های پوشهٔ web/templates ساخته می‌شوند.

`BASE_URL` و تونل

BASE_URL آدرس عمومی همین رابط وب است و ربات با آن لینک‌هایی را می‌سازد که برایتان می‌فرستد.

با Docker Compose: لازم نیست کاری بکنید. کانتینر tunnel با Cloudflare یک آدرس https://….trycloudflare.com می‌سازد و آن را در یک فایل مشترک می‌نویسد؛ ربات هنگام شروع و بعد از آن هر ۵ ثانیه این فایل را می‌خواند و BASE_URL را به‌روز می‌کند.
بدون تونل (تک‌کانتینری، Heroku یا تونل نام‌دار): BASE_URL را خودتان در config.py یا از /bsetting تنظیم کنید.

مسیرهای اصلی رابط وب:

مسیر	کاربرد
`/`	صفحهٔ معرفی با لینک کانال، گروه پشتیبانی و مخزن
`/app/files?gid=…`	صفحهٔ انتخاب فایل تورنت و NZB
`/xstrm/<token>`	صفحهٔ پخش آنلاین
`/dl/<token>`	دانلود مستقیم فایل
`/playlist/<token>`	صفحهٔ فهرست پخش (چند فایل)
`/m3u/<token>`	فایل فهرست پخش M3U برای پخش‌کننده‌های دیگر
`/qbit/` و `/nzb/`	پنل وب qBittorrent و SABnzbd (با رمز)

انتخاب فایل تورنت و NZB

وقتی یک تورنت یا NZB شامل چندین فایل است، می‌توانید قبل از دانلود فقط فایل‌هایی را که لازم دارید انتخاب کنید. این کار با Aria2، qBittorrent و SABnzbd کار می‌کند.

مراحل

کار را با آرگومان -s (آرگومان‌ها) شروع کنید، مثلاً /qbleech <magnet> -s یا /mirror <magnet> -s (در هر دستوری که تورنت یا NZB می‌پذیرد).

اگر کار قبلاً شروع شده و هنوز در مرحلهٔ دانلود، توقف یا صف است، روی پیام همان دستور با /select (کوتاه‌شده: /sel) ریپلای کنید، یا شناسهٔ کار (GID) را بعد از دستور بنویسید.
ربات دانلود را متوقف می‌کند و پیامی با این دکمه‌ها می‌فرستد: Select Files، Pincode (اگر WEB_PINCODE روشن باشد)، Done Selecting و Cancel. برای مگنت‌ها در qBittorrent، ربات اول منتظر دریافت متادیتا می‌ماند (Fetching Metadata...)؛ استفاده از فایل .torrent این انتظار را حذف می‌کند.
دکمهٔ Pincode را بزنید تا پین ۴ رقمی را ببینید، بعد Select Files را باز کنید و پین را وارد کنید (Unlock files). اگر WEB_PINCODE خاموش باشد، پین داخل خود لینک است و صفحه مستقیم باز می‌شود.
در صفحهٔ باز شده فایل‌ها را در ساختار پوشه‌ای می‌بینید. می‌توانید جست‌وجو کنید (Search files...)، بر اساس نام یا اندازه مرتب کنید و با دکمه‌های This folder، All files و Invert سریع انتخاب کنید. تعداد و حجم انتخاب‌شده بالای صفحه نمایش داده می‌شود. در آخر Submit selection را بزنید.
به تلگرام برگردید و Done Selecting را بزنید تا دانلود با فایل‌های انتخاب‌شده شروع شود. برای تورنت‌ها، ربات فایل‌های انتخاب‌نشده‌ای را که روی دیسک مانده‌اند پاک می‌کند و محدودیت‌های حجم را دوباره با حجم جدید بررسی می‌کند.

نکته‌ها

تغییر نام: فقط برای تورنت‌های qBittorrent، می‌توانید نام فایل‌ها و پوشه‌ها را از همین صفحه عوض کنید. برای Aria2 پیام Cannot rename aria2c torrent file را می‌گیرید.
فقط صاحب کار: دکمه‌های پیام انتخاب فقط برای کسی کار می‌کنند که کار را شروع کرده است (This task is not for you!).
مینی‌اپ: در چت خصوصی با ربات، اگر BASE_URL با https:// شروع شود، Select Files به‌شکل مینی‌اپ داخل خود تلگرام باز می‌شود؛ در غیر این صورت لینک معمولی است.
بدون BASE_URL: دستور /select پاسخ Base URL not defined! می‌دهد و انتخاب فایل از طریق وب انجام نمی‌شود.

پین و `WEB_PINCODE`

پین یک عدد ۴ رقمی است که از شناسهٔ کار و شناسهٔ ربات ساخته می‌شود؛ پس هر کار پین خودش را دارد.

WEB_PINCODE = True (پیش‌فرض): لینک Select Files پین ندارد و پین با دکمهٔ جداگانهٔ Pincode نشان داده می‌شود. کسی که فقط لینک را داشته باشد، بدون پین نمی‌تواند فایل‌ها را ببیند.
WEB_PINCODE = False: پین داخل خود لینک قرار می‌گیرد و صفحه بلافاصله باز می‌شود. راحت‌تر است، اما هر کس لینک را داشته باشد می‌تواند انتخاب را تغییر دهد.

برای جلوگیری از حدس زدن، اگر برای یک کار ۵ بار پین اشتباه در ۶۰ ثانیه وارد شود، صفحه پیام Too many PIN attempts. Try again in 60s. را نشان می‌دهد.

پخش آنلاین (استریم)

ربات می‌تواند برای فایل‌های تلگرام لینک پخش در مرورگر و لینک دانلود مستقیم بسازد. پخش از طریق یک سرور جدا انجام می‌شود که داخل کانتینر روی 127.0.0.1:8091 اجرا می‌شود (قابل تغییر با متغیر محیطی STREAM_PORT) و رابط وب درخواست‌ها را به آن می‌رساند.

پیش‌نیازها

DISABLE_STREAM خاموش باشد (در Module Settings ← On/Off Settings گزینهٔ STREAM).
STREAM_TOKENS یا HELPER_TOKENS تنظیم شده باشد؛ وگرنه ربات می‌گوید No streaming clients are running. اگر STREAM_TOKENS داشته باشید، پخش فقط از آن ربات‌ها استفاده می‌کند و از بار میرور و لیچ جدا می‌ماند.
BASE_URL تنظیم شده باشد.
DATABASE_URL تنظیم شده باشد؛ لینک‌های پخش در MongoDB ذخیره می‌شوند.

دستور `/stream`

دستور /stream (کوتاه‌شده: /sl) برای همهٔ کاربران مجاز فعال است:

کاربرد	شکل دستور
یک فایل	روی فایل ریپلای کنید، یا لینک پیام تلگرام را بدهید: `/stream [link]`
چند پیام پشت سر هم	`/stream [link]-[last id]` (حداکثر ۵۰ پیام)
یک صفحهٔ فهرست پخش	`/stream -pl [name] [link range]`
چند تکه به‌صورت یک ویدیوی پیوسته	`/stream -m [name] [link range]`
با تصویر کاور	`/stream -t [photo link] [link]`
لینک با تاریخ انقضا	`/stream -ttl [1d2h3m] [link]`
حذف لینک (فقط مالک و سودو)	`/stream [stream or playlist link] -d`

این الگوها همان‌هایی هستند که خود ربات با فرستادن /stream بدون ورودی نشان می‌دهد.

آرگومان -m در /stream ربطی به -m در /mirror و /leech ندارد. برای حالت ادغام، همهٔ تکه‌ها باید صوتی یا تصویری و دارای مدت زمان باشند؛ وگرنه ربات پیشنهاد می‌کند از -pl استفاده کنید.

اگر LEECH_LOG_CHAT تنظیم شده باشد، ربات قبل از ساختن لینک یک کپی از پیام را در آن چت می‌گذارد و لینک از روی آن کپی کار می‌کند.

لینک‌های خودکار بعد از لیچ

اگر MEDIA_STORE روشن باشد و لیچ در یک سوپرگروه انجام شود یا LEECH_LOG_CHAT تنظیم شده باشد، در پیام پایان کار، کنار هر فایل علاوه بر Store Link یک خط Direct → Stream | Download هم می‌آید (به شرط داشتن BASE_URL).

صفحهٔ پخش

صفحهٔ /xstrm/… یک پخش‌کنندهٔ داخل مرورگر دارد که می‌تواند از جای قبلی ادامه دهد یا از اول پخش کند، دکمهٔ دانلود دارد و می‌تواند فایل را در پخش‌کننده‌های بیرونی مثل VLC، MX Player، nPlayer، PotPlayer یا Kodi (بسته به دستگاه) باز کند. برای فهرست‌های پخش، فایل M3U هم در دسترس است.

اگر سرور پخش خاموش باشد، این صفحه‌ها خطای Streaming is disabled or the stream service is not running. برمی‌گردانند.

پنل qBittorrent و SABnzbd

رابط وب، پنل وب qBittorrent و SABnzbd داخل کانتینر را هم از مسیرهای /qbit/ و /nzb/ در دسترس قرار می‌دهد. این مسیرها رمز دارند؛ آدرس کامل همراه با رمز هنگام شروع در لاگ ربات چاپ می‌شود:

docker compose logs app | grep "Web UI"

خروجی شبیه Web UI: qBittorrent: /qbit/?pass=… است؛ آن را به انتهای آدرس رابط وب (BASE_URL) اضافه کنید. بعد از اولین ورود موفق، رمز در یک کوکی ذخیره می‌شود. با رمز اشتباه، خطای Unauthorized access می‌گیرید.

این رمزها از WEB_ACCESS_PASSWORD (مرجع متغیرها) و شناسهٔ ربات ساخته می‌شوند. اگر WEB_ACCESS_PASSWORD را خالی بگذارید، ربات خودش یک مقدار تصادفی می‌سازد.