streamlens 0.1.0__py3-none-any.whl

streamlens/__init__.py

@@ -0,0 +1,12 @@
+"""streamlens: live streams in one auto-updating Telegram message."""
+from .message import build_rich_message, build_text_message
+from .models import Stream, detect_platform
+from .publisher import Publisher, publish
+from .telegram import TelegramClient, TelegramError
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Stream", "Publisher", "publish", "detect_platform", "build_rich_message", "build_text_message",
+    "TelegramClient", "TelegramError", "__version__",
+]

streamlens/cli.py

@@ -0,0 +1,193 @@
+"""Command line: ``streamlens send | watch | check | clear``."""
+from __future__ import annotations
+
+import argparse
+import csv
+import datetime as dt
+import io
+import json
+import os
+import sys
+import time
+from typing import List, Optional
+from urllib.request import urlopen
+
+from . import __version__
+from .models import Stream
+from .publisher import Publisher
+from .sources import MissingDependency, TwitchApi, parse_channels, probe_channels
+from .telegram import TelegramClient, TelegramError
+
+ENV_TOKEN = ("STREAMLENS_TOKEN", "TELEGRAM_BOT_TOKEN")
+ENV_CHAT = ("STREAMLENS_CHAT_ID", "TELEGRAM_CHAT_ID")
+
+
+def _env(names) -> Optional[str]:
+    return next((os.environ[n] for n in names if os.environ.get(n)), None)
+
+
+def _load_image(value: Optional[str], base_dir: str) -> Optional[bytes]:
+    if not value:
+        return None
+    if value.startswith(("http://", "https://")):
+        with urlopen(value, timeout=20) as r:  # noqa: S310 (a URL that the user gave)
+            return r.read()
+    path = value if os.path.isabs(value) else os.path.join(base_dir, value)
+    with open(path, "rb") as f:
+        return f.read()
+
+
+def _num(value) -> Optional[int]:
+    return None if value in (None, "") else int(float(value))
+
+
+def load_streams(path: str) -> List[Stream]:
+    """Reads a JSON list or a CSV (header: name,url,online,...) from a file or stdin (``-``).
+
+    Columns / keys: name, url, online, platform, title, started_at (ISO 8601), watch_url, online_diff,
+    image (a file path or an http(s) URL)."""
+    text = sys.stdin.read() if path == "-" else open(path, encoding="utf-8").read()
+    base_dir = "." if path == "-" else os.path.dirname(os.path.abspath(path))
+    if text.lstrip().startswith(("[", "{")):
+        data = json.loads(text)
+        rows = data["streams"] if isinstance(data, dict) else data
+    else:
+        rows = list(csv.DictReader(io.StringIO(text)))
+
+    streams = []
+    for row in rows:
+        started = row.get("started_at")
+        streams.append(Stream(
+            name=row["name"], url=row["url"], online=_num(row.get("online")), platform=row.get("platform") or None,
+            online_diff=_num(row.get("online_diff")), title=row.get("title") or None,
+            watch_url=row.get("watch_url") or None,
+            started_at=dt.datetime.fromisoformat(started.replace("Z", "+00:00")) if started else None,
+            image=_load_image(row.get("image"), base_dir)))
+    return streams
+
+
+def _publisher(args) -> Publisher:
+    token, chat_id = args.token or _env(ENV_TOKEN), args.chat_id or _env(ENV_CHAT)
+    if not args.dry_run and not token:
+        sys.exit("Bot token is missing: --token or STREAMLENS_TOKEN (get one from @BotFather)")
+    if not chat_id:
+        sys.exit("Chat is missing: --chat-id or STREAMLENS_CHAT_ID")
+    split = [g.split("+") for g in args.split] if args.split else None
+    return Publisher(token, chat_id, state=args.state, lang=args.lang, tz=args.tz, mode=args.mode, split=split,
+                     sort=args.sort, min_online=args.min_online, exclude=args.exclude or (),
+                     empty_message=not args.no_empty_message, dry_run=args.dry_run)
+
+
+def cmd_send(args) -> None:
+    pub = _publisher(args)
+    streams = load_streams(args.file)
+    ids = pub.publish(streams)
+    print(f"streams: {len(streams)}, messages sent: {len(ids)}")
+
+
+def cmd_watch(args) -> None:
+    pub = _publisher(args)
+    with open(args.channels, encoding="utf-8") as f:
+        channels = parse_channels(f.read())
+    if not channels:
+        sys.exit(f"{args.channels}: no channels found")
+    twitch_id, twitch_secret = os.environ.get("TWITCH_CLIENT_ID"), os.environ.get("TWITCH_CLIENT_SECRET")
+    twitch = TwitchApi(twitch_id, twitch_secret) if twitch_id and twitch_secret else None
+    if not twitch and any("twitch.tv" in c["url"] for c in channels):
+        print("note: no TWITCH_CLIENT_ID / TWITCH_CLIENT_SECRET, so Twitch viewers are unknown (frames still work)")
+
+    while True:
+        started = time.monotonic()
+        try:
+            streams = probe_channels(channels, twitch=twitch, cookies_file=args.cookies)
+            ids = pub.publish(streams)
+            print(f"{dt.datetime.now():%Y-%m-%d %H:%M:%S} live: {len(streams)} of {len(channels)}, "
+                  f"messages sent: {len(ids)}", flush=True)
+        except (MissingDependency, ValueError):
+            raise
+        except TelegramError as e:
+            print(f"telegram error: {e}", file=sys.stderr, flush=True)
+        if args.once:
+            return
+        time.sleep(max(1, args.every * 60 - (time.monotonic() - started)))
+
+
+def cmd_check(args) -> None:
+    token, chat_id = args.token or _env(ENV_TOKEN), args.chat_id or _env(ENV_CHAT)
+    if not token or not chat_id:
+        sys.exit("Need --token and --chat-id (or STREAMLENS_TOKEN / STREAMLENS_CHAT_ID)")
+    client = TelegramClient(token)
+    try:
+        me = client.get_me()
+        print(f"token ok: @{me.get('username')}")
+        msg = client.send_text(chat_id, "✅ streamlens: the bot can post here")
+        client.delete(chat_id, msg["message_id"])
+        print(f"chat {chat_id} ok: test message sent and removed")
+    except TelegramError as e:
+        sys.exit(f"failed: {e}")
+
+
+def cmd_clear(args) -> None:
+    pub = _publisher(args)
+    print(f"deleted messages: {pub.clear()}")
+
+
+def _add_common(p: argparse.ArgumentParser) -> None:
+    p.add_argument("--token", help="bot token (or env STREAMLENS_TOKEN)")
+    p.add_argument("--chat-id", help="chat / channel / user id (or env STREAMLENS_CHAT_ID)")
+    p.add_argument("--state", default=os.environ.get("STREAMLENS_STATE", "streamlens.db"),
+                   help="SQLite file with message ids and frames (default: ./streamlens.db)")
+    p.add_argument("--lang", default="en", choices=("en", "ru"))
+    p.add_argument("--tz", default="UTC", help="time zone of the footer, e.g. Europe/Moscow")
+    p.add_argument("--mode", default="auto", choices=("auto", "rich", "text"),
+                   help="rich = message with frames, text = plain text, auto = rich with a text fallback")
+    p.add_argument("--split", action="append", metavar="PLATFORMS",
+                   help="separate message for these platforms, e.g. --split twitch+kick --split youtube")
+    p.add_argument("--sort", default="asc", choices=("asc", "desc"), help="asc: the biggest stream is at the bottom")
+    p.add_argument("--min-online", type=int, default=0, help="hide streams with fewer viewers")
+    p.add_argument("--exclude", action="append", metavar="NAME_OR_URL", help="never show this stream (repeatable)")
+    p.add_argument("--no-empty-message", action="store_true", help="do not post 'nobody is live'")
+    p.add_argument("--dry-run", action="store_true", help="print the message instead of sending it")
+
+
+def main(argv: Optional[List[str]] = None) -> None:
+    parser = argparse.ArgumentParser(prog="streamlens", description="Live streams in one Telegram message.")
+    parser.add_argument("--version", action="version", version=f"streamlens {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("send", help="publish streams from a JSON/CSV file (or - for stdin)")
+    p.add_argument("file")
+    _add_common(p)
+    p.set_defaults(func=cmd_send)
+
+    p = sub.add_parser("watch", help="check a list of channels every N minutes and publish who is live")
+    p.add_argument("channels", help="text file: one channel URL per line, optionally 'Name | URL'")
+    p.add_argument("--every", type=float, default=5, help="minutes between updates (default 5)")
+    p.add_argument("--once", action="store_true", help="run one update and exit (for cron)")
+    p.add_argument("--cookies", default=os.environ.get("STREAMLENS_YT_COOKIES"),
+                   help="YouTube cookies.txt, used only for age-restricted streams")
+    _add_common(p)
+    p.set_defaults(func=cmd_watch)
+
+    p = sub.add_parser("check", help="verify the token and that the bot can post to the chat")
+    p.add_argument("--token")
+    p.add_argument("--chat-id")
+    p.set_defaults(func=cmd_check)
+
+    p = sub.add_parser("clear", help="delete the messages posted by the bot (from the local state)")
+    _add_common(p)
+    p.set_defaults(func=cmd_clear)
+
+    args = parser.parse_args(argv)
+    try:
+        args.func(args)
+    except MissingDependency as e:
+        sys.exit(str(e))
+    except TelegramError as e:
+        sys.exit(f"telegram error: {e}")
+    except KeyboardInterrupt:
+        sys.exit(130)
+
+
+if __name__ == "__main__":
+    main()

streamlens/i18n.py

@@ -0,0 +1,35 @@
+"""Texts of the message. Add a language by adding a dict here."""
+from __future__ import annotations
+
+TEXTS = {
+    "en": {
+        "live_now": "🔴 Live now ({n})",
+        "nobody": "❌ Nobody is live right now",
+        "updated": "updated {time}",
+        "watch": "Watch stream",
+        "no_frames": "no frames yet",
+        "now": "now",
+        "min_ago": "min ago",
+        "days": "d",
+        "hours": "h",
+        "minutes": "min",
+    },
+    "ru": {
+        "live_now": "🔴 Сейчас в эфире ({n})",
+        "nobody": "❌ Сейчас никого нет в эфире",
+        "updated": "обновлено {time}",
+        "watch": "Смотреть стрим",
+        "no_frames": "кадров пока нет",
+        "now": "сейчас",
+        "min_ago": "мин назад",
+        "days": "дн",
+        "hours": "ч",
+        "minutes": "мин",
+    },
+}
+
+
+def texts(lang: str) -> dict:
+    if lang not in TEXTS:
+        raise ValueError(f"unknown lang {lang!r}, available: {', '.join(TEXTS)}")
+    return TEXTS[lang]

streamlens/message.py

@@ -0,0 +1,173 @@
+"""
+Building the message. Pure functions, no network and no state: easy to test and to reuse.
+
+The main format is a Telegram *rich message* (Bot API ``sendRichMessage``): platform groups, every stream is a
+collapsible block with a slideshow of frames "now / 5 / 10 / 15 / 20 min ago". ``build_text_message`` is a plain
+HTML fallback for bots/clients without rich messages.
+"""
+from __future__ import annotations
+
+import datetime as dt
+import html as html_lib
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from .i18n import texts
+from .models import Frame, Stream
+
+FRAMES_PER_STREAM = 5
+# Telegram limit: the 51st picture in one rich message fails with "Request Entity Too Large"
+MAX_MEDIA_PER_MESSAGE = 50
+
+PLATFORM_TITLES = (
+    ("youtube", "▶️ YOUTUBE"),
+    ("twitch", "🟣 TWITCH"),
+    ("kick", "🟢 KICK"),
+    ("vk", "🔵 VK VIDEO"),
+    ("other", "🌐 OTHER"),
+)
+
+RichMessage = Dict[str, object]
+Files = Dict[str, Tuple[str, bytes, str]]
+
+
+def esc(text: Optional[str]) -> str:
+    return html_lib.escape(text or "", quote=True)
+
+
+def fmt_num(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}M"
+    if n >= 10_000:
+        return f"{n / 1_000:.1f}k"
+    return str(n)
+
+
+def delta_str(diff: int) -> str:
+    if diff > 0:
+        return f"🟢 +{diff}"
+    if diff < 0:
+        return f"🔴 {diff}"
+    return "🟡 0"
+
+
+def format_duration(started_at: Optional[dt.datetime], now: dt.datetime, lang: str = "en") -> str:
+    """⏱️ how long the stream goes. 24/7 streams (years) are shown in days."""
+    if not started_at:
+        return ""
+    t = texts(lang)
+    minutes = max(0, int((now - started_at).total_seconds() // 60))
+    if minutes >= 24 * 60:
+        return f"⏱️{minutes // (24 * 60)} {t['days']}"
+    if minutes >= 60:
+        return f"⏱️{minutes // 60} {t['hours']} {minutes % 60:02d} {t['minutes']}"
+    return f"⏱️{minutes} {t['minutes']}"
+
+
+def ages_label(ages: Sequence[int], lang: str = "en") -> str:
+    """[0, 5, 10] -> '📷 now / 5 / 10 min ago'."""
+    t = texts(lang)
+    nums = [str(a) for a in ages]
+    if ages[0] <= 2:
+        nums[0] = t["now"]
+    suffix = "" if len(nums) == 1 and nums[0] == t["now"] else " " + t["min_ago"]
+    return "📷 " + " / ".join(nums) + suffix
+
+
+def plan_frames(streams: Sequence[Stream], per_stream: int = FRAMES_PER_STREAM,
+                max_media: int = MAX_MEDIA_PER_MESSAGE) -> Tuple[int, set]:
+    """
+    How many frames per stream and who gets them, to fit into the picture limit of one message.
+    Few streams: full slideshow for each; more: 4, 3, 2, then 1 frame; above the limit only the biggest streams
+    get a frame (``streams`` are sorted ascending, the biggest are last).
+    """
+    for per in range(per_stream, 0, -1):
+        if len(streams) * per <= max_media:
+            return per, {s.url for s in streams}
+    return 1, {s.url for s in streams[-max_media:]}
+
+
+def _summary(s: Stream) -> str:
+    text = f'📺 <b><a href="{esc(s.channel)}">{esc(s.name)}</a></b>'
+    if s.online is not None:
+        text += f" | {s.online} 👁"
+        if s.online_diff is not None:
+            text += f" {delta_str(s.online_diff)}"
+    return text
+
+
+def _stream_block(n: int, s: Stream, frames: Sequence[Frame], now: dt.datetime, lang: str,
+                  media: list, files: Files) -> str:
+    t = texts(lang)
+    if not frames:  # no frames yet (the stream has just appeared or a frame could not be taken)
+        credit = " · ".join(x for x in (esc(s.title), format_duration(s.started_at, now, lang)) if x)
+        tail = f" · {t['no_frames']}" + (f" · {credit}" if credit else "")
+        return (f'<details><summary>{_summary(s)}</summary>'
+                f'<p><a href="{esc(s.watch_url or s.channel)}">{t["watch"]}</a>{tail}</p></details>')
+
+    imgs = []
+    for k, f in enumerate(frames):
+        key = f"s{n}_{k}"
+        files[f"f_{key}"] = (f"{key}.jpg", f.image, "image/jpeg")
+        media.append({"id": key, "media": {"type": "photo", "media": f"attach://f_{key}"}})
+        imgs.append(f'<img src="tg://photo?id={key}"/>')
+
+    latest = frames[0]
+    title = s.title or latest.title
+    started = s.started_at or latest.started_at
+    credit = " · ".join(x for x in (
+        esc(title), format_duration(started, now, lang), ages_label([f.age_min for f in frames], lang)) if x)
+    link = latest.watch_url or s.watch_url or s.channel
+    return (f'<details><summary>{_summary(s)}</summary><tg-slideshow>{"".join(imgs)}'
+            f'<figcaption><a href="{esc(link)}">{t["watch"]}</a><cite>{credit}</cite></figcaption>'
+            f'</tg-slideshow></details>')
+
+
+def build_rich_message(streams: Sequence[Stream], frames: Dict[str, List[Frame]], now: dt.datetime,
+                       time_label: str, lang: str = "en") -> Tuple[RichMessage, Files]:
+    """
+    Returns ``(rich_message, files)`` for ``sendRichMessage``.
+    ``streams`` must be sorted already. ``frames`` maps stream url -> frames, newest first.
+    """
+    t = texts(lang)
+    footer = f"<footer>{t['updated'].format(time=time_label)}</footer>"
+    if not streams:
+        return {"html": f"<h3>{t['nobody']}</h3>{footer}"}, {}
+
+    per_stream, with_frames = plan_frames(streams)
+    media: list = []
+    files: Files = {}
+    blocks = []
+    numbered = list(enumerate(streams))
+    for key, title in PLATFORM_TITLES:
+        group = [(n, s) for n, s in numbered if s.platform == key]
+        if not group:
+            continue
+        total = sum(s.online or 0 for _, s in group)
+        blocks.append(f"<h4>{title} — {len(group)} • {fmt_num(total)}</h4>")
+        for n, s in group:
+            fr = frames.get(s.url, [])[:per_stream] if s.url in with_frames else []
+            blocks.append(_stream_block(n, s, fr, now, lang, media, files))
+
+    body = f"<h3>{t['live_now'].format(n=len(streams))}</h3>" + "".join(blocks) + footer
+    rich: RichMessage = {"html": body}
+    if media:
+        rich["media"] = media
+    return rich, files
+
+
+def build_text_message(streams: Sequence[Stream], time_label: str, lang: str = "en") -> str:
+    """Plain HTML for ``sendMessage``: the fallback when rich messages are not available."""
+    t = texts(lang)
+    footer = t["updated"].format(time=time_label)
+    if not streams:
+        return f"{t['nobody']}\n<i>{footer}</i>"
+    lines = [f"<b>{t['live_now'].format(n=len(streams))}</b>"]
+    for key, title in PLATFORM_TITLES:
+        group = [s for s in streams if s.platform == key]
+        if not group:
+            continue
+        lines += ["", f"<b>{title}</b> — {len(group)} • {fmt_num(sum(s.online or 0 for s in group))}"]
+        for s in group:
+            lines.append(_summary(s))
+    lines += ["", f"<i>{footer}</i>"]
+    return "\n".join(lines)

streamlens/models.py

@@ -0,0 +1,81 @@
+"""Data model: a live stream that you want to show in the chat."""
+from __future__ import annotations
+
+import datetime as dt
+from dataclasses import dataclass
+from typing import Optional
+from urllib.parse import urlparse
+
+PLATFORMS = ("youtube", "twitch", "kick", "vk", "other")
+
+_HOSTS = {
+    "youtube": ("youtube.com", "youtu.be"),
+    "twitch": ("twitch.tv",),
+    "kick": ("kick.com",),
+    "vk": ("vkvideo.ru", "vk.com", "vk.ru"),
+}
+
+
+def detect_platform(url: str) -> str:
+    """'youtube' | 'twitch' | 'kick' | 'vk' | 'other' by the URL host."""
+    host = (urlparse(url).hostname or "").lower()
+    for platform, domains in _HOSTS.items():
+        if any(host == d or host.endswith("." + d) for d in domains):
+            return platform
+    return "other"
+
+
+def channel_url(url: str) -> str:
+    """Channel link without the trailing /live."""
+    stripped = url.rstrip("/")
+    return stripped[: -len("/live")] if stripped.endswith("/live") else url
+
+
+@dataclass
+class Stream:
+    """
+    One live stream.
+
+    Only ``name`` and ``url`` are required. Everything else makes the message richer:
+
+    online       current viewers (``None`` if unknown, e.g. Kick without an API key)
+    online_diff  change vs. ~10 minutes ago; computed from the local state when omitted
+    image        JPEG/PNG bytes of a fresh frame; the last few are kept and shown as a slideshow
+    title        stream title
+    started_at   when the stream began (aware datetime, or naive = UTC); shown as duration
+    watch_url    direct link to the stream (defaults to ``url``)
+    platform     detected from ``url`` when omitted
+    """
+
+    name: str
+    url: str
+    online: Optional[int] = None
+    platform: Optional[str] = None
+    online_diff: Optional[int] = None
+    image: Optional[bytes] = None
+    title: Optional[str] = None
+    started_at: Optional[dt.datetime] = None
+    watch_url: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        if not self.platform:
+            self.platform = detect_platform(self.url)
+        if self.online is not None:
+            self.online = int(self.online)
+        if self.started_at is not None and self.started_at.tzinfo is None:
+            self.started_at = self.started_at.replace(tzinfo=dt.timezone.utc)
+
+    @property
+    def channel(self) -> str:
+        return channel_url(self.url)
+
+
+@dataclass
+class Frame:
+    """A stored frame of a stream; ``age_min`` is filled when it is loaded for a message."""
+
+    image: bytes
+    age_min: int = 0
+    watch_url: Optional[str] = None
+    title: Optional[str] = None
+    started_at: Optional[dt.datetime] = None

streamlens/publisher.py

@@ -0,0 +1,145 @@
+"""Publisher: takes the current list of streams and keeps the chat message(s) up to date."""
+from __future__ import annotations
+
+import datetime as dt
+import os
+from typing import Iterable, List, Optional, Sequence, Union
+from zoneinfo import ZoneInfo
+
+from .message import FRAMES_PER_STREAM, build_rich_message, build_text_message
+from .models import Stream
+from .state import State
+from .telegram import DryRunClient, TelegramClient, TelegramError
+
+FRAMES_WINDOW_MIN = 25  # frames older than this are not shown
+FRAMES_KEEP_MIN = 30    # ...and are deleted after this
+
+
+class Publisher:
+    """
+    >>> pub = Publisher(token="123:ABC", chat_id="-100123")
+    >>> pub.publish([Stream(name="Some channel", url="https://www.twitch.tv/some", online=1200)])
+
+    Call ``publish`` on a schedule (every ~5 minutes works best: that is the step between the frames of the
+    slideshow). Every call sends the new message first and then deletes the previous one, so a failed send never
+    leaves the chat empty.
+
+    token / chat_id   bot token and chat (a group, a channel where the bot is admin, or your own user id)
+    state             path of the SQLite file with message ids and frames (``":memory:"`` for none)
+    lang              ``"en"`` or ``"ru"``
+    tz                time zone of the "updated" footer, e.g. ``"Europe/Moscow"``
+    mode              ``"rich"`` rich message with frames, ``"text"`` plain text, ``"auto"`` rich with fallback to text
+    split             several messages instead of one, e.g. ``[["twitch", "kick"], ["youtube"]]``; the first one is
+                      posted first, the last one ends up at the bottom of the chat
+    sort              ``"asc"`` smaller streams first, the biggest at the bottom near the input field; or ``"desc"``
+    min_online        hide streams with fewer viewers (streams with unknown viewers are kept)
+    exclude           names or urls that are never shown
+    empty_message     post "nobody is live" when the list is empty (otherwise the old message is just removed)
+    dry_run           print instead of sending; nothing is sent to Telegram
+    """
+
+    def __init__(self, token: Optional[str] = None, chat_id: Union[str, int, None] = None, *,
+                 state: Union[str, os.PathLike] = "streamlens.db", lang: str = "en", tz: str = "UTC",
+                 mode: str = "auto", split: Optional[Sequence[Sequence[str]]] = None, sort: str = "asc",
+                 min_online: int = 0, exclude: Iterable[str] = (), empty_message: bool = True,
+                 dry_run: bool = False, client=None):
+        if mode not in ("auto", "rich", "text"):
+            raise ValueError("mode must be 'auto', 'rich' or 'text'")
+        if sort not in ("asc", "desc"):
+            raise ValueError("sort must be 'asc' or 'desc'")
+        if chat_id in (None, ""):
+            raise ValueError("chat_id is required")
+        self.chat_id = str(chat_id)
+        self.client = client or (DryRunClient() if dry_run else TelegramClient(token or ""))
+        self.state = State(state)
+        self.lang = lang
+        self.tzinfo = ZoneInfo(tz)
+        self.tz = tz
+        self.mode = mode
+        self.slots = [("+".join(g), tuple(g)) for g in split] if split else [("all", None)]
+        self.sort = sort
+        self.min_online = min_online
+        self.exclude = set(exclude)
+        self.empty_message = empty_message
+
+    # ------------------------------------------------------------------------------------------------------
+    def publish(self, streams: Sequence[Stream], now: Optional[dt.datetime] = None) -> List[int]:
+        """Updates the chat. Returns ids of the sent messages."""
+        now = now or dt.datetime.now(dt.timezone.utc)
+        streams = self._prepare(streams, now)
+        frames = self.state.load_frames([s.url for s in streams], now, FRAMES_WINDOW_MIN, FRAMES_PER_STREAM)
+        time_label = f"{now.astimezone(self.tzinfo):%H:%M} {self.tz if self.tz != 'UTC' else 'UTC'}"
+
+        sent: List[int] = []
+        for n, (slot, platforms) in enumerate(self.slots):
+            group = [s for s in streams if platforms is None or s.platform in platforms]
+            prev = self.state.last_message(self.chat_id, slot)
+
+            nobody_at_all = n == 0 and not streams and self.empty_message
+            if not group and not nobody_at_all:
+                if prev:
+                    self._drop(prev)
+                continue
+
+            message_id = self._send(group, frames, now, time_label)
+            self.state.remember_message(self.chat_id, slot, message_id, now)
+            sent.append(message_id)
+            if prev:  # new message first, old one after: a failed send keeps the old message
+                self._drop(prev)
+
+        self.state.prune(now, FRAMES_KEEP_MIN)
+        return sent
+
+    def clear(self) -> int:
+        """Deletes all messages the bot has posted to this chat (from the local state). Returns how many."""
+        count = 0
+        for slot, _ in self.slots:
+            prev = self.state.last_message(self.chat_id, slot)
+            if prev:
+                self._drop(prev)
+                count += 1
+        return count
+
+    # ------------------------------------------------------------------------------------------------------
+    def _prepare(self, streams: Sequence[Stream], now: dt.datetime) -> List[Stream]:
+        kept = [s for s in streams
+                if s.name not in self.exclude and s.url not in self.exclude
+                and (s.online is None or s.online >= self.min_online)]
+        seen, unique = set(), []
+        for s in kept:  # one entry per url
+            if s.url not in seen:
+                seen.add(s.url)
+                unique.append(s)
+
+        for s in unique:
+            if s.image:
+                self.state.add_frame(s.url, s.image, now, watch_url=s.watch_url, title=s.title,
+                                     started_at=s.started_at)
+            if s.online is not None:
+                if s.online_diff is None:
+                    before = self.state.online_before(s.url, now)
+                    if before is not None:
+                        s.online_diff = s.online - before
+                self.state.record_online(s.url, s.online, now)
+
+        unique.sort(key=lambda s: s.online or 0, reverse=self.sort == "desc")
+        return unique
+
+    def _send(self, group: Sequence[Stream], frames, now: dt.datetime, time_label: str) -> int:
+        if self.mode != "text":
+            rich, files = build_rich_message(group, frames, now, time_label, self.lang)
+            try:
+                return self.client.send_rich(self.chat_id, rich, files)["message_id"]
+            except TelegramError as e:
+                if self.mode == "rich" or e.error_code != 404:  # 404: this Bot API has no rich messages
+                    raise
+        return self.client.send_text(self.chat_id, build_text_message(group, time_label, self.lang))["message_id"]
+
+    def _drop(self, message_id: int) -> None:
+        self.client.delete(self.chat_id, message_id)
+        self.state.forget_message(self.chat_id, message_id)
+
+
+def publish(streams: Sequence[Stream], token: str, chat_id: Union[str, int], **options) -> List[int]:
+    """One-shot helper: ``publish(streams, token, chat_id, lang="ru")``. See :class:`Publisher` for options."""
+    return Publisher(token, chat_id, **options).publish(streams)

streamlens/sources.py

@@ -0,0 +1,212 @@
+"""
+Optional: find out by yourself which channels are live, with viewers and a fresh frame.
+Used by ``streamlens watch``; the core library does not need it (you can pass your own data to ``Publisher``).
+
+  YouTube  yt-dlp (``pip install streamlens[frames]``): live flag, viewers, title, start time, frame from the stream
+  Kick     yt-dlp: live flag, title, frame (Kick does not expose the viewer count without an API key)
+  Twitch   public preview picture (no key needed) shows that the channel is live and gives a frame;
+           viewers, title and start time need a free Twitch app: TWITCH_CLIENT_ID / TWITCH_CLIENT_SECRET
+"""
+from __future__ import annotations
+
+import datetime as dt
+import os
+import re
+import shutil
+import subprocess
+from concurrent.futures import ThreadPoolExecutor
+from typing import Dict, List, Optional, Sequence
+
+import requests
+
+from .models import Stream, detect_platform
+
+MIN_HEIGHT = 360  # enough for a preview and a small file
+AGE_GATE_MARK = "confirm your age"
+
+
+class MissingDependency(RuntimeError):
+    pass
+
+
+class _SilentLogger:
+    """yt-dlp prints 'ERROR: ... not currently live' for an offline channel; that is a normal answer for us."""
+
+    def debug(self, msg):
+        pass
+
+    warning = error = debug
+
+
+def _ytdlp():
+    try:
+        import yt_dlp
+    except ImportError:
+        raise MissingDependency("yt-dlp is required for YouTube/Kick: pip install 'streamlens[frames]'") from None
+    return yt_dlp
+
+
+def _ffmpeg() -> str:
+    path = shutil.which("ffmpeg")
+    if not path:
+        raise MissingDependency("ffmpeg is required for YouTube/Kick frames: https://ffmpeg.org/download.html")
+    return path
+
+
+def _utc(ts: Optional[float]) -> Optional[dt.datetime]:
+    return dt.datetime.fromtimestamp(ts, dt.timezone.utc) if ts else None
+
+
+def _clean_title(title: Optional[str]) -> str:
+    """yt-dlp appends the date and time to the title of live streams; drop it."""
+    return re.sub(r"\s\d{4}-\d{2}-\d{2} \d{2}:\d{2}$", "", title or "")
+
+
+# --- YouTube / Kick via yt-dlp -----------------------------------------------------------------------------------
+def _extract_info(url: str, cookies_file: Optional[str]) -> dict:
+    yt_dlp = _ytdlp()
+    opts = {"quiet": True, "no_warnings": True, "skip_download": True, "logger": _SilentLogger()}
+    if shutil.which("node"):  # JS runtime that YouTube extraction needs
+        opts["js_runtimes"] = {"node": {}}
+    try:
+        with yt_dlp.YoutubeDL(opts) as ydl:
+            return ydl.extract_info(url, download=False)
+    except yt_dlp.utils.DownloadError as e:
+        # cookies are used only when YouTube asks to confirm the age
+        if AGE_GATE_MARK not in str(e) or not cookies_file or not os.path.isfile(cookies_file):
+            raise
+    with yt_dlp.YoutubeDL({**opts, "cookiefile": cookies_file}) as ydl:
+        return ydl.extract_info(url, download=False)
+
+
+def probe_ytdlp(url: str, name: Optional[str] = None, cookies_file: Optional[str] = None) -> Optional[Stream]:
+    """A YouTube/Kick channel as a Stream with a frame, or None when it is not live."""
+    yt_dlp = _ytdlp()
+    try:
+        info = _extract_info(url, cookies_file)
+    except yt_dlp.utils.DownloadError as e:
+        if "not currently live" in str(e) or "not live" in str(e).lower() or "live event will begin" in str(e):
+            return None
+        raise
+    if not info.get("is_live"):
+        return None
+
+    formats = [f for f in info.get("formats", []) if f.get("vcodec") not in (None, "none") and f.get("height")]
+    if not formats:
+        return None
+    good = sorted((f for f in formats if f["height"] >= MIN_HEIGHT), key=lambda f: f["height"])
+    fmt = good[0] if good else max(formats, key=lambda f: f["height"])
+    proc = subprocess.run([_ffmpeg(), "-loglevel", "error", "-i", fmt["url"], "-frames:v", "1", "-q:v", "4",
+                           "-f", "image2", "-c:v", "mjpeg", "pipe:1"], capture_output=True, timeout=60)
+    image = proc.stdout if proc.returncode == 0 and proc.stdout else None
+
+    return Stream(
+        name=name or info.get("channel") or info.get("uploader") or info.get("uploader_id") or url,
+        url=url, online=info.get("concurrent_view_count"), image=image,
+        title=_clean_title(info.get("title")), watch_url=info.get("webpage_url"),
+        started_at=_utc(info.get("release_timestamp") or info.get("timestamp")))
+
+
+# --- Twitch --------------------------------------------------------------------------------------------------------
+def twitch_login(url: str) -> str:
+    return url.rstrip("/").rsplit("/", 1)[-1].lower()
+
+
+def twitch_preview(login: str, timeout: float = 15) -> Optional[bytes]:
+    """Public preview of a live channel. Offline channels redirect to a placeholder, then None."""
+    r = requests.get(f"https://static-cdn.jtvnw.net/previews-ttv/live_user_{login}-640x360.jpg", timeout=timeout)
+    if r.status_code != 200 or "404_preview" in r.url or not r.content:
+        return None
+    return r.content
+
+
+class TwitchApi:
+    """Helix API with client credentials (create a free app at https://dev.twitch.tv/console)."""
+
+    def __init__(self, client_id: str, client_secret: str, timeout: float = 15):
+        self.client_id, self.client_secret, self.timeout = client_id, client_secret, timeout
+        self._headers: Optional[dict] = None
+
+    def _auth(self) -> dict:
+        if not self._headers:
+            r = requests.post("https://id.twitch.tv/oauth2/token", timeout=self.timeout, data={
+                "client_id": self.client_id, "client_secret": self.client_secret, "grant_type": "client_credentials"})
+            r.raise_for_status()
+            self._headers = {"Client-ID": self.client_id, "Authorization": f"Bearer {r.json()['access_token']}"}
+        return self._headers
+
+    def live(self, logins: Sequence[str]) -> Dict[str, dict]:
+        """{login: helix stream item} for channels that are live now."""
+        result: Dict[str, dict] = {}
+        for i in range(0, len(logins), 100):
+            r = requests.get("https://api.twitch.tv/helix/streams", headers=self._auth(), timeout=self.timeout,
+                             params=[("user_login", x) for x in logins[i:i + 100]])
+            r.raise_for_status()
+            for item in r.json().get("data", []):
+                if item.get("type") == "live":
+                    result[item["user_login"].lower()] = item
+        return result
+
+
+def probe_twitch(channels: Sequence[Dict[str, str]], api: Optional[TwitchApi] = None) -> List[Stream]:
+    """channels: [{"name":..., "url":...}]. Returns the live ones."""
+    by_login = {twitch_login(c["url"]): c for c in channels}
+    live = api.live(list(by_login)) if api else {}
+    streams = []
+    for login, c in by_login.items():
+        item = live.get(login)
+        if api and not item:
+            continue
+        image = twitch_preview(login)
+        if not api and not image:  # without the API the preview is the only sign that the channel is live
+            continue
+        started = None
+        if item:
+            started = dt.datetime.fromisoformat(item["started_at"].replace("Z", "+00:00"))
+        streams.append(Stream(
+            name=c.get("name") or (item or {}).get("user_name") or login, url=c["url"], platform="twitch",
+            online=item["viewer_count"] if item else None, image=image,
+            title=(item or {}).get("title"), started_at=started, watch_url=f"https://www.twitch.tv/{login}"))
+    return streams
+
+
+# --- everything together -------------------------------------------------------------------------------------------
+def parse_channels(text: str) -> List[Dict[str, str]]:
+    """Lines of ``https://...`` or ``Name | https://...``; blank lines and ``#`` comments are ignored."""
+    channels = []
+    for raw in text.splitlines():
+        line = re.sub(r"\s+#.*$", "", raw.strip())
+        if not line or line.startswith("#"):
+            continue
+        name, _, url = line.rpartition("|")
+        channels.append({"name": name.strip(), "url": url.strip()})
+    return channels
+
+
+def probe_channels(channels: Sequence[Dict[str, str]], *, twitch: Optional[TwitchApi] = None,
+                   cookies_file: Optional[str] = None, workers: int = 2, log=print) -> List[Stream]:
+    """Which of the channels are live now. One broken channel never breaks the others."""
+    streams: List[Stream] = []
+    twitch_channels = [c for c in channels if detect_platform(c["url"]) == "twitch"]
+    others = [c for c in channels if detect_platform(c["url"]) in ("youtube", "kick")]
+    unsupported = [c for c in channels if c not in twitch_channels and c not in others]
+    for c in unsupported:
+        log(f"  ! {c['url']}: platform is not supported in watch mode, pass such streams to Publisher yourself")
+
+    try:
+        streams += probe_twitch(twitch_channels, twitch)
+    except Exception as e:
+        log(f"  ! twitch: {str(e)[:200]}")
+
+    def one(c: Dict[str, str]) -> Optional[Stream]:
+        try:
+            return probe_ytdlp(c["url"], c.get("name") or None, cookies_file)
+        except MissingDependency:
+            raise
+        except Exception as e:
+            log(f"  ! {c['url']}: {str(e)[:200]}")
+            return None
+
+    with ThreadPoolExecutor(max_workers=workers) as pool:
+        streams += [s for s in pool.map(one, others) if s]
+    return streams

streamlens/state.py

@@ -0,0 +1,100 @@
+"""
+Local state in one SQLite file (standard library, no server): ids of the messages the bot posted, the latest frames of
+every stream and a short history of viewer counts (to show the change over ~10 minutes).
+"""
+from __future__ import annotations
+
+import datetime as dt
+import os
+import sqlite3
+from typing import Dict, List, Optional, Sequence, Union
+
+from .models import Frame
+
+SCHEMA = """
+create table if not exists messages (
+    chat_id text not null, slot text not null, message_id integer not null, ts real not null
+);
+create table if not exists frames (
+    url text not null, ts real not null, image blob not null,
+    watch_url text, title text, started_at real
+);
+create index if not exists frames_url_ts on frames (url, ts desc);
+create table if not exists online (url text not null, ts real not null, online integer not null);
+create index if not exists online_url_ts on online (url, ts desc);
+"""
+
+
+def _ts(t: dt.datetime) -> float:
+    return t.timestamp()
+
+
+def _from_ts(x: Optional[float]) -> Optional[dt.datetime]:
+    return dt.datetime.fromtimestamp(x, dt.timezone.utc) if x is not None else None
+
+
+class State:
+    def __init__(self, path: Union[str, os.PathLike] = "streamlens.db"):
+        self.db = sqlite3.connect(str(path))
+        self.db.executescript(SCHEMA)
+
+    def close(self) -> None:
+        self.db.close()
+
+    # --- messages -------------------------------------------------------------------------------------------
+    def last_message(self, chat_id: str, slot: str) -> Optional[int]:
+        row = self.db.execute("select message_id from messages where chat_id=? and slot=? order by ts desc limit 1",
+                              (chat_id, slot)).fetchone()
+        return row[0] if row else None
+
+    def remember_message(self, chat_id: str, slot: str, message_id: int, now: dt.datetime) -> None:
+        self.db.execute("insert into messages values (?, ?, ?, ?)", (chat_id, slot, message_id, _ts(now)))
+        self.db.commit()
+
+    def forget_message(self, chat_id: str, message_id: int) -> None:
+        self.db.execute("delete from messages where chat_id=? and message_id=?", (chat_id, message_id))
+        self.db.commit()
+
+    # --- frames ---------------------------------------------------------------------------------------------
+    def add_frame(self, url: str, image: bytes, now: dt.datetime, *, watch_url: Optional[str] = None,
+                  title: Optional[str] = None, started_at: Optional[dt.datetime] = None,
+                  min_gap_min: float = 3) -> None:
+        """Stores a frame. A frame that is younger than ``min_gap_min`` is replaced, so quick reruns do not
+        fill the slideshow with duplicates."""
+        self.db.execute("delete from frames where url=? and ts > ?", (url, _ts(now) - min_gap_min * 60))
+        self.db.execute("insert into frames values (?, ?, ?, ?, ?, ?)",
+                        (url, _ts(now), image, watch_url, title, _ts(started_at) if started_at else None))
+        self.db.commit()
+
+    def load_frames(self, urls: Sequence[str], now: dt.datetime, window_min: float,
+                    limit: int) -> Dict[str, List[Frame]]:
+        """{url: [Frame, ...]}, newest first, at most ``limit`` per stream, younger than ``window_min``."""
+        result: Dict[str, List[Frame]] = {}
+        for url in urls:
+            rows = self.db.execute(
+                "select ts, image, watch_url, title, started_at from frames where url=? and ts > ? "
+                "order by ts desc limit ?", (url, _ts(now) - window_min * 60, limit)).fetchall()
+            if rows:
+                result[url] = [Frame(image=bytes(img), age_min=int(round((_ts(now) - ts) / 60)), watch_url=w,
+                                     title=title, started_at=_from_ts(st)) for ts, img, w, title, st in rows]
+        return result
+
+    # --- viewers history ------------------------------------------------------------------------------------
+    def record_online(self, url: str, online: int, now: dt.datetime) -> None:
+        self.db.execute("insert into online values (?, ?, ?)", (url, _ts(now), online))
+        self.db.commit()
+
+    def online_before(self, url: str, now: dt.datetime, min_age_min: float = 8,
+                      max_age_min: float = 20) -> Optional[int]:
+        """Viewer count from ~10 minutes ago (the freshest record within the window), or None."""
+        row = self.db.execute(
+            "select online from online where url=? and ts <= ? and ts >= ? order by ts desc limit 1",
+            (url, _ts(now) - min_age_min * 60, _ts(now) - max_age_min * 60)).fetchone()
+        return row[0] if row else None
+
+    # --- housekeeping ---------------------------------------------------------------------------------------
+    def prune(self, now: dt.datetime, frames_keep_min: float = 30) -> None:
+        self.db.execute("delete from frames where ts < ?", (_ts(now) - frames_keep_min * 60,))
+        self.db.execute("delete from online where ts < ?", (_ts(now) - 24 * 3600,))
+        self.db.execute("delete from messages where ts < ?", (_ts(now) - 3 * 24 * 3600,))
+        self.db.commit()

streamlens/telegram.py

@@ -0,0 +1,90 @@
+"""Minimal Telegram Bot API client (only what streamlens needs). The bot token never ends up in error messages."""
+from __future__ import annotations
+
+import json
+import time
+from typing import Any, Dict, Optional
+
+import requests
+
+API_BASE = "https://api.telegram.org"
+
+
+class TelegramError(RuntimeError):
+    def __init__(self, method: str, description: str, error_code: Optional[int] = None):
+        super().__init__(f"{method}: {description}")
+        self.method = method
+        self.description = description
+        self.error_code = error_code
+
+
+class TelegramClient:
+    def __init__(self, token: str, *, api_base: str = API_BASE, timeout: float = 120,
+                 session: Optional[requests.Session] = None):
+        if not token:
+            raise ValueError("Telegram bot token is empty")
+        self._url = f"{api_base.rstrip('/')}/bot{token}"
+        self.timeout = timeout
+        self.session = session or requests.Session()
+
+    def call(self, method: str, data: Optional[Dict[str, Any]] = None, files: Optional[dict] = None) -> Any:
+        for attempt in (1, 2):
+            try:
+                r = self.session.post(f"{self._url}/{method}", data=data, files=files or None, timeout=self.timeout)
+                payload = r.json()
+            except (requests.RequestException, ValueError) as e:
+                # do not chain: the original exception text contains the URL with the token
+                raise TelegramError(method, f"request failed ({type(e).__name__})") from None
+            if payload.get("ok"):
+                return payload["result"]
+            retry_after = (payload.get("parameters") or {}).get("retry_after")
+            if payload.get("error_code") == 429 and retry_after and attempt == 1 and retry_after <= 30:
+                time.sleep(retry_after + 1)
+                continue
+            raise TelegramError(method, payload.get("description", "unknown error"), payload.get("error_code"))
+
+    def get_me(self) -> dict:
+        return self.call("getMe")
+
+    def send_rich(self, chat_id: str, rich: dict, files: Optional[dict] = None) -> dict:
+        return self.call("sendRichMessage", {"chat_id": chat_id, "rich_message": json.dumps(rich)}, files)
+
+    def send_text(self, chat_id: str, html: str) -> dict:
+        return self.call("sendMessage", {"chat_id": chat_id, "text": html, "parse_mode": "HTML",
+                                         "disable_web_page_preview": True})
+
+    def delete(self, chat_id: str, message_id: int) -> None:
+        """Deleting is best effort: the message may be already gone or older than 48 hours."""
+        try:
+            self.call("deleteMessage", {"chat_id": chat_id, "message_id": message_id})
+        except TelegramError:
+            pass
+
+
+class DryRunClient:
+    """Prints what would be sent instead of sending. Used by ``--dry-run`` and in tests."""
+
+    def __init__(self, out=print):
+        self.out = out
+        self.sent: list = []
+        self._next_id = 1
+
+    def _id(self) -> dict:
+        self._next_id += 1
+        return {"message_id": self._next_id - 1}
+
+    def get_me(self) -> dict:
+        return {"username": "dry_run_bot"}
+
+    def send_rich(self, chat_id: str, rich: dict, files: Optional[dict] = None) -> dict:
+        self.sent.append(("rich", chat_id, rich, files or {}))
+        self.out(f"[dry-run] sendRichMessage to {chat_id}: {len(files or {})} picture(s)\n{rich['html']}")
+        return self._id()
+
+    def send_text(self, chat_id: str, html: str) -> dict:
+        self.sent.append(("text", chat_id, html, {}))
+        self.out(f"[dry-run] sendMessage to {chat_id}:\n{html}")
+        return self._id()
+
+    def delete(self, chat_id: str, message_id: int) -> None:
+        self.out(f"[dry-run] deleteMessage {message_id} in {chat_id}")

streamlens-0.1.0.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.5
+Name: streamlens
+Version: 0.1.0
+Summary: Live-stream tracker for Telegram: one auto-updating rich message with frames from YouTube, Twitch and Kick streams
+Project-URL: Homepage, https://github.com/klipbn/streamlens
+Project-URL: Issues, https://github.com/klipbn/streamlens/issues
+Project-URL: Changelog, https://github.com/klipbn/streamlens/blob/main/CHANGELOG.md
+Author: Alexey Voronko
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bot,kick,livestream,monitoring,telegram,twitch,youtube
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.9
+Requires-Dist: requests>=2.25
+Requires-Dist: tzdata; platform_system == 'Windows'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: frames
+Requires-Dist: yt-dlp[default]>=2025.1.1; extra == 'frames'
+Description-Content-Type: text/markdown
+
+# streamlens
+
+[![PyPI](https://img.shields.io/pypi/v/streamlens.svg?style=flat-square)](https://pypi.org/project/streamlens/)
+[![Python](https://img.shields.io/pypi/pyversions/streamlens.svg?style=flat-square)](https://pypi.org/project/streamlens/)
+[![CI](https://img.shields.io/github/actions/workflow/status/klipbn/streamlens/ci.yml?style=flat-square&label=tests)](https://github.com/klipbn/streamlens/actions)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](LICENSE)
+
+**Live streams in one Telegram message that keeps itself up to date.**
+Hand it a list of streams (or a list of channels) and a bot token; it posts who is live, how many viewers they have,
+how that changed, and a slideshow of frames from the last 20 minutes for each stream.
+
+- **No server, no database.** Pure Python; state is one small SQLite file.
+- **Bring your own data** (`Publisher.publish([...])`) **or let it watch channels** for you (`streamlens watch`).
+- **YouTube, Twitch, Kick** out of the box; any other platform if you pass the numbers yourself.
+- **Safe updates:** the new message is sent first, then the old one is deleted; a failed send never empties the chat.
+- English and Russian texts, time zone for the footer, size limits of Telegram handled for you.
+
+It grew out of a production Airflow + Postgres pipeline that tracks streams around the clock; this is the same
+message format, extracted into something you can `pip install`.
+
+## Quick start
+
+```bash
+pip install streamlens
+```
+
+You need a bot token from [@BotFather](https://t.me/BotFather) and a chat id. Add the bot to your group (or make it
+an admin of your channel) and check that it can post:
+
+```bash
+export STREAMLENS_TOKEN="123456:ABC..."
+export STREAMLENS_CHAT_ID="-1001234567890"   # group / channel id, or your own user id
+streamlens check
+```
+
+> How to find the chat id: add [@RawDataBot](https://t.me/RawDataBot) to the group, or open
+> `https://api.telegram.org/bot<TOKEN>/getUpdates` after writing anything to your bot.
+
+### 1. You have the data
+
+```python
+from streamlens import Publisher, Stream
+
+publisher = Publisher(token="123456:ABC...", chat_id="-1001234567890", lang="en", tz="Europe/Berlin")
+
+publisher.publish([
+    Stream(name="Some Twitch channel", url="https://www.twitch.tv/some_channel", online=12400),
+    Stream(name="Some YouTube channel", url="https://www.youtube.com/@some_channel/live", online=830,
+           title="Late night talk", image=open("frame.jpg", "rb").read()),
+])
+```
+
+Call `publish` every ~5 minutes (cron, Airflow, a loop). Only `name` and `url` are required; the platform is detected
+from the URL. Each call stores the frame you pass in `image`, so the slideshow *now / 5 / 10 / 15 / 20 min ago*
+builds up by itself. The change in viewers versus ~10 minutes ago is computed from the history the same way.
+
+From the shell, with a JSON or CSV file (or `-` for stdin):
+
+```bash
+streamlens send examples/streams.json
+cat streams.csv | streamlens send -          # columns: name,url,online[,title,image,started_at,...]
+streamlens send examples/streams.json --dry-run --chat-id 1   # print instead of sending
+```
+
+### 2. You only have channel links
+
+```bash
+pip install "streamlens[frames]"     # + ffmpeg on PATH, for YouTube/Kick frames
+streamlens watch examples/channels.txt --every 5
+```
+
+`channels.txt` is one URL per line (`Name | URL` to set a display name). Every 5 minutes it finds out who is live,
+grabs a frame and updates the message.
+
+| Platform | Live status | Viewers | Frame | Notes |
+|---|---|---|---|---|
+| YouTube | yt-dlp | yes | from the stream (ffmpeg) | use the channel `/live` URL |
+| Twitch | public preview | with a free [Twitch app](https://dev.twitch.tv/console): set `TWITCH_CLIENT_ID`, `TWITCH_CLIENT_SECRET` | public preview | works without keys, just no viewer count |
+| Kick | yt-dlp | no (Kick has no public count) | from the stream (ffmpeg) | pass your own numbers via `Publisher` if you have them |
+
+Age-restricted YouTube streams need a `cookies.txt` of a YouTube account (`--cookies`); it is used only for those.
+
+## Options
+
+| Option (`Publisher(...)` / CLI flag) | Default | What it does |
+|---|---|---|
+| `lang` / `--lang` | `en` | `en` or `ru` |
+| `tz` / `--tz` | `UTC` | time zone of the "updated" footer, e.g. `Europe/Moscow` |
+| `mode` / `--mode` | `auto` | `rich` (frames), `text` (plain), `auto` = rich, falls back to text if the Bot API has no rich messages |
+| `split` / `--split` | one message | several messages, e.g. `--split twitch+kick --split youtube` |
+| `sort` / `--sort` | `asc` | `asc`: the biggest stream ends up at the bottom, next to the input field |
+| `min_online` / `--min-online` | `0` | hide small streams |
+| `exclude` / `--exclude` | none | names or URLs that are never shown |
+| `state` / `--state` | `./streamlens.db` | where message ids and frames are kept |
+
+`streamlens clear` deletes the messages the bot posted. `--dry-run` works everywhere and never touches Telegram.
+
+## Deploy
+
+Anything that runs a command every few minutes works. Pick one.
+
+**Long-running process (systemd, tmux, a VPS):** `streamlens watch channels.txt --every 5`
+
+**cron:** `*/5 * * * * streamlens watch /path/channels.txt --once` (env vars in the crontab or an env file)
+
+**Docker:**
+
+```bash
+cp examples/channels.txt channels.local.txt        # edit
+printf 'STREAMLENS_TOKEN=...\nSTREAMLENS_CHAT_ID=...\n' > .env
+docker compose up -d
+```
+
+The image contains ffmpeg and Node.js (the JS runtime that yt-dlp needs for YouTube). State lives in a volume.
+
+**Existing pipeline (Airflow, a script):** import `Publisher` and call `publish()` with your data on your schedule.
+
+## Telegram limits it handles for you
+
+- One rich message takes at most 50 pictures. With many streams the frames per stream go 5 → 4 → 3 → 2 → 1, and above
+  50 streams only the biggest ones get a frame.
+- Telegram clients fold long rich messages behind "Show more" after roughly 20 pictures in the visible part. This is a
+  client behaviour; no Bot API setting for it is documented. Measured on real messages: the fewer frames per stream, the more streams stay visible before the fold.
+- Bot tokens never appear in error messages or logs.
+
+## Development
+
+```bash
+git clone https://github.com/klipbn/streamlens && cd streamlens
+pip install -e ".[dev,frames]"
+pytest && ruff check .
+```
+
+MIT © Alexey Voronko. Russian version: [README.ru.md](README.ru.md).

streamlens-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+streamlens/__init__.py,sha256=h7A2EkhceHO_MtKgsnlP4RH5Nrf1wYVXVX_3Jws2cRQ,461
+streamlens/cli.py,sha256=R8-xhBbV-aX3Sqt46Vqg3-gNP27Lq-J-Fd_i3Bj2wzc,8516
+streamlens/i18n.py,sha256=Xct2rY3JzsPZ7JrGwhRnStC6oRyUMZ35cxSrxIE1g3g,1066
+streamlens/message.py,sha256=iCehpzMZ0WTUCMhMYexwMEGnAl072DrvBpaHsjUs0PI,6747
+streamlens/models.py,sha256=Yu_WEfYVTZGoTulePgAc4EwlsKHAChBreJMVJ8TFwAQ,2607
+streamlens/publisher.py,sha256=gC8MmrPxY68MAGNjQ_2TMF7LLenj9IdCJMLzYO6uIxc,7362
+streamlens/sources.py,sha256=m-7CyyzlHdp1t14A74Yo8JgpZB0-nOXs5N-qP4vUBQM,9322
+streamlens/state.py,sha256=hoG_BV6VQCMzFBTdTFifP8rohGMB-lJlnTrgnJAWrYg,5100
+streamlens/telegram.py,sha256=4cFD2V9zmhxK-RfPcbQjfGSJOSoyEACt3gELdvJTlok,3776
+streamlens-0.1.0.dist-info/METADATA,sha256=zv3mCJ6BUHXyl-5ZyVN0e8gXAvjk9VWaC2RdcyGe4ek,7657
+streamlens-0.1.0.dist-info/WHEEL,sha256=THafob7ofN-NsuMN7Mg4qZyHaQI7KkD-QlcQatYhXPo,87
+streamlens-0.1.0.dist-info/entry_points.txt,sha256=L30qJy98Ah1QwJMPrXmFInDOOnjMWClpQIGP0ErKad0,51
+streamlens-0.1.0.dist-info/licenses/LICENSE,sha256=b-ZbQXBE550xg9jmMQDaT5cN5of_fRGnGGBMtJqVtEo,1071
+streamlens-0.1.0.dist-info/RECORD,,

streamlens-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.3
+Root-Is-Purelib: true
+Tag: py3-none-any

streamlens-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+streamlens = streamlens.cli:main

streamlens-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexey Voronko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.