From f69246c43d9df0d2f50f69e8c13b75d9c4a2a954 Mon Sep 17 00:00:00 2001 From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:43:14 +0000 Subject: [PATCH 1/6] docs: add user-friendly Furo documentation site Co-authored-by: Karan Adhikari <113664541+weebzone@users.noreply.github.com> --- docs/.gitignore | 5 + docs/_static/custom.css | 21 ++++ docs/admin-panel.md | 97 ++++++++++++++++ docs/api-reference.md | 120 ++++++++++++++++++++ docs/catalogs.md | 103 +++++++++++++++++ docs/changelog.md | 40 +++++++ docs/conf.py | 71 ++++++++++++ docs/configuration.md | 180 ++++++++++++++++++++++++++++++ docs/contributing.md | 51 +++++++++ docs/credits.md | 43 +++++++ docs/deployment.md | 128 +++++++++++++++++++++ docs/faq.md | 52 +++++++++ docs/getting-started.md | 188 +++++++++++++++++++++++++++++++ docs/index.md | 130 ++++++++++++++++++++++ docs/license.md | 25 +++++ docs/media-management.md | 234 +++++++++++++++++++++++++++++++++++++++ docs/requirements.txt | 7 ++ docs/search.md | 40 +++++++ docs/streaming.md | 88 +++++++++++++++ docs/support.md | 35 ++++++ docs/themes.md | 64 +++++++++++ docs/tips.md | 68 ++++++++++++ docs/troubleshooting.md | 93 ++++++++++++++++ docs/updating.md | 73 ++++++++++++ docs/user-management.md | 128 +++++++++++++++++++++ 25 files changed, 2084 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/_static/custom.css create mode 100644 docs/admin-panel.md create mode 100644 docs/api-reference.md create mode 100644 docs/catalogs.md create mode 100644 docs/changelog.md create mode 100644 docs/conf.py create mode 100644 docs/configuration.md create mode 100644 docs/contributing.md create mode 100644 docs/credits.md create mode 100644 docs/deployment.md create mode 100644 docs/faq.md create mode 100644 docs/getting-started.md create mode 100644 docs/index.md create mode 100644 docs/license.md create mode 100644 docs/media-management.md create mode 100644 docs/requirements.txt create mode 100644 docs/search.md create mode 100644 docs/streaming.md create mode 100644 docs/support.md create mode 100644 docs/themes.md create mode 100644 docs/tips.md create mode 100644 docs/troubleshooting.md create mode 100644 docs/updating.md create mode 100644 docs/user-management.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..b096d911 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,5 @@ +# Sphinx build output +_build/ + +# Local virtual environment used to build the docs +.venv/ diff --git a/docs/_static/custom.css b/docs/_static/custom.css new file mode 100644 index 00000000..93794ad3 --- /dev/null +++ b/docs/_static/custom.css @@ -0,0 +1,21 @@ +/* Small visual tweaks on top of the Furo theme. */ + +/* Make callout boxes a touch more prominent. */ +.admonition { + border-radius: 8px; +} + +/* Nicer tables that stretch to full width. */ +table.docutils { + width: 100%; +} + +/* Slightly rounder code blocks. */ +div.highlight { + border-radius: 8px; +} + +/* Emoji-friendly headings keep their spacing. */ +h1, h2, h3 { + scroll-margin-top: 1.5rem; +} diff --git a/docs/admin-panel.md b/docs/admin-panel.md new file mode 100644 index 00000000..5b6a57a1 --- /dev/null +++ b/docs/admin-panel.md @@ -0,0 +1,97 @@ +# Admin Panel + +The web admin panel is your control center — no command line needed for daily tasks. Log +in at `/login` (default `admin` / `admin`, which you should change immediately). + +```{admonition} Beginner Tip +:class: tip +Almost everything you'd ever want to do lives here as a button or form. The old bot +commands for stats, logs, scanning, and restarting have all moved into this panel. +``` + +## Dashboard + +Your landing page after login. Shows an at-a-glance overview of your library and system — +counts, recent activity, and quick links to the main sections. + +## Media Library + +Under **Media Management** you can browse **Movies** and **TV Shows**, search, and page +through everything. For each title you can: + +- **Edit** its details or **Scan Metadata** to fix a wrong match. +- Delete a single **quality**, **episode**, **season**, or the whole title. +- **Manually add** custom movies, shows, seasons, episodes, or extra qualities. + +See {doc}`media-management` for the details. + +## Catalogs + +Create and manage **custom catalogs**, set their **visibility**, and configure which +**automatic catalogs** are enabled. See {doc}`catalogs`. + +## Users & Access + +**Access Management** and **Subscription Management** let you handle tokens, plans, and +subscribers. See {doc}`user-management`. + +## Content Requests + +A public **request page** (`/request`) lets viewers ask for titles. Admins review incoming +requests under **Admin → Requests**, and can approve, update, or delete them. Fulfilled +requests can notify the requester automatically. + +## Analytics + +See live and recent **streaming stats** — active streams, throughput, and history — plus +tools to clear analytics. Helpful for spotting heavy usage or dead content. + +## Health Dashboard + +A **Health** report checks that your key pieces — Telegram connection, databases, +streaming — are responsive. Use it as your first stop when something feels off. + +## Tools + +The **Tools** page replaces the old scanning bot commands: + +- **Scan** a channel to index existing files (start / cancel / view status). +- **DB Check** to verify database integrity (start / cancel / status). +- **Dead Links** detection and purge, to clean up entries whose Telegram files are gone. + +```{admonition} Good to Know +:class: note +A **scan** is how you import files that were already in a channel *before* you set up the +bot. New uploads are indexed automatically without scanning. +``` + +## Settings + +The full configuration page (`/admin/settings`) — general options, admin login, media +keys, subscriptions, proxy, extra databases, and multi-token clients. Everything here is +applied instantly. See {doc}`configuration`. + +## Backup & Restore + +From Settings you can **export** your configuration to a JSON file and **import** it later +— useful before migrating servers or making big changes. See {doc}`updating`. + +## Bot commands + +A few things still live in the Telegram bot itself: + +```{list-table} +:header-rows: 1 +:widths: 20 80 + +* - Command + - What it does +* - `/start` + - Returns your **addon URL** (or the subscription flow, if enabled) +* - `/set ` + - Sets a metadata override for the files you upload next; send `/set` alone to clear it +* - `/log` + - Sends the latest log file for debugging +* - `/restart` + - Restarts the bot and pulls the latest updates from your upstream repo +``` diff --git a/docs/api-reference.md b/docs/api-reference.md new file mode 100644 index 00000000..19aac14d --- /dev/null +++ b/docs/api-reference.md @@ -0,0 +1,120 @@ +# API Reference + +This page documents the HTTP endpoints your server exposes. Most users never touch these +directly — Stremio calls them for you — but they're useful for debugging and integrations. + +```{admonition} Beginner Tip +:class: tip +You don't need to understand this page to use the app. It's here for the curious and for +developers building on top of it. +``` + +## Authentication + +There are two kinds of protected routes: + +**Addon token** (`{token}` in the URL) +: Every Stremio-facing route is scoped to a per-user token, e.g. + `/stremio/{token}/manifest.json`. Invalid or expired tokens are rejected (or shown a + subscription prompt). + +**Admin session** (web panel) +: All `/api/admin/**` and management routes require you to be logged into the web panel. + Unauthenticated requests are redirected to `/login`. + +## Stremio addon endpoints + +These follow the standard Stremio addon protocol. + +```{list-table} +:header-rows: 1 +:widths: 55 45 + +* - Endpoint + - Purpose +* - `GET /stremio/{token}/manifest.json` + - The addon manifest — declares catalogs and capabilities for this user +* - `GET /stremio/{token}/catalog/{media_type}/{id}.json` + - A catalog listing (latest / popular / custom) +* - `GET /stremio/{token}/catalog/{media_type}/{id}/{extra}.json` + - Same, with extra filters (genre, search, skip/pagination) +* - `GET /stremio/{token}/meta/{media_type}/{id}.json` + - Detailed metadata for one title, including the episode list for series +* - `GET /stremio/{token}/subtitles/{media_type}/{id}.json` + - Subtitles for a title/episode, sourced from subtitle files in your channels +``` + +### The manifest + +The manifest is **dynamic per user**. Its name and description reflect subscription state +(e.g. `Telegram — Expires 28 Mar 2026`), and its version encodes the expiry so Stremio +detects updates when you change a subscription. + +## Streaming endpoints + +```{list-table} +:header-rows: 1 +:widths: 55 45 + +* - Endpoint + - Purpose +* - `GET` / `HEAD` `/dl/{token}/{id}/{name}` + - The actual video stream (supports range requests for seeking) +* - `GET /thumb/{id}` + - A public thumbnail image for a Telegram file (used as artwork) +* - `GET /sub/{token}/{id}/{name}` + - Serves a subtitle file (small, served fully in memory) +* - `GET /stream/stats` + - Live and recent stream telemetry +* - `GET /stream/stats/{stream_id}` + - Detailed telemetry for a single stream +``` + +```{admonition} How proxying affects the stream URL +:class: note +When an **HTTP Proxy URL** is configured, the app builds the stream link by prepending the +proxy address in front of the `/dl/...` URL. With "Show Both" enabled, both the proxied and +direct links are offered to the player. +``` + +## Admin & management API (session-protected) + +The web panel is powered by a large set of `/api/...` endpoints. Highlights: + +```{list-table} +:header-rows: 1 +:widths: 50 50 + +* - Area + - Example endpoints +* - Media + - `GET /api/media/list`, `PUT /api/media/update`, `DELETE /api/media/delete` +* - Rescan / metadata + - `GET /api/media/rescan/search`, `POST /api/media/rescan/apply` +* - Manual add + - `POST /api/media/resolve-telegram`, `POST /api/media/manual-add` +* - Custom catalogs + - `GET/POST /api/custom-catalogs`, `.../items`, `.../auto-sync`, `.../auto-sync/settings` +* - Tokens & access + - `POST /api/tokens`, `DELETE /api/tokens/{token}`, `/api/admin/access/**` +* - Subscriptions + - `/api/admin/subscriptions/plans`, `/api/admin/subscriptions/users` +* - Requests + - `GET /api/admin/requests`, public `POST /api/request/submit` +* - System & tools + - `/api/admin/health`, `/api/admin/tools/scan/**`, `/api/admin/tools/dbcheck/**`, `/api/admin/backup/export` +``` + +## Response format & errors + +- Successful API calls return **JSON**. +- Stremio endpoints return the shapes Stremio expects (manifest, catalog metas, streams). +- Common error behaviors: + - **401 / redirect to `/login`** — you're not authenticated to the admin panel. + - **Token rejected** — an invalid or expired addon token. + - **Empty catalog/streams** — usually means nothing matched or the item has no files yet. + +```{admonition} Good to Know +:class: note +CORS is open (`*`) so Stremio clients on any origin can talk to your addon. +``` diff --git a/docs/catalogs.md b/docs/catalogs.md new file mode 100644 index 00000000..bec5f509 --- /dev/null +++ b/docs/catalogs.md @@ -0,0 +1,103 @@ +# Catalogs + +A **catalog** is a group of titles shown as a row/shelf in Stremio — like a playlist that +groups similar movies and shows together. + +```{admonition} Beginner Tip +:class: tip +Think of a catalog like a **playlist** or a **shelf**: "Bollywood," "Anime," "Top Rated," +or your own custom "Weekend Picks." +``` + +There are three kinds: **default**, **automatic**, and **custom/personal**. + +## Default catalogs + +Out of the box, your library is browsable by the standard **latest / popular** rows for +Movies and TV Shows, with genre and search filters supplied to Stremio. + +## Automatic catalogs + +The app can **automatically sort every title** into smart catalogs based on its metadata. +You choose which ones are enabled from **Catalogs → Auto Catalog Settings**. + +The available automatic catalogs are grouped: + +```{list-table} +:header-rows: 1 +:widths: 20 80 + +* - Group + - Catalogs +* - **Language** + - Bollywood, Hollywood, Anime, K-Drama, Bengali, South Indian, Tamil, Telugu, Malayalam, Kannada, Japanese, Korean +* - **Smart** + - Top Rated, Recently Added +* - **OTT / Platform** + - Netflix, Prime Video, Hotstar, Apple TV, Hulu, HBO, JioCinema, ZEE5, SonyLIV, MX Player, Crunchyroll +``` + +### How auto-classification works + +For each title, the app looks at data from TMDB and applies rules like: + +- **Language → catalog.** Original language `hi` → Bollywood, `ja` → Japanese, `ko` → + Korean, and so on. +- **Region nuance.** A Hindi title from India → **Bollywood**. A Korean **series** → + **K-Drama**. A Japanese **animation** → **Anime**. +- **Ratings.** A rating of **7.5 or higher** → **Top Rated**. +- **Freshness.** Released in the **last year or so** → **Recently Added**. +- **Where it streams.** Its official streaming platforms (in your region) map to OTT + catalogs like Netflix, Prime Video, or Hotstar. + +```{admonition} Needs a TMDB key +:class: warning +Language and OTT catalogs require a **TMDB API key** (the app looks up language and +streaming-provider data). **Without a key, only "Top Rated" and "Recently Added" populate.** +``` + +### When does it run? + +- **Instantly** for each new title as it's added (a quick per-item categorization). +- **In bulk** when you run a sync from the panel (processes your whole library in + batches, reusing already-classified titles to stay fast). + +```{admonition} Good to Know +:class: note +The default region for streaming-provider lookups is **India (IN)**, falling back to the +US. This affects which OTT catalog a title lands in. +``` + +## Custom catalogs + +You can build your own catalogs by hand from **Catalogs → Custom Catalogs**. + +- **Create** a catalog with any name (e.g. "Weekend Picks," "Kids"). +- **Add / remove** titles individually. +- **Edit** the name and settings. +- **Delete** it when you're done. + +## Personal / visibility controls + +Each catalog has a **visibility** setting that controls who sees it in Stremio: + +**Owner only** +: Visible just to you. + +**Selected users** +: Visible only to specific access tokens you choose. + +**Public** +: Visible to everyone using your addon. + +```{admonition} Beginner Tip +:class: tip +Use **Selected users** to give friends or paying subscribers their own private shelves +without exposing them to everyone. +``` + +## Tags + +Titles carry tags (such as **Netflix**, **Prime**, **Anime**, **Hindi**, **English**) +derived during classification. These tags are what power the automatic catalogs and help +group content consistently across your library. diff --git a/docs/changelog.md b/docs/changelog.md new file mode 100644 index 00000000..956b8d4f --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1,40 @@ +# Changelog + +```{admonition} Where the real changelog lives +:class: note +The authoritative, up-to-date version history is on GitHub: +[Releases](https://github.com/weebzone/Telegram-Stremio/releases) and the commit history. +This page summarizes the major capabilities available today. +``` + +## Feature highlights (current) + +The app has grown into a full media-server platform. Major capabilities include: + +- **Streaming** + - Permanent, non-expiring streaming links + - Split-file and multi-part playback as a single stream + - Multi-token load balancing for concurrent viewers +- **Metadata & catalogs** + - IMDb / Cinemeta + TMDB metadata matching + - Anime-aware matching for designated channels + - Automatic catalogs (Language, Smart, OTT) and custom catalogs +- **Management** + - Full web admin panel (dashboard, media, catalogs, tools, settings) + - Manual add for personal content + - Scan, DB-check, and dead-link tools + - Config backup / restore +- **Access** + - Per-user addon tokens and permissions + - Optional paid subscriptions with an approval flow + - Content request page +- **Experience** + - 13 built-in themes + - Global search across selected channels + - Optional addon proxy support + +```{admonition} Keeping up to date +:class: tip +Set **Upstream Repo/Branch** and use `/restart` (or redeploy) to pull the latest changes. +See {doc}`updating`. +``` diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..e33615a3 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,71 @@ +# Configuration file for the Sphinx documentation builder. +# Docs: https://www.sphinx-doc.org/en/master/usage/configuration.html + +from datetime import datetime + +# -- Project information ----------------------------------------------------- +project = "Telegram-Stremio" +author = "weebzone & contributors" +copyright = f"{datetime.now().year}, {author}" +release = "latest" + +# -- General configuration --------------------------------------------------- +extensions = [ + "myst_parser", + "sphinx_copybutton", + "sphinx_design", +] + +# MyST (Markdown) features we use across the docs. +myst_enable_extensions = [ + "colon_fence", # ::: fenced admonitions / directives + "deflist", # definition lists + "linkify", # auto-link bare URLs + "substitution", # variable substitutions + "tasklist", # GitHub-style checkboxes +] +myst_heading_anchors = 3 + +source_suffix = { + ".md": "markdown", + ".rst": "restructuredtext", +} + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", ".venv", "**/.venv"] + +# -- HTML output (Furo theme) ------------------------------------------------ +html_theme = "furo" +html_title = "Telegram-Stremio Docs" +html_static_path = ["_static"] +html_css_files = ["custom.css"] + +# Show a friendly 404-safe experience and a clean sidebar. +html_theme_options = { + "sidebar_hide_name": False, + "navigation_with_keys": True, + "top_of_page_buttons": ["view", "edit"], + "source_repository": "https://github.com/weebzone/Telegram-Stremio", + "source_branch": "master", + "source_directory": "docs/", + "light_css_variables": { + "color-brand-primary": "#B45309", + "color-brand-content": "#B45309", + }, + "dark_css_variables": { + "color-brand-primary": "#F59E0B", + "color-brand-content": "#FBBF24", + }, + "footer_icons": [ + { + "name": "GitHub", + "url": "https://github.com/weebzone/Telegram-Stremio", + "html": "", + "class": "fa-brands fa-github", + }, + ], +} + +# Copybutton: don't copy prompt characters. +copybutton_prompt_text = r">>> |\.\.\. |\$ |# " +copybutton_prompt_is_regexp = True diff --git a/docs/configuration.md b/docs/configuration.md new file mode 100644 index 00000000..f1fdcddb --- /dev/null +++ b/docs/configuration.md @@ -0,0 +1,180 @@ +# Configuration + +Configuration happens in **two layers**. Understanding this split makes everything +else easy. + +```{list-table} +:header-rows: 1 +:widths: 20 25 55 + +* - Layer + - Where + - What goes here +* - 🧱 **Startup** + - `config.env` file + - The core credentials needed to boot the app. Set once, before first launch. +* - 🎛️ **Runtime** + - Web Settings page + - Everything else — saved to the database and applied instantly, no restart. +``` + +```{admonition} Beginner Tip +:class: tip +Only 6 things go in `config.env`. If a setting isn't in the list below, you set it +later from the web panel — and changes take effect immediately. +``` + +## Part 1 — Startup variables (`config.env`) + +These are read once when the app starts. + +`API_ID` +: **Your Telegram API ID.** A number from [my.telegram.org](https://my.telegram.org). + Needed so the app can talk to Telegram. **Required.** + +`API_HASH` +: **Your Telegram API Hash.** A long string from the same page. **Required.** + +`BOT_TOKEN` +: **Your bot's token** from @BotFather. This is the bot that receives files and hands + out streaming links. **Required.** + +`OWNER_ID` +: **Your numeric Telegram user ID.** Marks you as the owner/super-admin. **Required.** + +`DATABASE` +: **Two MongoDB connection strings**, separated by a comma. The first is the + *tracking* database (settings, tokens, catalogs); the second is *storage_1* + (your media references). **Required.** + +`PORT` +: **The web server port.** Defaults to `8000`. Your domain/reverse proxy points here. **Required.** + +`USER_SESSION_STRING` +: **A Telegram "stay logged in" token for your own account.** Only needed to unlock + **Global Search**. Safe to leave empty. **Optional.** + +```{admonition} Why is USER_SESSION_STRING special? +:class: note +A bot can only see channels it's a member of. To search *other* channels you're in, +the app briefly uses your own account session. It's the only runtime feature that +needs a value in `config.env` plus one restart. See {doc}`search`. +``` + +## Part 2 — Runtime settings (Web Settings page) + +Open **Settings** at `/admin/settings`. These are stored in the database and applied +live. Here's what each one does. + +### General + +**Replace Mode** +: When ON, uploading a file with the **same quality label** (e.g. another `720p`) as + an existing one **replaces** the old entry instead of adding a duplicate. Recommended **ON**. + +**Hide Catalog** +: Hides the public browsable catalog in Stremio. Direct streams still work — useful if + you only want people to open specific links, not browse everything. + +### Admin Authentication + +**Admin Username / Password** +: Your web panel login. Defaults are `admin` / `admin`. + **Change these immediately.** Leave the password blank when saving to keep the current one. + +**AUTH_CHANNELS** +: The channel(s) the bot **indexes and streams from**. Add each by `@username` or its + `-100…` ID. Your bot must be an **admin** in each channel. + +```{admonition} Common Mistake +:class: warning +If a channel isn't listed in AUTH_CHANNELS, the bot **ignores** its files completely. +This is the #1 reason "nothing shows up." +``` + +### Media & Content + +**TMDB API Key** +: A free **v3** key from [themoviedb.org](https://www.themoviedb.org) → Settings → API. + Powers automatic metadata, posters, and language/OTT catalogs. + +**Base URL** +: Your public address, e.g. `https://your-domain.com`. **Critical:** Stremio uses this + exact address to reach your streams. If it's wrong, playback fails. + +**Upstream Repo / Branch** +: Optional. Used by the update process to pull the latest code (e.g. repo + `weebzone/Telegram-Stremio`, branch `master`). See {doc}`updating`. + +### Subscription (optional) + +Turn this on to charge for access. You configure: + +- **Subscription Group ID** — the channel users must join. +- **Payment Instructions** — your UPI / bank / PayPal text. +- **Payment QR image URL** — optional QR code image. +- **Approver IDs** — Telegram user IDs allowed to approve/reject payments. + +Full flow is in {doc}`user-management`. + +### Global Search (optional) + +Requires `USER_SESSION_STRING` in `config.env` plus one restart. Then enable the toggle +and add the **channel IDs** to search. See {doc}`search`. + +### Proxy (optional) + +**HTTP Proxy URL** +: An external proxy address (from a proxy provider or one you host). When set, the app + routes stream links through it. Leave empty for direct streaming (usually fastest). + +**Show Proxy and Non-Proxy Both** +: When ON, Stremio shows two links per file — one proxied, one direct — so viewers can + pick whichever works better for them. + +```{admonition} Good to Know +:class: note +The proxy is **not** created by this app and doesn't magically speed things up. It's an +optional workaround for IP blocks or geo-restrictions. It can even slow streaming if the +proxy is slow. +``` + +### Extra Storage Databases + +Your first two databases (from `config.env`) are **locked** as *Tracking* and *Storage 1*. +Add more MongoDB URIs here to expand capacity. A 🟢 means connected. + +```{admonition} Common Mistake +:class: warning +Only remove databases from the **end** of the list. Existing media references databases +**by position**, so removing one from the middle breaks those links. +``` + +### Multi-Token Clients + +Add extra **bot tokens** for faster parallel streaming under heavy load. Create more bots +with @BotFather, add them as **admins** in all your AUTH channels, then paste their tokens. +Changes apply immediately. + +```{admonition} Beginner Tip +:class: tip +Each extra bot token is like adding another checkout lane at a store — more people can be +served at once. You only need this if many people stream simultaneously. +``` + +## Storage databases explained + +You might wonder why there are multiple databases: + +- **`tracking`** — the "brain": settings, tokens, subscriptions, custom catalogs, requests. +- **`storage_1`, `storage_2`, …** — the "shelves": the actual movie/TV entries and their + Telegram file references. + +When one storage database fills up (free tiers have size limits), you add another. The app +spreads media across them and remembers which database each title lives in. + +```{admonition} Why split storage at all? +:class: note +Free MongoDB tiers cap at ~512 MB. Splitting across multiple free databases lets you grow +a large library without paying — each new database is another free "shelf." +``` diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..76bda1de --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,51 @@ +# Contributing + +Contributions are welcome — whether it's code, docs, bug reports, or ideas. + +## Ways to help + +- 🐛 **Report bugs** with clear steps to reproduce. +- 💡 **Request features** with a short description of the problem you're solving. +- 📝 **Improve docs** (including this site — the pages live under `docs/`). +- 🔧 **Send pull requests** for fixes and features. + +## Setting up for development + +```bash +git clone https://github.com/weebzone/Telegram-Stremio +cd Telegram-Stremio +cp sample_config.env config.env # fill in your values +``` + +The project is a **FastAPI** app with a **PyroFork** Telegram bot and **MongoDB** storage. +Dependencies are listed in `requirements.txt` (installed with `uv` in the Docker image). + +## Building these docs locally + +```bash +cd docs +pip install -r requirements.txt +sphinx-build -b html . _build/html +``` + +Then open `docs/_build/html/index.html` in your browser. + +## Reporting bugs + +Please include: + +- What you did and what you expected. +- What actually happened (with logs — use `/log` or Settings → Logs → Download). +- Your deployment method (Docker, Hugging Face, VPS, …) and app version. + +## Pull requests + +- Keep changes focused and describe the motivation. +- Match the existing code style. +- Test your change locally before opening the PR. + +```{admonition} Beginner Tip +:class: tip +Small, well-described PRs get reviewed and merged faster than large ones that change many +things at once. +``` diff --git a/docs/credits.md b/docs/credits.md new file mode 100644 index 00000000..0d3ce691 --- /dev/null +++ b/docs/credits.md @@ -0,0 +1,43 @@ +# Credits + +Telegram-Stremio stands on the shoulders of great open-source projects and a helpful +community. + +## Built with + +```{list-table} +:header-rows: 1 +:widths: 30 70 + +* - Project + - Role +* - **FastAPI** + - Web framework serving the API and admin panel +* - **PyroFork** + - Telegram client library powering the bot and streaming +* - **MongoDB** (via Motor) + - Database for settings, metadata, and media references +* - **TheMovieDB (TMDB)** + - Metadata, posters, and streaming-provider data +* - **IMDb / Cinemeta** + - Primary metadata matching source +* - **parse-torrent-title & GuessIt** + - Filename parsing +* - **RapidFuzz** + - Fuzzy title matching +* - **Uvicorn / uvloop** + - ASGI server and event loop +* - **Stremio SDK** + - Addon protocol this server implements +``` + +## Contributors + +Thanks to everyone who has contributed code, testing, and community support — including the +project author and the wider community around it. See the full list on the +[GitHub repository](https://github.com/weebzone/Telegram-Stremio). + +## Special thanks + +To the **Stremio** and **Nuvio** projects for the players that bring this library to your +screens, and to the users who report issues and suggest improvements. diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 00000000..ac676091 --- /dev/null +++ b/docs/deployment.md @@ -0,0 +1,128 @@ +# Deployment + +You can run Telegram-Stremio several ways. Pick the one that matches your comfort level +and budget. + +```{list-table} +:header-rows: 1 +:widths: 25 20 55 + +* - Method + - Cost + - Best for +* - Hugging Face + - Free + - Beginners who want always-online with no server to manage +* - VPS + Docker + - Paid VPS + - Best performance and full control (recommended for real use) +* - Heroku + - Varies + - Quick guided deploy via a Colab notebook +* - Local Docker + - Free + - Testing on your own PC +``` + +## Docker (single container) + +Build and run the included `Dockerfile`: + +```bash +docker build -t telegram-stremio . +docker run -d -p 8000:8000 telegram-stremio +``` + +Your server runs at `http://:8000`. + +## Docker Compose (recommended) + +Compose is easier to maintain — it mounts your config and restarts automatically. + +```bash +git clone https://github.com/weebzone/Telegram-Stremio +cd Telegram-Stremio +cp sample_config.env config.env +nano config.env # fill in your 6 values +docker compose up -d +``` + +Because `config.env` is mounted, editing it and running `docker compose restart` applies +changes **without rebuilding** the image. + +```{admonition} Beginner Tip +:class: tip +Compose also caps log size (so logs don't fill your disk) and restarts the app if it ever +crashes. It's the least-effort way to keep things running. +``` + +## VPS with a domain (HTTPS) + +For real use, run it on a VPS behind a reverse proxy so you get a clean HTTPS domain. + +1. **Point DNS** — add an `A` record for your domain to your VPS IP. +2. **Install Caddy** (it handles HTTPS certificates automatically). +3. **Configure Caddy** with a tiny config: + + ```text + your-domain.com { + reverse_proxy localhost:8000 + } + ``` + +4. Reload Caddy. Your app is now at `https://your-domain.com`. + +```{admonition} Why a reverse proxy? +:class: note +Stremio prefers **HTTPS**. A reverse proxy like Caddy (or Nginx/Cloudflare) gives you a +secure `https://` address and forwards traffic to the app on port 8000. +``` + +```{admonition} Set your Base URL! +:class: warning +After adding a domain, set **Base URL** in the web settings to that exact `https://` address. +Streams break if Base URL doesn't match how clients reach you. +``` + +## Hugging Face Spaces (free, always-online) + +This is the easiest zero-cost option — Hugging Face builds the Docker image on its servers. + +1. **Fork** the GitHub repo (so you can add secrets and run the workflow). +2. Create a **Hugging Face write token** (Profile → Settings → Access Tokens). +3. Create a **Docker Space** (Blank template), visibility **Public**. +4. In your GitHub fork → **Settings → Secrets and variables → Actions**, add: + - Secret `HF_TOKEN` = your write token + - Variable `HF_SPACE_ID` = `/` +5. On the **Hugging Face Space → Settings → Variables and secrets**, add the same values + you'd put in `config.env` (`API_ID`, `API_HASH`, `BOT_TOKEN`, `OWNER_ID`, `DATABASE`, + and optionally `USER_SESSION_STRING`). +6. In your fork → **Actions → Deploy to Hugging Face Space → Run workflow**. + +After the first run, **every push auto-deploys**. Your app lives at +`https://-.hf.space`. Set that as your **Base URL** in settings. + +```{admonition} Good to Know +:class: note +On Hugging Face you don't need a `config.env` file — the Space secrets are read directly as +environment variables. +``` + +## Heroku + +Follow the guided **Google Colab** notebook linked from the project README. It walks you +through a Heroku deploy step by step. + +## Watching on your device (Nuvio / Stremio) + +Your server works as a standard Stremio-style addon, so it plays in any compatible client. +**Nuvio** (free, open-source, available for Android, Android TV, Fire TV, iOS, Windows, and +TV) tends to handle these Telegram streams especially reliably. Regular **Stremio** works +too. *(Content was rephrased for compliance with licensing restrictions.)* + +To connect: + +1. Install [Nuvio](https://play.google.com/store/apps/details?id=com.nuvio.app) (or Stremio). +2. Send `/start` to your bot to get your **manifest URL**. +3. In the app's **Addons** section, paste the manifest URL and install. +4. Your Telegram library now appears and streams directly. 🎉 diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..a5b3b784 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,52 @@ +# FAQ + +Quick answers to the questions people ask most. + +**Why are there multiple databases?** +: The first database (`tracking`) stores settings, tokens, and catalogs. The others + (`storage_1`, `storage_2`, …) store your actual media entries. Splitting them lets you + grow a big library across several **free** MongoDB tiers without paying. See {doc}`configuration`. + +**Why Telegram as storage?** +: Telegram offers generous, reliable file hosting with no expiring links. This app turns + that storage into a streamable, organized library — no re-uploading required. + +**Can I use private channels?** +: Yes. Add the bot as an **admin** to your private channel and list it in AUTH_CHANNEL. For + manual entries and Global Search, private links (`t.me/c/...`) are supported too. + +**Can I stream lectures or personal videos?** +: Absolutely. Use **Manual Add** for content that has no IMDb/TMDB page — you supply the + title and details. See {doc}`media-management`. + +**Can multiple users stream at the same time?** +: Yes. For heavy simultaneous use, add extra **bot tokens** (multi-token load balancing) so + streams are spread across several bots. + +**Can I use Cloudflare / a reverse proxy?** +: Yes. Run the app behind Caddy, Nginx, or Cloudflare for HTTPS. Just set your **Base URL** + to the public HTTPS address. See {doc}`deployment`. + +**Do I have to pay for anything?** +: No. You can run entirely on free tiers (Hugging Face + free MongoDB). A VPS and domain are + optional upgrades for performance and a clean URL. + +**Do I need a TMDB key?** +: It's optional but strongly recommended. Without it, posters/descriptions are limited and + language/OTT auto-catalogs won't populate (only *Top Rated* and *Recently Added* will). + +**How much RAM do I need?** +: The app is lightweight. A small VPS (about **1 GB RAM**) is plenty for personal use. Heavy + multi-user streaming benefits from more, but streaming is bandwidth-bound, not RAM-bound. + +**Will my links expire?** +: No. The app stores the channel + message reference and reconnects to Telegram on demand, + so links keep working indefinitely. + +**How do I charge people for access?** +: Enable **Subscription** mode, create plans, and set approvers. Users pay through the bot + and get an auto-generated addon token on approval. See {doc}`user-management`. + +**Which app should I watch in — Stremio or Nuvio?** +: Both work. **Nuvio** tends to handle these Telegram streams more reliably across more + devices, so it's the recommended client. diff --git a/docs/getting-started.md b/docs/getting-started.md new file mode 100644 index 00000000..260e627e --- /dev/null +++ b/docs/getting-started.md @@ -0,0 +1,188 @@ +# Getting Started + +This page takes you from **nothing** to **your first working stream**. Follow it in +order and you'll be watching in about 15–20 minutes. + +```{admonition} Beginner Tip +:class: tip +You only need to fill in **6 values once** in a file called `config.env`. Everything +else is configured later from a friendly web page — no code, no restarts. +``` + +## What you need before starting + +You'll need a few free accounts and tools. Grab these first so you don't get stuck +halfway: + +Telegram account +: A normal Telegram account (the one on your phone is fine). + +A Telegram bot +: Created for free through **@BotFather** (we show you how below). + +Two MongoDB databases +: Free forever on **MongoDB Atlas** (the "M0" tier). This is where your library info lives. + +A place to run the app +: A VPS, Hugging Face Space, Heroku, or even your own PC. See {doc}`deployment`. + +A Stremio-compatible app +: **Stremio** or **Nuvio** on your phone, TV, or computer. + +```{admonition} Good to Know +:class: note +A **TMDB API key** (free) is optional but strongly recommended — it's what fetches +posters, descriptions, and organizes your automatic catalogs. +``` + +## Prerequisites (the technical bits) + +If you deploy with **Docker** (recommended), you don't need to install Python or +anything else — Docker handles it. If you run it directly on your machine, you'll need: + +- **Python 3.10+** +- **MongoDB** connection strings (from Atlas) +- The Python packages listed in `requirements.txt` + +## Step 1 — Get your Telegram credentials + +1. **API ID & API HASH** — Go to [my.telegram.org](https://my.telegram.org), log in, + open **API development tools**, and create an app (any title works). Copy the + **api_id** and **api_hash**. +2. **Bot Token** — Open **@BotFather** in Telegram, send `/newbot`, follow the prompts, + and copy the token it gives you. +3. **Owner ID** — Open **@userinfobot** in Telegram; it replies with your numeric ID. + +```{admonition} Common Mistake +:class: warning +After creating your bot, you **must add it as an admin** in every channel you'll use +for media. If you forget this, no files will be indexed. +``` + +## Step 2 — Get your MongoDB databases + +1. Create a free account at [MongoDB Atlas](https://www.mongodb.com/atlas) and create a cluster. +2. Under **Database Access**, add a username and password. +3. Under **Network Access**, add `0.0.0.0/0` (allow from anywhere). +4. Click **Connect → Drivers** and copy the connection string. It looks like: + `mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/` +5. You need **two** — add a database name to the end of each, e.g. `/tracking` and `/storage1`. + +```{admonition} Beginner Tip +:class: tip +You can use the **same cluster** for both databases — just give them two different +names at the end of the URL. The first is for tracking/metadata, the second stores +your media references. +``` + +## Step 3 — Create your `config.env` file + +Clone the project and copy the sample config: + +```bash +git clone https://github.com/weebzone/Telegram-Stremio +cd Telegram-Stremio +cp sample_config.env config.env +``` + +Open `config.env` and fill in these values: + +```{list-table} +:header-rows: 1 +:widths: 25 15 60 + +* - Variable + - Required + - What it is +* - `API_ID` + - ✅ + - Telegram API ID (from my.telegram.org) +* - `API_HASH` + - ✅ + - Telegram API Hash (from my.telegram.org) +* - `BOT_TOKEN` + - ✅ + - Your bot token (from @BotFather) +* - `OWNER_ID` + - ✅ + - Your numeric Telegram user ID +* - `DATABASE` + - ✅ + - **Two** MongoDB URIs, separated by a comma +* - `PORT` + - ✅ + - Web server port (keep `8000` unless it's busy) +* - `USER_SESSION_STRING` + - ⬜ + - Optional — only needed for Global Search +``` + +A finished file looks like this (example values): + +```ini +API_ID="1234567" +API_HASH="abc123def456ghi789jkl012mno345pq" +BOT_TOKEN="1234567890:AAEabcdEFGhijkLMnOPqrsTUVwxyz12345" +USER_SESSION_STRING="" +OWNER_ID="987654321" +DATABASE="mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/tracking,mongodb+srv://user:pass@cluster0.xxxx.mongodb.net/storage1" +PORT="8000" +``` + +```{admonition} Common Mistake +:class: warning +The `DATABASE` value must contain **exactly two** connection strings separated by a +single comma, with **no spaces** around the comma. +``` + +## Step 4 — Run the app + +The easiest way is Docker Compose: + +```bash +docker compose up -d +``` + +Your server is now running at `http://:8000`. + +```{admonition} Good to Know +:class: note +Prefer a free, always-online option with no server to manage? See the +**Hugging Face** guide in {doc}`deployment`. +``` + +## Step 5 — Finish setup in the web panel + +1. Open `http://:8000/login` in your browser. +2. Log in with the default credentials — **`admin` / `admin`**. +3. **Change the admin password immediately** (Settings → Admin Authentication). +4. Fill in your **TMDB API Key**, **Base URL**, and **AUTH_CHANNEL(s)**, then **Save Settings**. + +See {doc}`configuration` for what every field does. + +## Step 6 — Add your first file and watch it + +1. Add your bot as an **admin** to your Telegram channel. +2. Make sure that channel is listed in **AUTH_CHANNEL** in the web settings. +3. Forward a movie with a good caption, e.g. `Ghosted 2023 720p WEBRip.mkv`. +4. In Telegram, send `/start` to your bot — it replies with your **addon URL**. +5. Paste that addon URL into Stremio/Nuvio. +6. Your movie now appears in the catalog. Press play. 🎉 + +## Verify everything is working + +Use this quick checklist: + +- [ ] The web panel loads at your URL and you can log in. +- [ ] Settings shows a green/connected status for your databases. +- [ ] Your bot replies to `/start` with an addon URL. +- [ ] A forwarded file appears under **Media Management** in the panel. +- [ ] The title shows a poster and description (means TMDB/IMDb matching works). +- [ ] The addon appears in Stremio and the file plays. + +```{admonition} Stuck? +:class: important +If a file doesn't show up, the caption is almost always the reason. Jump to +{doc}`media-management` to learn the exact naming rules, or {doc}`troubleshooting` +for common fixes. +``` diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..ee4dc1f0 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,130 @@ +# Telegram-Stremio + +Welcome to the **Telegram-Stremio** documentation — a self-hosted media server that +turns your Telegram channels into a personal Netflix-style library you can watch +inside **Stremio** (or **Nuvio**) on any device. + +```{admonition} What is this, in one sentence? +:class: tip +You upload movies and shows to a private Telegram channel, and this app makes them +appear as a browsable, streamable catalog in your Stremio-compatible app — with +posters, descriptions, seasons, and episodes filled in automatically. +``` + +## Who is this for? + +- **Beginners** who have never written code and just want their own streaming library. +- **Power users** who want subscriptions, multiple databases, and load balancing. +- **Developers** who want to understand the API and internals. + +You do **not** need to be a programmer. If you can copy, paste, and click buttons, +you can run this. + +## What can it do? + +- ⚡ Stream movies and TV shows straight from Telegram — no re-uploading, no file limits. +- ♾️ Permanent streaming links that never expire. +- 🎬 Automatic posters, descriptions, cast, and ratings from IMDb / TMDB. +- 🧩 Play split files (`.001`, `.002`) and multi-part videos as one smooth stream. +- 📚 Automatic catalogs (Bollywood, Anime, Netflix, Top Rated, and more). +- 🖥️ A friendly web admin panel — no command line needed for daily use. +- 💳 Optional paid subscriptions with an approval flow. +- 🔐 Per-user access tokens and permissions. +- 🔍 Global search across your channels. + +## How the pieces fit together + +```text + You upload a file The app reads it You watch it +┌─────────────────────┐ ┌─────────────────────┐ ┌──────────────────┐ +│ Telegram Channel │ ──▶ │ Bot + FastAPI + │ ──▶ │ Stremio / Nuvio │ +│ (your movies/shows) │ │ MongoDB + PyroFork │ │ on any device │ +└─────────────────────┘ └─────────────────────┘ └──────────────────┘ +``` + +```{admonition} Beginner Tip +:class: tip +Think of Telegram as your **hard drive**, this app as the **librarian** that +organizes everything and prints nice labels, and Stremio as the **TV remote** +you use to actually watch. +``` + +## New here? Start with these + +::::{grid} 1 1 2 2 +:gutter: 3 + +:::{grid-item-card} 🚀 Getting Started +:link: getting-started +:link-type: doc +Install the app and get your first stream working. +::: + +:::{grid-item-card} ⚙️ Configuration +:link: configuration +:link-type: doc +Understand every setting in plain English. +::: + +:::{grid-item-card} 🗂 Media Management +:link: media-management +:link-type: doc +How files are named, scanned, and organized. +::: + +:::{grid-item-card} 🛠 Troubleshooting +:link: troubleshooting +:link-type: doc +Fix the most common problems fast. +::: +:::: + +```{toctree} +:hidden: +:caption: Get Started + +getting-started +configuration +``` + +```{toctree} +:hidden: +:caption: Using the App + +streaming +media-management +catalogs +search +user-management +admin-panel +themes +``` + +```{toctree} +:hidden: +:caption: Reference & Operations + +api-reference +deployment +updating +``` + +```{toctree} +:hidden: +:caption: Help + +troubleshooting +faq +tips +``` + +```{toctree} +:hidden: +:caption: Project + +contributing +changelog +credits +license +support +``` diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..4b8ca9a7 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,25 @@ +# License + +Telegram-Stremio is released under the **GNU General Public License v3.0 (GPL-3.0)**. + +## What this means (in plain English) + +```{admonition} Not legal advice +:class: note +This is a friendly summary. The full, authoritative terms are in the +[LICENSE file](https://github.com/weebzone/Telegram-Stremio/blob/master/LICENSE). +``` + +- ✅ You may **use** the software for any purpose, including commercially. +- ✅ You may **study and modify** the source code. +- ✅ You may **share** the original or your modified version. +- ⚠️ If you distribute a modified version, you must **release your source code** under the + **same GPL-3.0 license** (this is called "copyleft"). +- ⚠️ You must **keep the license and copyright notices** intact. +- ❌ There is **no warranty** — the software is provided "as is." + +## Full text + +The complete license text lives in the `LICENSE` file at the root of the repository: + +[github.com/weebzone/Telegram-Stremio/blob/master/LICENSE](https://github.com/weebzone/Telegram-Stremio/blob/master/LICENSE) diff --git a/docs/media-management.md b/docs/media-management.md new file mode 100644 index 00000000..1d81dd5b --- /dev/null +++ b/docs/media-management.md @@ -0,0 +1,234 @@ +# Media Management + +This is the most important page for day-to-day use. It explains **how the app reads +your filenames**, how it tells movies from TV shows, how split and combined files are +handled, how to add things by hand, and how to fix wrong metadata. + +## How the app reads a filename + +Every time you upload a file, the app runs its **caption or filename** through a +cleaning-and-parsing pipeline. Understanding this helps you name files so they always +match correctly. + +### Step 1 — Cleaning + +First, the raw name is scrubbed. The app removes: + +- **URLs** that captions sometimes start with. +- **Emoji** and decorative symbols (★, ➤, •, etc.). +- **Non-English characters** (replaced with spaces). +- **Telegram channel tags** like `@MyChannel_`. +- **Codec/source clutter** in the title area (e.g. `AMZN`, `DDP`, `AAC`, `5.1`, `x` bitrate tags). + +```{admonition} Beginner Tip +:class: tip +This is why a messy caption like `@Movies4u ★ Ghosted 2023 720p WEBRip [AAC].mkv` +still matches correctly — the junk is stripped before matching. +``` + +### Step 2 — Parsing + +The cleaned name is then analyzed to pull out: + +- **Title** (e.g. *Ghosted*) +- **Year** (e.g. *2023*) +- **Season** and **Episode** numbers (for shows) +- **Quality / resolution** (e.g. *720p*, *1080p*, *2160p*) + +The app uses two parsers together (a torrent-name parser plus a fallback) so it handles +a very wide range of naming styles. + +```{admonition} Two hard requirements +:class: warning +A file is **only indexed** if the app can find **both**: + +1. A **title**, and +2. A **quality/resolution** (like `720p` or `1080p`). + +If either is missing, the file is skipped. Always include a resolution in your caption. +``` + +### Step 3 — Movie vs. TV decision + +The rule is simple: + +- If the name has a **season *and* episode** (e.g. `S01E04`) → treated as a **TV episode**. +- Otherwise → treated as a **Movie**. +- A **season with no episode** (e.g. just `S01`) → treated as a **whole-season "combined"** entry. + +## Naming files correctly + +### For movies + +```text +Ghosted 2023 720p 10bit WEBRip [Org APTV Hindi AAC 2.0CH + English 6CH] x265 HEVC.mkv +``` + +Required: **Title**, **Year**, **Quality**. Everything else is optional extra info. + +### For TV shows + +```text +Harikatha.Sambhavami.Yuge.Yuge.S01E04.1080p.WEB-DL.DUAL.DDP5.1.H.264.mkv +``` + +Required: **Title**, **Season** (`S01`), **Episode** (`E04`), **Quality**. + +### Good vs. bad names + +```{list-table} +:header-rows: 1 +:widths: 50 15 35 + +* - Filename / caption + - Result + - Why +* - `Inception 2010 1080p BluRay.mkv` + - ✅ Good + - Title, year, and quality all present +* - `The Office S02E05 720p WEB-DL.mkv` + - ✅ Good + - Clear season/episode and quality +* - `Ghosted.mkv` + - ❌ Skipped + - No quality/resolution +* - `movie_final_v2.mkv` + - ❌ Skipped + - No recognizable title or quality +* - `S01E01.mkv` + - ❌ Skipped + - No title +``` + +```{admonition} Beginner Tip +:class: tip +Put the details in the **caption** if the file name itself is ugly. The app prefers the +caption over the raw file name. +``` + +## Split files (`.001`, `.002`, …) + +Large videos are sometimes uploaded in numbered pieces. The app detects a trailing +**`.ext.NN`** pattern — a video extension followed by a 2–3 digit number — and treats +those pieces as **parts of one video**. + +```text +BigMovie.2023.1080p.mkv.001 +BigMovie.2023.1080p.mkv.002 +BigMovie.2023.1080p.mkv.003 +``` + +What happens: + +- The `.001` / `.002` suffix is **stripped before parsing**, so the numbers aren't + mistaken for an episode number. +- All parts are grouped together (by channel + quality + base name). +- Stremio sees **one stream** and plays the parts back-to-back seamlessly. + +```{admonition} Common Mistake +:class: warning +Upload the parts **to the same channel** and keep the base name identical. If the base +names differ, the app can't group them. +``` + +## Combined episodes and season packs + +Sometimes one file contains several episodes, or a whole season. + +The app detects patterns like: + +- **Episode ranges** — `E01-E04`, `EP01~EP04`, `E01 to E04`, `E1+E2`. +- The keyword **`combined`** together with a season number (e.g. `S02 Combined`). +- A **season with no episode** (e.g. `S01`) is treated as a whole-season file. + +Combined files are filed under a special **"Season N Combined"** entry (in a Specials +folder), labeled with the range like `E01-E04` or `Full`, so they don't clash with your +individual episodes. + +```{admonition} Good to Know +:class: note +Valid episode ranges are between 1 and 99, and the start must be lower than the end +(e.g. `E01-E04` works; `E04-E01` does not). +``` + +## Automatic metadata (posters, descriptions, ratings) + +Once a title and year are known, the app looks up rich details: + +1. It first searches **IMDb / Cinemeta** for a strong match. +2. If that's weak or missing, it falls back to **TMDB** (needs your TMDB API key). +3. For channels you mark as **anime**, it tries anime-specific matching first. + +From the match it stores: **poster**, **backdrop**, **logo**, **description**, **cast**, +**genres**, **runtime**, **rating**, and (for shows) **per-episode titles and stills**. + +```{admonition} Beginner Tip +:class: tip +No poster showing? It usually means the title/year didn't match a database entry. Fix the +caption or use a manual override (below). A TMDB API key dramatically improves matching. +``` + +## Fixing incorrect or missing metadata + +If a title is matched to the wrong movie/show, you have three easy options. + +### Method 1 — IMDb / TMDB URL in the caption + +1. Copy the correct **IMDb** or **TMDB** URL. +2. **Edit** the file's caption in your AUTH channel and paste the URL anywhere in it. +3. The app removes the old entry, re-scans using that URL, and saves the correct data. + +### Method 2 — Scan Metadata in the web panel + +1. Open the title under **Movies** or **TV Shows** in the panel. +2. Click **Edit → Scan Metadata**. +3. Search for the correct title and pick the right result. +4. Apply. The catalog updates instantly. + +### Method 3 — `/set` for a batch of uploads + +Send `/set ` to the bot, then forward the related files — they'll all use that +ID. Send `/set` with no URL to clear it afterward. See {doc}`admin-panel` for bot commands. + +## Manual entry (add files by hand) + +Some content isn't a public movie or show — personal videos, lectures, recordings. You can +add these manually from the panel instead of relying on automatic matching. + +The manual-add flow (**Media Management → Manual Add**) lets you point at a specific +Telegram message and add it as a custom movie, show, season, episode, or extra quality. + +You can identify the source message by: + +- A **public link** — `t.me//` +- A **private link** — `t.me/c//` +- Or a **chat ID + message ID** pair. + +When you provide the message, the app: + +- Fetches the file and reads its real details. +- Determines quality from the **actual video height** when available + (e.g. 1080 px → `1080p`), falling back to the filename. +- Uses the caption over the raw file name, and strips any split-part suffix. +- Records the original upload date/year. + +```{admonition} Beginner Tip +:class: tip +Manual entry is perfect for **lectures, home videos, or anything without an IMDb page.** +You supply the title and details, and it streams just like everything else. +``` + +```{admonition} Good to Know +:class: note +Channels you designate as **manual channels** are *not* auto-indexed — they're reserved +for hand-added content, so random uploads there won't clutter your catalog. +``` + +## Auto-cleanup + +The app keeps your library tidy automatically: + +- **Delete a message** in Telegram → its catalog entry is purged automatically. +- **Edit a caption** with an override ID → the title is re-indexed. +- **Replace Mode** on → a new file of the same quality replaces the old one instead of + creating a duplicate. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..58d4beac --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,7 @@ +sphinx>=7.2 +furo>=2024.1.29 +myst-parser>=2.0 +sphinx-copybutton>=0.5.2 +sphinx-design>=0.5.0 +linkify-it-py>=2.0 + diff --git a/docs/search.md b/docs/search.md new file mode 100644 index 00000000..4aee70b0 --- /dev/null +++ b/docs/search.md @@ -0,0 +1,40 @@ +# Search + +Your library is searchable from inside Stremio, and you can optionally search **beyond** +your local catalog with Global Search. + +## Local search + +By default, Stremio's search box queries **your indexed library** — the movies and shows +already stored in your databases. Results are filtered and sorted for you, respecting each +title's visibility settings. + +## Global Search (optional) + +Global Search lets the app look through **other Telegram channels you belong to** — not +just your AUTH channels — and surface matching files on the fly. + +### Why it needs a session string + +A bot can only see channels it's a member of. To reach your *personal* channels, the app +briefly uses **your own account session** (the `USER_SESSION_STRING`). This is the same as +being logged into Telegram Web. + +### Enabling it + +1. Generate a `USER_SESSION_STRING` (see the guide in {doc}`getting-started` / + {doc}`deployment`) and put it in `config.env`. +2. **Restart** the app once to load it. +3. In the web settings, enable **Global Search** and add the **channel IDs** to search. + +```{admonition} Results are tagged +:class: note +Titles found through Global Search that aren't in your local catalog are marked with a +**🌐 GLOBAL** tag in Stremio, so you can tell them apart from your own library. +``` + +```{admonition} Keep your session string private +:class: warning +Anyone with your `USER_SESSION_STRING` can access your Telegram account. Never share it or +commit it to a public repo. You can revoke it anytime from **Telegram → Settings → Devices**. +``` diff --git a/docs/streaming.md b/docs/streaming.md new file mode 100644 index 00000000..ddcbe395 --- /dev/null +++ b/docs/streaming.md @@ -0,0 +1,88 @@ +# Streaming + +This page explains **how a file in Telegram becomes something you can watch** — in +plain English — plus the file formats supported and the analytics you can see. + +## How streaming works + +```text + Telegram PyroFork FastAPI Stremio +┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ +│ Your video │──▶ │ Reads bytes │──▶ │ Serves them │──▶ │ Plays the │ +│ sits here │ │ on demand │ │ over HTTP │ │ video for you │ +└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ +``` + +Here's the same thing in words: + +1. Your video **stays in Telegram** — it is never copied or re-uploaded. +2. When you press play, the app asks Telegram for the video **piece by piece**. +3. Those pieces are handed to your player over a normal web link. +4. The player shows the video as it arrives, so it **starts almost instantly** and you + can seek/skip around. + +```{admonition} Beginner Tip +:class: tip +Nothing is downloaded to the server first. It's like a straw into your Telegram file — +the app sips the exact part of the video you're currently watching and passes it along. +``` + +## Why links never expire + +Instead of storing a temporary Telegram download link, the app stores the **channel ID** +and **message ID** of your file. Whenever someone plays it, a fresh connection to +Telegram is made on the spot. That's why your links keep working forever. + +## Multiple bot tokens (load balancing) + +Under heavy use, a single bot can only pull so much at once. If you add extra bot tokens +(see {doc}`configuration`), the app spreads active streams across all of them — like +opening more checkout lanes. Each viewer gets assigned to the least-busy bot. + +## Supported file formats + +The app recognizes these video types when reading captions/filenames: + +```text +mkv mp4 avi ts m4v mov wmv webm flv m2ts mpg mpeg +``` + +It also understands **split archive parts** (files ending in `.001`, `.002`, …) so large +videos uploaded in pieces can be streamed as one. See {doc}`media-management` for the +naming rules. + +```{admonition} Limitations +:class: warning +- The most reliable playback formats are **MKV** and **MP4** — stored titles are + normalized to one of these. +- Some players struggle with certain codecs (e.g. exotic audio tracks). If a video plays + with no sound, it's usually a codec issue in the player, not the server. +- "Multipart" files meant to be joined *outside* the player (e.g. `movie.part1.rar`) are + **skipped** — they aren't streamable video on their own. +``` + +## Streaming analytics + +The web panel and API expose live streaming telemetry so you can see what's happening. + +**Active streams** +: Who/what is playing **right now**, including how many bytes have been transferred. + +**Recent history** +: A rolling list of recently finished streams. + +**Speed & health** +: A **Health Dashboard** and a **Speed Test** let you check that Telegram, your databases, + and streaming are all responsive. + +Relevant endpoints (see {doc}`api-reference` for details): + +- `/stream/stats` — live and recent stream summary. +- `/stream/stats/{stream_id}` — detailed telemetry for one stream. +- `/api/system/speedtest` — measure real streaming throughput. + +```{admonition} Good to Know +:class: note +If you enabled **subscriptions** or **per-token limits**, streaming usage (bandwidth) is +tracked per user token so daily/monthly caps can be enforced. +``` diff --git a/docs/support.md b/docs/support.md new file mode 100644 index 00000000..5a76d8cd --- /dev/null +++ b/docs/support.md @@ -0,0 +1,35 @@ +# Support + +Need help? Here's where to go. + +## GitHub Issues + +For bugs and feature requests, open an issue on the repository: + +[github.com/weebzone/Telegram-Stremio/issues](https://github.com/weebzone/Telegram-Stremio/issues) + +```{admonition} Help us help you +:class: tip +Include your deployment method, app version, clear steps to reproduce, and logs +(`/log` in the bot, or Settings → Logs → Download). It speeds up fixes a lot. +``` + +## Before you ask + +You'll often find the answer faster in: + +- {doc}`troubleshooting` — fixes for the most common problems. +- {doc}`faq` — quick answers to frequent questions. +- {doc}`configuration` — what every setting does. + +## Community + +The project has an active community around it. Check the +[repository README](https://github.com/weebzone/Telegram-Stremio) for the latest community +links (Telegram group, etc.) and contributor contacts. + +```{admonition} Be kind and specific +:class: note +Maintainers and community members are volunteers. A clear, respectful, well-described +question gets a better response than "it doesn't work." +``` diff --git a/docs/themes.md b/docs/themes.md new file mode 100644 index 00000000..04b1eed6 --- /dev/null +++ b/docs/themes.md @@ -0,0 +1,64 @@ +# Themes + +The web panel ships with **13 built-in themes** — 9 dark and 4 light. Pick one from the +theme switcher in the panel; your choice is remembered. + +```{admonition} Beginner Tip +:class: tip +Themes only change how the **admin web panel** looks. They don't affect how your library +appears in Stremio. +``` + +The default theme is **Graphite Amber**. + +## Dark themes + +```{list-table} +:header-rows: 1 +:widths: 30 70 + +* - Theme + - Vibe +* - **Graphite Amber** (default) + - Warm amber accents on near-black graphite +* - **AMOLED Midnight** + - True-black background with cool sky-blue accents — great for OLED screens +* - **Obsidian Emerald** + - Deep green-on-black +* - **Royal Violet** + - Rich purple accents +* - **Slate Ocean** + - Cool blue on dark slate +* - **Charcoal Violet** + - Neon-lime accents on a dark violet base +* - **Fresh Canopy** + - Soft lime-green on deep forest tones +* - **Tiffany Noir** + - Mint/teal accents on pure charcoal +* - **Bridal Blush** + - Warm peach/rose accents on dark maroon +``` + +## Light themes + +```{list-table} +:header-rows: 1 +:widths: 30 70 + +* - Theme + - Vibe +* - **Rose Quartz** + - Soft pink on a bright, airy background +* - **Daylight Sky** + - Clean blue-on-white, classic and neutral +* - **Sage Linen** + - Calm teal-green on off-white +* - **Golden Hour** + - Warm amber/brown on cream +``` + +```{admonition} Good to Know +:class: note +Each theme defines its own accent, background, card, border, and text colors, so the whole +panel stays consistent and readable whichever one you choose. +``` diff --git a/docs/tips.md b/docs/tips.md new file mode 100644 index 00000000..96dac6e7 --- /dev/null +++ b/docs/tips.md @@ -0,0 +1,68 @@ +# Tips & Best Practices + +Small habits that keep your server fast, tidy, and reliable. + +## Name files well + +Good captions are 90% of a smooth experience. + +- Always include **title + year + resolution** for movies. +- Use `S01E04`-style markers for episodes. +- Let the app clean the junk — you don't need to strip tags yourself, but a clean caption + matches faster. + +```{admonition} Recommended +:class: tip +`Movie Name 2023 1080p WEB-DL.mkv` and `Show Name S01E05 720p.mkv` are the sweet spot — +enough for perfect matching, nothing missing. +``` + +## Keep metadata clean + +- Add a **TMDB API key** early — it improves matching and unlocks language/OTT catalogs. +- Fix wrong matches promptly with a caption URL override or **Scan Metadata**. +- Run **Dead Links** cleanup occasionally to remove entries whose files were deleted. + +## Backup regularly + +- Export your **config JSON** before big changes or migrations. +- Snapshot your **MongoDB** databases on a schedule. See {doc}`updating`. + +## Performance tuning + +- Add extra **bot tokens** if several people stream at once — it spreads the load. +- Prefer **direct streaming** (no proxy) unless you specifically need a proxy for + geo/IP reasons; a slow proxy adds buffering. +- Put the app behind a **reverse proxy with HTTPS** for the most compatible playback. +- Enable **Replace Mode** so you don't accumulate duplicate qualities. + +## Recommended server specs + +```{list-table} +:header-rows: 1 +:widths: 30 35 35 + +* - Use case + - CPU / RAM + - Notes +* - Personal (1–2 viewers) + - 1 vCPU / 1 GB + - Free tiers or a small VPS are fine +* - Small group (a few viewers) + - 1–2 vCPU / 2 GB + - Add 1–2 extra bot tokens +* - Community (many viewers) + - 2+ vCPU / 4 GB+ + - Several bot tokens + good bandwidth matter most +``` + +```{admonition} Good to Know +:class: note +Streaming is limited far more by **bandwidth and Telegram rate limits** than by CPU/RAM. +Prioritize a host with good network throughput. +``` + +## Storage growth + +- When a storage database nears its size limit, **add another** from settings. +- Only remove storage databases from the **end** of the list to avoid breaking references. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..452e0b01 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,93 @@ +# Troubleshooting + +This is likely your most-visited page. Find your symptom and follow the fix. + +```{admonition} First stop +:class: tip +Open the **Health Dashboard** in the admin panel. It quickly tells you whether Telegram, +your databases, and streaming are healthy — narrowing down the problem fast. +``` + +## Bot doesn't respond + +- Confirm `BOT_TOKEN`, `API_ID`, and `API_HASH` are correct in `config.env`. +- Make sure the app is actually running (check logs / container status). +- Try messaging the bot again after a restart. + +## Files aren't showing up / "nothing happens" when I upload + +This is almost always one of these: + +- The channel **isn't in AUTH_CHANNEL**. Add it in settings. +- The bot **isn't an admin** in that channel. +- The caption **lacks a resolution** (`720p`, `1080p`, …) — the file is skipped without one. +- The caption **lacks a title**. + +```{admonition} Quick test +:class: note +Forward a file captioned exactly `Inception 2010 1080p BluRay.mkv`. If that shows up, your +earlier captions were the issue. +``` + +## No streams found (item shows but won't play) + +- Check that **Base URL** matches exactly how you reach the server (including `https://`). +- Verify the Telegram file still exists (deleted messages are purged automatically). +- Look at the **Tools → Dead Links** report to find broken entries. + +## Metadata missing or wrong + +- Add a **TMDB API key** in settings — it dramatically improves matching. +- Fix the title/year in the caption, or use a **manual override** (IMDb/TMDB URL in the + caption, or **Scan Metadata** in the panel). See {doc}`media-management`. + +## Posters missing + +- Same cause as missing metadata — the title didn't match a database entry, or there's no + TMDB key. Re-scan the title with the correct match. + +## Catalog is empty + +- Automatic **language/OTT catalogs need a TMDB key** — without it only *Top Rated* and + *Recently Added* fill up. +- Make sure you **enabled** and **saved** your auto-catalog selection. +- Run an **auto-sync** from the Catalogs page. + +## MongoDB connection failed + +- Re-check both URIs in `DATABASE` (username, password, and a database name at the end). +- In MongoDB Atlas → **Network Access**, allow `0.0.0.0/0`. +- Make sure the two URIs are separated by a **single comma with no spaces**. + +## OffsetInvalid / FloodWait errors in logs + +- **FloodWait** means Telegram is rate-limiting you; the app waits and retries. Slow down + bulk scans or add more bot tokens to spread the load. +- **OffsetInvalid** usually clears on retry; if persistent, re-scan the affected channel. + +## Stream stops midway / buffering + +- Your server or proxy bandwidth may be the bottleneck — run a **Speed Test** in the panel. +- If you set an **HTTP Proxy URL**, try disabling it; a slow proxy hurts streaming. +- Add extra **bot tokens** so heavy concurrent use is spread across more bots. + +## Subtitles missing + +- Subtitle files must be uploaded to your channel; supported subtitle files are ingested + automatically and attached to the matching title/episode. +- Make sure the subtitle's name matches the video closely enough to associate it. + +## Playback has no sound + +- Usually a **codec** limitation in your player, not the server. Try a different player + (Nuvio is recommended) or a file with a more common audio track. + +## Authentication failed (web panel) + +- Default login is `admin` / `admin`. If you changed it and forgot, update + `ADMIN_USERNAME` / `ADMIN_PASSWORD` and restart, or reset from your database. + +## Something else? + +Grab logs with the bot's `/log` command or **Settings → Logs → Download**, then open an +issue (see {doc}`support`). diff --git a/docs/updating.md b/docs/updating.md new file mode 100644 index 00000000..62091c83 --- /dev/null +++ b/docs/updating.md @@ -0,0 +1,73 @@ +# Updating, Backup & Restore + +Keeping your server current and your data safe. + +## Updating the app + +There are two common ways to get the latest version. + +### Option A — `/restart` (built-in updater) + +If you set **Upstream Repo** and **Upstream Branch** in settings, sending `/restart` to +your bot pulls the latest code from that repo/branch and restarts. + +```{admonition} Beginner Tip +:class: tip +Set Upstream Repo to `weebzone/Telegram-Stremio` and branch to `master` (or your own fork) +so `/restart` can update you in one step. +``` + +### Option B — Redeploy + +- **Docker Compose (VPS):** + + ```bash + git pull + docker compose up -d --build + ``` + +- **Hugging Face:** push to your fork (or click **Run workflow**) — it auto-rebuilds. + +## Backup your data + +Two things are worth backing up: + +**Your configuration** +: From **Settings**, use **Backup → Export** to download a JSON file of your settings. + Restore later with **Import**. + +**Your MongoDB databases** +: These hold your entire library and users. Back them up with your provider's tools or + `mongodump`: + + ```bash + mongodump --uri="" --out=backup/ + ``` + +## Restore + +- **Config:** Settings → **Import** the JSON file you exported. +- **Databases:** restore with `mongorestore`: + + ```bash + mongorestore --uri="" backup/ + ``` + +## Migrating to a new server + +1. **Export** your config JSON and back up your databases. +2. Stand up the app on the new host (see {doc}`deployment`). +3. Point `DATABASE` at the same MongoDB (or restore your dump there). +4. **Import** your config, update **Base URL** to the new address, and save. + +```{admonition} Common Mistake +:class: warning +After migrating, don't forget to update **Base URL** to the new domain/IP. Old stream +links point at the address stored in Base URL. +``` + +```{admonition} Order matters for storage databases +:class: warning +Media references storage databases **by position** in the list. When migrating, keep the +same database order so existing titles keep resolving to the right files. +``` diff --git a/docs/user-management.md b/docs/user-management.md new file mode 100644 index 00000000..3dbc9621 --- /dev/null +++ b/docs/user-management.md @@ -0,0 +1,128 @@ +# User Management + +This page covers **who can access your streams** — access tokens, permissions, and the +optional paid subscription system. + +## The big picture + +Every viewer accesses your addon through a **unique token** embedded in their addon URL: + +```text +https://your-domain.com/stremio/{token}/manifest.json +``` + +That token identifies them, controls what they can see, and (if enabled) ties them to a +subscription. If you don't enable subscriptions, tokens simply act as access keys. + +## Telegram users + +Users interact with your **bot**. When they send `/start`, the bot responds based on your +setup: + +- **No subscription mode** → they get an addon URL right away. +- **Subscription mode** → they're guided to choose a plan and pay first. + +## Access tokens + +From **Admin Panel → Access Management**, you manage every token: + +```{list-table} +:header-rows: 1 +:widths: 25 75 + +* - Column + - Meaning +* - Status + - 🟢 Active / 🔴 Expired +* - User + - Display name or `User {id}` +* - Addon Link + - Their Stremio install URL (with a copy button) +* - Created + - When the token was made +* - Expires + - Subscription expiry date +* - Actions + - Buttons to manage the user +``` + +### Action buttons + +```{list-table} +:header-rows: 1 +:widths: 25 75 + +* - Button + - What it does +* - 📅 **Assign** + - Assign or extend a subscription plan (adds days) +* - ➕ **Extend** + - Add extra days to an active subscription +* - ➖ **Reduce** + - Subtract days +* - 🚫 **Revoke** + - Wipe the subscription (marks expired) +* - 🗑️ **Del Token** + - Delete only the addon token (user stays subscribed) +* - 🔗 **Link User ID** + - Link an old/orphan token to a Telegram user ID so it can be managed +``` + +```{admonition} Beginner Tip +:class: tip +Old, manually created tokens that have no linked user show a **🔗 Link User ID** button. +Link it once and all the other management buttons unlock. +``` + +## Permissions & limits + +Tokens can carry **usage limits** (for example daily or monthly bandwidth caps). The app +tracks how much each token streams and can enforce those limits, which is handy for paid +tiers or fair-use control. + +## Subscriptions (optional) + +Turn this on to **monetize access**. When enabled, users need an active subscription to +stream. + +### Plans + +Create plans in **Admin Panel → Subscription Management**. Each plan has a **name**, +**duration in days**, **price** (for display), and **description**. Plans can be added, +edited, or deleted anytime without restarting. + +### The payment flow + +```text +User → /start → picks a plan → sends payment screenshot + → Approver is notified → Approve / Reject + → On Approve: + ✅ Subscription saved + 🔑 Stremio token auto-generated + 📨 User gets their install link + group invite +``` + +Approvers (the **Approver IDs** you configured) get **Approve** / **Reject** buttons in +Telegram. + +### What the user sees in Stremio + +The addon adapts per user: + +- **Active, with expiry** → addon named like `Telegram — Expires 28 Mar 2026`. +- **Active, no expiry** → `Telegram — Active`. +- **Expired** → instead of streams, a single **🚫 Plan Expired** entry that opens your bot + to renew. +- **Not joined** → a **📢 Join Required** entry that opens your bot to rejoin the group. + +```{admonition} Fail-safe by design +:class: note +The "did they join the channel?" check **fails open** — if Telegram is briefly unreachable, +legitimate users are never wrongly blocked. +``` + +### Configure / reinstall page + +Each user has a page at `/stremio/{token}/configure` showing their status, expiry, and an +**Install / Update in Stremio** button. The ⚙️ gear icon in Stremio opens this so users can +reinstall after you extend or change their subscription. From 22bde7602a08303a4155045e46c4a2c48021b064 Mon Sep 17 00:00:00 2001 From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com> Date: Fri, 10 Jul 2026 16:45:34 +0000 Subject: [PATCH 2/6] ci: auto-deploy docs to GitHub Pages --- .github/workflows/docs.yml | 69 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 .github/workflows/docs.yml diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 00000000..18043c8e --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,69 @@ +name: Deploy Docs to GitHub Pages + +# Builds the Sphinx (Furo) documentation in docs/ and publishes it to GitHub Pages. +# Runs on every push to main/master that touches the docs, and can be triggered manually. +# +# One-time setup (all doable from a browser): +# 1. Merge this workflow into your default branch (main/master). +# 2. In this GitHub repo: Settings -> Pages -> "Build and deployment" +# - Source: "GitHub Actions" +# 3. Push a commit to docs/ (or run this workflow manually from the Actions tab). +# Your site will be published at: +# https://.github.io// +# +# No secrets required — GitHub Pages uses the built-in GITHUB_TOKEN. + +on: + push: + branches: [main, master] + paths: + - "docs/**" + - ".github/workflows/docs.yml" + workflow_dispatch: + +# Allow the workflow to publish to GitHub Pages. +permissions: + contents: read + pages: write + id-token: write + +# Only one Pages deployment at a time; don't cancel an in-progress one. +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + cache: pip + cache-dependency-path: docs/requirements.txt + + - name: Install documentation dependencies + run: pip install -r docs/requirements.txt + + - name: Build the documentation + run: sphinx-build -b html -W --keep-going docs docs/_build/html + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy: + needs: build + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From ca7a1c2fd259dca717b3bb3497eb0c70c8f91c5f Mon Sep 17 00:00:00 2001 From: Karan Adhikari Date: Fri, 10 Jul 2026 22:27:09 +0530 Subject: [PATCH 3/6] Create CNAME --- CNAME | 1 + 1 file changed, 1 insertion(+) create mode 100644 CNAME diff --git a/CNAME b/CNAME new file mode 100644 index 00000000..cc7eb0f0 --- /dev/null +++ b/CNAME @@ -0,0 +1 @@ +wzmlx.space \ No newline at end of file From f80c592be26f9d27fda94e71db143262c9c2abde Mon Sep 17 00:00:00 2001 From: Karan Adhikari Date: Fri, 10 Jul 2026 22:28:56 +0530 Subject: [PATCH 4/6] Delete CNAME --- CNAME | 1 - 1 file changed, 1 deletion(-) delete mode 100644 CNAME diff --git a/CNAME b/CNAME deleted file mode 100644 index cc7eb0f0..00000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -wzmlx.space \ No newline at end of file From 5c64c5784ab128978db6033652f5dc8ed759d7ef Mon Sep 17 00:00:00 2001 From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com> Date: Fri, 10 Jul 2026 17:46:57 +0000 Subject: [PATCH 5/6] ci: auto-enable Pages via GitHub Actions and trigger on docs branch --- .github/workflows/docs.yml | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 18043c8e..a4bfa5c3 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -1,21 +1,21 @@ name: Deploy Docs to GitHub Pages # Builds the Sphinx (Furo) documentation in docs/ and publishes it to GitHub Pages. -# Runs on every push to main/master that touches the docs, and can be triggered manually. # -# One-time setup (all doable from a browser): -# 1. Merge this workflow into your default branch (main/master). -# 2. In this GitHub repo: Settings -> Pages -> "Build and deployment" -# - Source: "GitHub Actions" -# 3. Push a commit to docs/ (or run this workflow manually from the Actions tab). -# Your site will be published at: -# https://.github.io// +# The build job uses actions/configure-pages with enablement, which programmatically +# sets the repo's Pages source to "GitHub Actions" — so you do NOT need to manually +# flip Settings -> Pages -> Source. It also stops the automatic Jekyll builder +# ("pages build and deployment") from serving raw Markdown. # +# Publishes to: https://.github.io// # No secrets required — GitHub Pages uses the built-in GITHUB_TOKEN. +# +# NOTE: "docs/user-guide" is included below so the site can be previewed before the +# PR is merged. After merging, that branch line can be removed (master is enough). on: push: - branches: [main, master] + branches: [main, master, docs/user-guide] paths: - "docs/**" - ".github/workflows/docs.yml" @@ -39,6 +39,11 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 + - name: Configure GitHub Pages (sets source to GitHub Actions) + uses: actions/configure-pages@v5 + with: + enablement: true + - name: Set up Python uses: actions/setup-python@v5 with: From 338c69fd9c1cfaca37b55053ad7c1b218c3278cf Mon Sep 17 00:00:00 2001 From: Kiro Agent <244629292+kiro-agent@users.noreply.github.com> Date: Fri, 10 Jul 2026 18:12:57 +0000 Subject: [PATCH 6/6] =?UTF-8?q?docs:=20refresh=20home=20page=20=E2=80=94?= =?UTF-8?q?=20persona=20cards,=20remove=20intro/diagram?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/index.md | 47 ++++++++++++++++++++++++----------------------- 1 file changed, 24 insertions(+), 23 deletions(-) diff --git a/docs/index.md b/docs/index.md index ee4dc1f0..d3cd19f7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,23 +2,34 @@ Welcome to the **Telegram-Stremio** documentation — a self-hosted media server that turns your Telegram channels into a personal Netflix-style library you can watch -inside **Stremio** (or **Nuvio**) on any device. +inside **Stremio** (or **Nuvio**) on any device. 🍿 -```{admonition} What is this, in one sentence? -:class: tip -You upload movies and shows to a private Telegram channel, and this app makes them -appear as a browsable, streamable catalog in your Stremio-compatible app — with -posters, descriptions, seasons, and episodes filled in automatically. -``` +## 💛 Who is this for? + +::::{grid} 1 1 3 3 +:gutter: 3 -## Who is this for? +:::{grid-item-card} 🎬 Your own free Netflix +For anyone who wants a **personal, ad-free streaming library** — your movies and +shows, beautiful posters and all, without paying a monthly bill. +::: + +:::{grid-item-card} 📚 Stream personal files +For anyone who wants to stream their **own videos, lectures, or recordings** from +anywhere — no re-uploading, no downloads, just press play. +::: -- **Beginners** who have never written code and just want their own streaming library. -- **Power users** who want subscriptions, multiple databases, and load balancing. -- **Developers** who want to understand the API and internals. +:::{grid-item-card} 💳 Earn with subscriptions +For anyone who wants to **make money** by offering paid access — built-in plans, +payments, and an approval flow, all handled for you. +::: +:::: +```{admonition} No coding required +:class: tip You do **not** need to be a programmer. If you can copy, paste, and click buttons, -you can run this. +you can run this. 🙌 +``` ## What can it do? @@ -32,16 +43,6 @@ you can run this. - 🔐 Per-user access tokens and permissions. - 🔍 Global search across your channels. -## How the pieces fit together - -```text - You upload a file The app reads it You watch it -┌─────────────────────┐ ┌─────────────────────┐ ┌──────────────────┐ -│ Telegram Channel │ ──▶ │ Bot + FastAPI + │ ──▶ │ Stremio / Nuvio │ -│ (your movies/shows) │ │ MongoDB + PyroFork │ │ on any device │ -└─────────────────────┘ └─────────────────────┘ └──────────────────┘ -``` - ```{admonition} Beginner Tip :class: tip Think of Telegram as your **hard drive**, this app as the **librarian** that @@ -49,7 +50,7 @@ organizes everything and prints nice labels, and Stremio as the **TV remote** you use to actually watch. ``` -## New here? Start with these +## 🚀 New here? Start with these ::::{grid} 1 1 2 2 :gutter: 3