anchorless 1.0.0__py3-none-any.whl

anchorless/__init__.py

@@ -0,0 +1,8 @@
+"""Anchorless: a 24/7 text newscast for IPTV."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("anchorless")     # one source of truth: pyproject.toml
+except PackageNotFoundError:                 # running from a source tree that isn't installed
+    __version__ = "0+unknown"

anchorless/breaking.py

@@ -0,0 +1,61 @@
+"""Deciding when a story is big and new enough to interrupt the rundown."""
+
+from __future__ import annotations
+
+import logging
+from datetime import datetime, timedelta
+
+from .config import BreakingConfig
+from .models import Cluster
+from .store import Store
+from .text import similarity
+
+log = logging.getLogger(__name__)
+_logged: set[str] = set()   # local stories already logged in "log" mode
+
+
+def _prefixed(cluster: Cluster, prefixes: list[str]) -> bool:
+    return any((s.raw_title or s.title).upper().startswith(p.upper()) for s in cluster.stories for p in prefixes)
+
+
+def _already_alerted(cluster: Cluster, alerts: list[tuple[str, set[str], datetime]]) -> bool:
+    keys = {s.key for s in cluster.stories} | {cluster.key}
+    return any(k in keys or similarity(cluster.tokens, tokens) >= 0.5 for k, tokens, _ in alerts)
+
+
+def pick_breaking(clusters: list[Cluster], cfg: BreakingConfig, store: Store, now: datetime) -> Cluster | None:
+    """The story to break in with now, if any (and record it so it is never repeated).
+
+    A story qualifies when it appeared within ``window_minutes`` and either at
+    least ``min_sources`` outlets already carry it, or a headline is marked
+    "BREAKING:". At most one alert per ``cooldown_minutes``. A story only local
+    outlets carry needs ``local_min_sources`` of them instead.
+    """
+    if not cfg.enabled:
+        return None
+    last = store.last_alert_at()
+    if last and now - last < timedelta(minutes=cfg.cooldown_minutes):
+        return None
+    window = timedelta(minutes=cfg.window_minutes)
+    alerts = store.alerts()
+    for cluster in clusters:  # best first
+        when = cluster.when
+        if when is None or now - when > window:
+            continue
+        local = all(s.scope == "local" for s in cluster.stories)
+        if local and cfg.local_alerts == "off":
+            continue
+        need = cfg.local_min_sources if local else cfg.min_sources
+        if len(cluster.outlets) < need and not _prefixed(cluster, cfg.title_prefixes):
+            continue
+        if _already_alerted(cluster, alerts):
+            continue
+        if local and cfg.local_alerts == "log":
+            if cluster.key not in _logged:
+                _logged.add(cluster.key)
+                log.info("local story would break in (local_alerts = log): %s (%s)",
+                         cluster.lead.title, ", ".join(cluster.outlets))
+            continue
+        store.record_alert(cluster.key, cluster.lead.title, cluster.tokens, now)
+        return cluster
+    return None

anchorless/cli.py

@@ -0,0 +1,230 @@
+"""Command line: anchorless init | serve | fetch | render | preview | ..."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import logging
+import os
+import sys
+from datetime import datetime
+from pathlib import Path
+
+from . import __version__
+from .config import Config, ConfigError, config_path, load_config
+
+
+def _age(when: datetime | None, now: datetime) -> str:
+    if when is None:
+        return "  ?  "
+    minutes = int((now - when).total_seconds() // 60)
+    return f"{minutes:3d}m" if minutes < 120 else f"{minutes // 60:3d}h"
+
+
+async def _fetch(cfg: Config, as_json: bool) -> int:
+    from .newsroom import Newsroom
+
+    room = Newsroom(cfg)
+    rundown = await room.refresh()
+    now = rundown.built_at
+    if as_json:
+        print(json.dumps({
+            "built_at": now.isoformat(),
+            "segments": [{
+                "name": seg.name,
+                "stories": [{
+                    "title": c.lead.title, "summary": c.lead.summary, "outlets": c.outlets,
+                    "url": c.lead.url, "when": c.when.isoformat() if c.when else None,
+                    "score": round(c.score, 3),
+                } for c in seg.clusters],
+            } for seg in rundown.segments],
+            "feeds": room.feed_status(),
+        }, indent=2))
+        return 0
+    for seg in rundown.segments:
+        print(f"\n== {seg.name}")
+        for c in seg.clusters:
+            print(f"  {_age(c.when, now)}  [{len(c.outlets)}] {c.lead.title}")
+            print(f"         {', '.join(c.outlets)}")
+    failed = [f for f in room.feed_status() if f["error"]]
+    print(f"\n{sum(f['stories'] for f in room.feed_status())} stories from {len(cfg.source)} feeds", end="")
+    print(f", {len(failed)} failed:" if failed else "")
+    for f in failed:
+        print(f"  {f['name']} {f['url']}: {f['error']}")
+    return 0
+
+
+async def _headlines(cfg: Config, dump: str | None) -> int:
+    """Every story several outlets carry: each version, its score and why."""
+    from datetime import UTC, datetime
+
+    from . import headline
+    from .pipeline import all_clusters
+    from .sources.rss import RssFetcher
+
+    now = datetime.now(UTC)
+    stories = await RssFetcher().fetch_all(cfg.source, cfg.feeds.allow_private)
+    clusters = all_clusters(stories, cfg, now)
+    rows = []
+    for c in clusters:
+        choice = headline.choose(c, cfg.rundown.headline_margin)
+        if choice is None:
+            continue
+        local = any(s.scope == "local" for s in c.stories)
+        print(f"\n[{len(c.outlets)} outlets] {'CHANGED' if choice.changed else 'kept'}"
+              + (f" - {choice.reason}" if choice.changed else ""))
+        for x in sorted(choice.scores, key=lambda x: -x.total):
+            mark = ">" if x.story is choice.chosen else ("d" if x.story is choice.default else " ")
+            print(f"  {mark} {x.total:5.2f}  {x.story.outlet[:18]:18}  {x.story.title[:90]}")
+            print(f"           {x.why()}")
+        if dump and not local:      # local stories would say where you live
+            rows.append({"when": now.isoformat(timespec="seconds"), "key": c.key, "changed": choice.changed,
+                         "chosen": choice.chosen.key, "default": choice.default.key, "versions": [
+                             {"key": x.story.key, "outlet": x.story.outlet, "title": x.story.title,
+                              "summary": x.story.summary, "scope": x.story.scope, "total": round(x.total, 3),
+                              "corroboration": round(x.corroboration, 3), "coverage": round(x.coverage, 3),
+                              "penalties": x.penalties} for x in choice.scores]})
+    if dump:
+        with open(dump, "a", encoding="utf-8") as f:
+            for r in rows:
+                f.write(json.dumps(r) + "\n")
+        print(f"\n{len(rows)} stories appended to {dump}", file=sys.stderr)
+    return 0
+
+
+def _hash_password(from_stdin: bool) -> int:
+    import getpass
+
+    from .passwords import MIN_LENGTH, hash_password
+    if from_stdin:
+        password = sys.stdin.readline().rstrip("\n")
+    else:
+        password = getpass.getpass(f"Settings password (at least {MIN_LENGTH} characters): ")
+        if getpass.getpass("Again: ") != password:
+            print("The two passwords differ.", file=sys.stderr)
+            return 2
+    try:
+        hashed = hash_password(password)
+    except ValueError as err:
+        print(err, file=sys.stderr)
+        return 2
+    print("Put this in config.toml (and remove any [admin] password / ANCHORLESS__ADMIN__PASSWORD):\n",
+          file=sys.stderr)
+    print(f'[admin]\npassword_hash = "{hashed}"')
+    return 0
+
+
+def _init(folder: Path, force: bool) -> int:
+    from .examples import init
+
+    try:
+        written = init(folder, force)
+    except FileExistsError as err:
+        print(err, file=sys.stderr)
+        return 1
+    for path in written:
+        print(f"wrote {path}")
+    here = "" if folder.resolve() == Path.cwd() else f"cd {folder} && "
+    print(f"""
+Next:
+  1. Look through config.toml: every setting is explained there. The defaults work.
+     Local news: set ANCHORLESS__LOCATION__CITY and list your outlets' feeds
+     (see local.example.toml).
+  2. Start it:   {here}anchorless serve
+  3. Watch at http://localhost:9798/ or add http://<this host>:9798/playlist.m3u
+     to Jellyfin, Plex or any IPTV player as an M3U tuner.
+
+Needs ffmpeg on the PATH.""")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="anchorless", description="A 24/7 text newscast for IPTV.")
+    parser.add_argument("--version", action="version", version=f"anchorless {__version__}")
+    parser.add_argument("-c", "--config", help="config file (default: $ANCHORLESS_CONFIG or ./config.toml)")
+    parser.add_argument("-v", "--verbose", action="store_true")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("fetch", help="fetch the sources once and print the rundown")
+    p.add_argument("--json", action="store_true")
+
+    p = sub.add_parser("render", help="write PNG stills of each page type")
+    p.add_argument("-o", "--out", default="out", help="output directory (default: out)")
+    p.add_argument("-t", "--theme", choices=["studio", "classic", "classic-light", "classic-dark"], help="default: the configured theme")
+
+    p = sub.add_parser("preview", help="write a short MP4 of the channel")
+    p.add_argument("-o", "--out", default="out/preview.mp4")
+    p.add_argument("-s", "--seconds", type=float, default=60)
+    p.add_argument("--breaking", action="store_true", help="start with a (sample) breaking-news alert")
+    p.add_argument("-t", "--theme", choices=["studio", "classic", "classic-light", "classic-dark"], help="default: the configured theme")
+
+    p = sub.add_parser("init", help="write a starter config.toml (and local.example.toml) to get going")
+    p.add_argument("folder", nargs="?", default=".", help="where to write it (default: here)")
+    p.add_argument("--force", action="store_true", help="replace an existing config.toml")
+    p = sub.add_parser("serve", help="run the channel: /playlist.m3u, /guide.xml, /live.ts, /health")
+    p.add_argument("--init", action="store_true",
+                   help="first write a starter config if there is none (the container image does this)")
+    sub.add_parser("check-config", help="validate the config and print it")
+    p = sub.add_parser("headlines", help="each version of every multi-outlet story, scored (consensus headline)")
+    p.add_argument("--dump", help="append the stories (not local ones) to this JSONL file, for calibration")
+    p = sub.add_parser("hash-password", help="make a password_hash for [admin] (the settings page)")
+    p.add_argument("--stdin", action="store_true", help="read the password from standard input")
+
+    args = parser.parse_args(argv)
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s %(levelname)-7s %(name)s: %(message)s", stream=sys.stderr,
+    )
+    if not args.verbose:
+        logging.getLogger("httpx").setLevel(logging.WARNING)
+    if args.command == "hash-password":           # needs no config: you run it while writing one
+        return _hash_password(args.stdin)
+    if args.command == "init":
+        return _init(Path(args.folder), args.force)
+    if args.command == "serve" and args.init:
+        target = Path(args.config or os.environ.get("ANCHORLESS_CONFIG") or "config.toml")
+        if not target.exists():
+            from .examples import init
+
+            init(target.parent, filename=target.name)
+            logging.getLogger("anchorless").info("wrote a starter config to %s", target)
+        args.config = str(target)
+    try:
+        cfg = load_config(args.config)
+        cfg_path = Path(args.config) if args.config else config_path()
+    except ConfigError as err:
+        print(err, file=sys.stderr)
+        return 2
+
+    if args.command == "check-config":
+        shown = cfg.model_copy(deep=True)
+        if shown.admin.password:
+            shown.admin.password = "<set>"           # never print the settings password
+        if shown.admin.password_hash:
+            shown.admin.password_hash = "<set>"
+        print(shown.model_dump_json(indent=2))
+        return 0
+    if args.command == "headlines":
+        return asyncio.run(_headlines(cfg, args.dump))
+    if args.command == "fetch":
+        return asyncio.run(_fetch(cfg, args.json))
+    if args.command == "render":
+        from .render.stills import write_stills
+
+        return asyncio.run(write_stills(cfg, Path(args.out), args.theme))
+    if args.command == "preview":
+        from .stream.preview import write_preview
+
+        if args.theme:
+            cfg.channel.theme = args.theme
+        return asyncio.run(write_preview(cfg, Path(args.out), args.seconds, args.breaking))
+    if args.command == "serve":
+        from .stream.server import serve
+
+        return serve(cfg, cfg_path)
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

anchorless/config.example.toml

@@ -0,0 +1,175 @@
+# Anchorless configuration.
+#
+# Copy this to config.toml and change what you like. In [channel], theme and
+# show_on are required (and channel_number for a TV channel); every other
+# setting is optional, and anything left out uses the default shown here.
+#
+# Any setting can also come from the environment as ANCHORLESS__<SECTION>__<KEY>,
+# e.g. ANCHORLESS__LOCATION__CITY=Springfield. Use that for anything personal
+# (like your location) so this file can be shared.
+
+[channel]
+theme = "studio"              # required: "studio" (pixel-art news set), "classic-light" / "classic-dark"
+                              # (cable-news pages), or "classic" (light by day, dark at night)
+name = "NEWS"                 # shown in the logo and in your TV guide (default "NEWS")
+show_on = "both"              # required: "both" (TV + web page), "tv" (TV only) or "web" (web page only)
+channel_number = 101          # required for "both" and "tv" (e.g. 2, 101, 2.1); ignored for "web"
+# id = "anchorless.news"      # stable id for TV guides (tvg-id) and the stream URL
+timezone = "America/Chicago"  # for the on-screen clock and the guide
+guide_title = "Anchorless News"
+guide_description = "Around-the-clock headlines from national and world news outlets."
+guide_slot_minutes = 30        # guide blocks on :00/:30; 1440 = one per day
+
+[location]
+# Local news. Best set from the environment instead (ANCHORLESS__LOCATION__CITY=...),
+# so this file names no place:
+# city = "Springfield"        # the local segment's title
+# sources_file = "local.toml" # your local outlets' feeds (see local.example.toml),
+#                             # relative to this file. No file = no local segment.
+
+[video]
+width = 854
+height = 480
+fps = 24
+encoder = "x264"              # "x264" (CPU) or "vaapi" (Intel/AMD GPU)
+vaapi_device = "/dev/dri/renderD128"
+vaapi_rc = "vbr"              # "cqp" for older Intel GPUs (i965 driver) that reject bitrates
+vaapi_qp = 24                 # quality for "cqp" (lower = better)
+vaapi_convert = "cpu"         # "gpu" converts colours on the GPU too (less CPU; newer Intel drivers)
+bitrate = "1500k"
+maxrate = "2000k"
+gop_seconds = 2               # a keyframe every 2 s: how fast a joining viewer can start
+x264_preset = "veryfast"
+x264_threads = 0              # 0 = automatic
+
+[audio]
+music_dir = "/music"          # background music (.mp3), shuffled; missing folder = silence
+volume = 0.5
+bitrate = "128k"
+
+[stream]
+host = "0.0.0.0"
+port = 9798
+lead_seconds = 10             # rendered ahead for a new viewer (Samsung TVs buffer ~10 s)
+idle_seconds = 60             # stop encoding this long after the last viewer leaves
+max_sessions = 2              # channels encoding at once (~30% of a CPU core each); -1 = no limit,
+                              # 0 = listed but nobody can watch. Viewers of a channel already on don't count.
+max_viewers = -1              # viewers at once, all channels (TV, web, iPhone); -1 = no limit, 0 = nobody
+max_viewers_per_client = -1   # viewers from one address; -1 = no limit. Jellyfin (all its viewers
+                              # come from it) and a household behind one router are one address each.
+
+[web]                         # the viewer page; the TV side (playlist, guide, streams) is never https-only
+require_https = false         # true: viewer page only over https. Suggested if you have https - and
+                              # keep [admin] require_https on too.
+public_status = "full"        # "full": /health and the viewer page list feeds by name and site;
+                              # "summary": counts only. URLs and error details: settings page only.
+
+[rundown]
+refresh_minutes = 10          # how often the sources are fetched
+page_seconds = 12             # how long each story stays on screen
+intro_seconds = 5             # segment title card (0 = none)
+transition_seconds = 0.4      # crossfade between pages (0 = cut)
+max_story_age_hours = 12
+same_story_similarity = 0.5   # headline overlap that makes two items the same story
+same_story_text_similarity = 0.32
+
+# The newscast: segments play in order, then it loops. A story appears in the
+# first segment it fits and nowhere else. Leave out scope/category to take any story.
+# When several outlets carry a story, whose headline is shown: "first" (first
+# published), "consensus" (if that one has a red flag - loaded words, shouting, or
+# wording no other outlet shares - a clean version the others agree with), or "log"
+# (show "first"; list what consensus would change, on the settings page and in the log).
+headline_choice = "log"
+headline_margin = 0.15        # how much better a version must score to replace the shown one
+
+[[rundown.segment]]
+name = "TOP STORIES"
+stories = 4
+exclude_scope = ["local"]     # local-only stories stay in the local segment
+
+[[rundown.segment]]
+name = "{city}"                # the local segment, titled with [location] city
+stories = 3
+scope = "local"
+
+[[rundown.segment]]
+name = "NATIONAL"
+stories = 3
+scope = "national"            # local | national | world
+
+[[rundown.segment]]
+name = "WORLD"
+stories = 3
+scope = "world"
+
+[[rundown.segment]]
+name = "BUSINESS"
+stories = 2
+category = "business"
+
+[breaking]
+enabled = true
+min_sources = 4               # outlets that must carry a story...
+window_minutes = 30           # ...within this long of its first appearance
+cooldown_minutes = 20         # at most one alert per this long
+crawl_tag_minutes = 60        # how long it keeps the red BREAKING tag in the crawl
+title_prefixes = ["BREAKING:", "BREAKING NEWS:"]
+local_min_sources = 5         # a story only local outlets carry needs this many
+local_alerts = "on"           # "on", "log" (only log what would break in), or "off"
+sound = "auto"                # "auto", "chiptune", "news", "none", or a sound file's path
+sound_volume = 0.8            # the music ducks under it either way
+
+[crawl]                       # the headline crawl along the bottom, on every channel
+label = "HEADLINES"
+speed = 96                    # pixels per second at 480 lines
+
+# More channels from the same news (one fetch feeds them all). The settings are
+# the same as [channel], except that name is required here. Each channel gets its
+# own stream, drawn and encoded only while someone watches it. Add as many as you like.
+#
+# [[extra_channel]]
+# theme = "classic"
+# name = "NEWS CLASSIC"       # required for an extra channel
+# show_on = "web"
+# channel_number = 99         # ignored: show_on is "web"
+#
+# [[extra_channel]]
+# theme = "studio"
+# name = "NEWS 2"
+# show_on = "tv"
+# channel_number = 102
+
+[data]
+dir = "data"                  # SQLite memory of stories already seen
+
+# Feeds. Anchorless comes with a list of national and world outlets (NPR, NYT,
+# CBS, ABC, NBC, Fox, Guardian, BBC, Al Jazeera, CNBC). [[source]] entries are
+# added to that list; turn any feed off by its URL. Feeds with the same name
+# count as one outlet. scope: national | world (local feeds go in the local
+# feeds file, see [location]). exclude: regular expressions; matching
+# headlines or links are skipped.
+[feeds]
+builtin = true                # false: only your [[source]] entries
+disabled = []                 # feed URLs to skip, e.g. ["https://feeds.npr.org/1001/rss.xml"]
+allow_private = false         # true: allow feeds on your own network. Off, every feed request
+                              # (redirects too) must go to a public address - so a URL typed
+                              # into the settings page can't point the server at your router etc.
+
+# [[source]]
+# name = "Reuters"
+# url = "https://example.com/reuters/rss.xml"
+# scope = "world"
+# category = "general"        # "business" feeds the BUSINESS segment
+
+# The settings page (/settings) edits this file. It is off until a password is
+# set (12+ characters): either from the environment, ANCHORLESS__ADMIN__PASSWORD=...,
+# or as a hash here - run `anchorless hash-password` and paste its line:
+# password_hash = "scrypt$15$8$1$...$..."
+# The file must be writable by Anchorless (in Docker: mount its folder, not the file).
+[admin]
+allow_from = ["127.0.0.0/8", "::1/128", "10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16",
+              "100.64.0.0/10", "fc00::/7", "fe80::/10"]   # who may open the settings page
+trusted_proxies = []          # e.g. ["192.168.1.2"]: your reverse proxy, so X-Forwarded-For is believed
+session_days = 30             # how long a login lasts
+require_https = true          # log in only over https (TLS, or a trusted proxy's X-Forwarded-Proto);
+                              # localhost is always allowed. false only on a network you trust.