kryten-webqueue 0.31.0__tar.gz → 0.32.1__tar.gz

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.32.1] — 2026-07-09
+
+### Added
+
+- **Admin controls to test recently-played hiding in situ** without waiting for real playback:
+  - `POST /admin/catalog/{token}/mark-played` — simulates a genuine completion via the same `record_play_completion` the poll loop uses, so it also exercises the mutable-playlist pass logic (marking episodes, resetting on the last item).
+  - `POST /admin/catalog/{token}/clear-played` — removes an item's completion and playlist-pass rows so it reappears for regular users immediately.
+  - `GET /admin/catalog/recently-played/debug` — read-only snapshot of exactly what regular users are not seeing and why (time-window vs mutable-playlist pass).
+  - The admin catalog browser gains **Mark played** and **Clear played** buttons per item.
+
+## [0.32.0] — 2026-07-09
+
+### Added
+
+- **Hide recently-played items from the public catalog.** Regular users no longer see a title in browse/search for a configurable window after it has actually finished playing. Admins (rank ≥ 3) always see every title. The window is set by `catalog_recently_played_hide_days` (default `21`; `0` disables).
+  - **Based on genuine play-completion, not queue time.** A new `CompletionRecorder` runs in the poll loop and records a completion only when the now-playing pointer advances off an item that played past ~50% of its duration (`play_completions` table). This means an item that was pay-to-queued and then **refunded/removed by an admin before it played never counts as played**, and an early admin *skip* of the currently-playing item doesn't either.
+  - **Mutable playlists (TV-show collections) are handled as a unit.** Short (< 1 hour) episodes of a mutable playlist are governed by playlist position instead of the day window: each hides as it plays, and reaching the playlist's **last item** releases the whole collection at once (`playlist_item_played` table). This lets admins append S2/S3 to a show without re-hiding S1 piecemeal or over-playing season 1. Longer items (e.g. a movie) inside a mutable playlist still follow the normal completion + day-window rule.
+  - **Firing a mutable playlist skips episodes already played in the current pass.** `fire_schedule` (scheduled or manual "fire now"), including the appended fallback playlist, now omits already-played episodes so a re-fire continues where the pass left off instead of replaying from the start. Once the last item plays the pass resets and the next fire loads the full playlist again. Immutable/promo playlists are unaffected.
+  - **Manual "import playlist to live queue" honors the same skip, with an override.** Importing a saved playlist now skips already-played episodes by default (matching automated firing); pass `?full=1` on the import endpoint to force-load the entire list regardless of pass state. Automated use (a playlist attached to a schedule as a fallback) always observes the played/non-played rules. The playlist editor exposes both as **Import to Live** (skip played) and **Load Entire List** (full) buttons.
+  - Promos are unaffected — promo/immutable-playlist items are already excluded from the public catalog.
+
+[0.32.0]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.32.0
+[0.32.1]: https://github.com/grobertson/kryten-webqueue/releases/tag/v0.32.1
+
 ## [0.31.0] — 2026-07-04
 
 ### Fixed

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kryten-webqueue
-Version: 0.31.0
+Version: 0.32.1
 Summary: Netflix/Tubi-style catalog browser and pay-to-play queue management for CyTube
 Author: grobertson
 License-Expression: MIT

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/config.example.json

@@ -60,6 +60,7 @@
   "catalog_sync_interval_hours": 4,
   "pre_fire_lock_minutes_default": 15,
   "state_poll_interval_sec": 3.0,
+  "catalog_recently_played_hide_days": 21,
 
   "playlist_bulk_add_delay_sec": 0.5,
   "playlist_bulk_add_max_retries": 2,

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/app.py

@@ -16,6 +16,7 @@ from .jobs import JobManager
 from .catalog.images import CoverArtResolver
 from .queue.shadow import QueueShadow
 from .queue.poller import StatePoller
+from .queue.completion import CompletionRecorder
 from .queue.race_poller import RacePoller
 from .queue.presence import PresenceRefundMonitor
 from .promos.director import PromoDirector
@@ -138,6 +139,11 @@ async def lifespan(app: FastAPI):
     )
     app.state.promo_director = promo_director
 
+    # Play-completion recorder (poller-driven; records genuine completions that
+    # drive hiding recently-played catalog items from regular users).
+    completion_recorder = CompletionRecorder(db=db)
+    app.state.completion_recorder = completion_recorder
+
     # State poller
     poller = StatePoller(
         api_gate=api_gate,
@@ -146,6 +152,7 @@ async def lifespan(app: FastAPI):
         db=db,
         interval=config.state_poll_interval_sec,
         promo_director=promo_director,
+        completion_recorder=completion_recorder,
     )
     await poller.start()
     app.state.poller = poller

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/catalog/db/_catalog.py

@@ -72,6 +72,40 @@ def _hidden_exclusion(alias: str = "c") -> tuple[str, list]:
     return sql, [*HIDDEN_CATEGORY_NAMES, *HIDDEN_TAG_NAMES]
 
 
+def _recently_played_exclusion(alias: str, days: int) -> tuple[str, list]:
+    """SQL fragment (+ params) hiding recently-played items from regular users.
+
+    Two independent signals hide an item; either one is enough:
+
+    1. **Time window** — the item has a genuine ``play_completions`` row within
+       the last ``days`` days. A completion is only recorded when an item
+       actually played past a threshold (see ``CompletionRecorder``), so an item
+       that was queued and then refunded/removed before playing never counts.
+
+    2. **Mutable-playlist pass** — the item is a short (<1h) episode of a mutable
+       (TV-show) playlist that has played in the current pass and not yet reset
+       (``playlist_item_played``). These are governed by playlist position, not
+       the day window, so a whole show collection releases together when its last
+       item plays.
+
+    The fragment is prefixed with ``AND`` so it can be appended to an existing
+    WHERE clause referencing the catalog row under ``alias``. Caller must ensure
+    ``days > 0`` before applying (a non-positive window disables both signals).
+    """
+    sql = f"""
+            AND {alias}.friendly_token NOT IN (
+                SELECT pc.media_id FROM play_completions pc
+                WHERE pc.media_type = 'cm'
+                  AND pc.completed_at >= datetime('now', ?)
+            )
+            AND {alias}.friendly_token NOT IN (
+                SELECT pip.media_id FROM playlist_item_played pip
+                WHERE pip.media_type = 'cm'
+            )
+    """
+    return sql, [f"-{int(days)} days"]
+
+
 def _facet_filter(alias: str, category: str | None, tag: str | None) -> tuple[str, list]:
     """SQL fragment (+ params) AND-filtering by a category slug and/or tag name.
 
@@ -130,7 +164,7 @@ class _CatalogMixin:
 
     # --- Catalog ---
 
-    async def browse(self, *, category: str | None = None, tag: str | None = None, page: int = 1, per_page: int = 24, show_hidden: bool = False, sort: str = "default") -> list[dict]:
+    async def browse(self, *, category: str | None = None, tag: str | None = None, page: int = 1, per_page: int = 24, show_hidden: bool = False, sort: str = "default", recently_played_days: int = 0) -> list[dict]:
         query = """
             SELECT c.friendly_token, c.title, c.duration_sec, c.cover_art_path, c.cover_art_source, c.thumbnail_url, c.manifest_url
             FROM catalog c
@@ -145,6 +179,10 @@ class _CatalogMixin:
             excl_sql, excl_params = _hidden_exclusion("c")
             query += excl_sql
             params.extend(excl_params)
+        if recently_played_days > 0:
+            rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
+            query += rp_sql
+            params.extend(rp_params)
         if category:
             query += """
                 AND c.friendly_token IN (
@@ -180,7 +218,7 @@ class _CatalogMixin:
         params.extend([per_page, (page - 1) * per_page])
         return await self._fetch_all(query, params)
 
-    async def browse_count(self, *, category: str | None = None, tag: str | None = None, show_hidden: bool = False) -> int:
+    async def browse_count(self, *, category: str | None = None, tag: str | None = None, show_hidden: bool = False, recently_played_days: int = 0) -> int:
         query = """
             SELECT COUNT(*) as cnt FROM catalog c
             WHERE c.friendly_token NOT IN (
@@ -194,6 +232,10 @@ class _CatalogMixin:
             excl_sql, excl_params = _hidden_exclusion("c")
             query += excl_sql
             params.extend(excl_params)
+        if recently_played_days > 0:
+            rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
+            query += rp_sql
+            params.extend(rp_params)
         if category:
             query += """
                 AND c.friendly_token IN (
@@ -216,7 +258,7 @@ class _CatalogMixin:
         return row["cnt"] if row else 0
 
     async def search(self, query_text: str, *, category: str | None = None, tag: str | None = None,
-                     page: int = 1, per_page: int = 24, show_hidden: bool = False, sort: str = "default") -> list[dict]:
+                     page: int = 1, per_page: int = 24, show_hidden: bool = False, sort: str = "default", recently_played_days: int = 0) -> list[dict]:
         sql = """
             SELECT c.friendly_token, c.title, c.duration_sec, c.cover_art_path, c.cover_art_source, c.thumbnail_url, c.manifest_url,
                    rank AS relevance
@@ -234,6 +276,10 @@ class _CatalogMixin:
             excl_sql, excl_params = _hidden_exclusion("c")
             sql += excl_sql
             params.extend(excl_params)
+        if recently_played_days > 0:
+            rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
+            sql += rp_sql
+            params.extend(rp_params)
         # Category/tag facets AND with the text match (same subqueries browse()
         # uses), so a search can be narrowed by the selected facets.
         facet_sql, facet_params = _facet_filter("c", category, tag)
@@ -247,7 +293,7 @@ class _CatalogMixin:
         return await self._fetch_all(sql, params)
 
     async def search_count(self, query_text: str, *, category: str | None = None, tag: str | None = None,
-                           show_hidden: bool = False) -> int:
+                           show_hidden: bool = False, recently_played_days: int = 0) -> int:
         sql = """
             SELECT COUNT(*) as cnt
             FROM catalog_fts fts
@@ -264,6 +310,10 @@ class _CatalogMixin:
             excl_sql, excl_params = _hidden_exclusion("c")
             sql += excl_sql
             params.extend(excl_params)
+        if recently_played_days > 0:
+            rp_sql, rp_params = _recently_played_exclusion("c", recently_played_days)
+            sql += rp_sql
+            params.extend(rp_params)
         facet_sql, facet_params = _facet_filter("c", category, tag)
         sql += facet_sql
         params.extend(facet_params)
@@ -285,6 +335,133 @@ class _CatalogMixin:
     async def get_item_admin(self, friendly_token: str) -> dict | None:
         return await self._fetch_one("SELECT * FROM catalog WHERE friendly_token = ?", [friendly_token])
 
+    async def resolve_media(self, media_id: str) -> dict | None:
+        """Resolve a now-playing identifier to its catalog row (token + duration).
+
+        The live now-playing payload carries the manifest URL as ``id`` for 'cm'
+        items (not the friendly_token), so match on either column.
+        """
+        if not media_id:
+            return None
+        return await self._fetch_one(
+            "SELECT friendly_token, duration_sec FROM catalog "
+            "WHERE friendly_token = ? OR manifest_url = ? LIMIT 1",
+            [media_id, media_id],
+        )
+
+    async def record_play_completion(self, *, friendly_token: str, duration_sec: int | None,
+                                     media_type: str = "cm") -> None:
+        """Record a genuine play-completion, routing it to the correct hide rule.
+
+        Short (<1h) episodes that belong to a mutable (TV-show) playlist are
+        governed by playlist position instead of the day window: each such
+        completion marks the episode played for the current pass, and reaching
+        the playlist's last item (MAX position) clears the whole pass so the
+        collection releases together. Everything else (movies, standalone clips,
+        long items even inside a mutable playlist) gets a time-boxed
+        ``play_completions`` row instead.
+        """
+        rows = await self._fetch_all(
+            """
+            SELECT spi.playlist_id AS playlist_id, spi.position AS position,
+                   (SELECT MAX(position) FROM saved_playlist_items
+                     WHERE playlist_id = spi.playlist_id) AS max_pos
+            FROM saved_playlist_items spi
+            JOIN saved_playlists sp ON sp.id = spi.playlist_id
+            WHERE spi.media_id = ? AND spi.media_type = ?
+              AND sp.is_immutable = 0 AND sp.promo_type IS NULL
+            """,
+            [friendly_token, media_type],
+        )
+        governed = False
+        if duration_sec is not None and duration_sec < 3600:
+            for r in rows:
+                governed = True
+                if r["position"] == r["max_pos"]:
+                    # Last item of the pass reached — release the whole collection.
+                    await self._execute(
+                        "DELETE FROM playlist_item_played WHERE playlist_id = ?",
+                        [r["playlist_id"]],
+                    )
+                else:
+                    await self._execute(
+                        "INSERT OR REPLACE INTO playlist_item_played "
+                        "(playlist_id, position, media_type, media_id) VALUES (?, ?, ?, ?)",
+                        [r["playlist_id"], r["position"], media_type, friendly_token],
+                    )
+        if not governed:
+            await self._execute(
+                "INSERT INTO play_completions (media_type, media_id) VALUES (?, ?)",
+                [media_type, friendly_token],
+            )
+
+    async def get_playlist_played_media_ids(self, playlist_id: int) -> set[str]:
+        """media_ids already played in the current pass of a mutable playlist.
+
+        Backed by ``playlist_item_played`` (populated only for short episodes of
+        mutable playlists and cleared when the playlist's last item plays), so
+        firing can skip already-played episodes and continue the pass instead of
+        replaying from the start.
+        """
+        rows = await self._fetch_all(
+            "SELECT media_id FROM playlist_item_played WHERE playlist_id = ?",
+            [playlist_id],
+        )
+        return {r["media_id"] for r in rows}
+
+    async def clear_play_state(self, friendly_token: str, *, media_type: str = "cm") -> dict:
+        """Remove all recently-played hide state for an item (admin test helper).
+
+        Deletes both time-boxed ``play_completions`` rows and any
+        ``playlist_item_played`` (mutable-playlist pass) rows for the item, so it
+        immediately reappears in the public catalog. Returns the row counts
+        removed.
+        """
+        pc = await self._fetch_one(
+            "SELECT COUNT(*) AS c FROM play_completions WHERE media_id = ? AND media_type = ?",
+            [friendly_token, media_type],
+        )
+        pip = await self._fetch_one(
+            "SELECT COUNT(*) AS c FROM playlist_item_played WHERE media_id = ? AND media_type = ?",
+            [friendly_token, media_type],
+        )
+        await self._execute(
+            "DELETE FROM play_completions WHERE media_id = ? AND media_type = ?",
+            [friendly_token, media_type],
+        )
+        await self._execute(
+            "DELETE FROM playlist_item_played WHERE media_id = ? AND media_type = ?",
+            [friendly_token, media_type],
+        )
+        return {"completions": pc["c"] if pc else 0, "playlist_pass": pip["c"] if pip else 0}
+
+    async def get_recently_played_debug(self, days: int) -> dict:
+        """Snapshot of what the recently-played rules currently hide (admin test).
+
+        Mirrors the two exclusion signals used by browse/search so an admin can
+        see exactly which titles a regular user would NOT see, and why.
+        """
+        by_completion = await self._fetch_all(
+            "SELECT pc.media_id, c.title, MAX(pc.completed_at) AS last_completed "
+            "FROM play_completions pc "
+            "LEFT JOIN catalog c ON c.friendly_token = pc.media_id "
+            "WHERE pc.media_type = 'cm' AND pc.completed_at >= datetime('now', ?) "
+            "GROUP BY pc.media_id ORDER BY last_completed DESC",
+            [f"-{int(days)} days"],
+        )
+        by_playlist_pass = await self._fetch_all(
+            "SELECT pip.media_id, c.title, pip.playlist_id, sp.name AS playlist_name, pip.position "
+            "FROM playlist_item_played pip "
+            "JOIN saved_playlists sp ON sp.id = pip.playlist_id "
+            "LEFT JOIN catalog c ON c.friendly_token = pip.media_id "
+            "WHERE pip.media_type = 'cm' ORDER BY sp.name, pip.position",
+        )
+        return {
+            "window_days": days,
+            "by_completion": by_completion,
+            "by_playlist_pass": by_playlist_pass,
+        }
+
     async def get_catalog_brief(self, tokens: list[str], manifest_urls: list[str]) -> dict[str, dict]:
         """Return a lookup of catalog metadata keyed by BOTH friendly_token and
         manifest_url, for enriching queue-shadow items that may only carry one.

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/catalog/db/_connection.py

@@ -258,6 +258,39 @@ MIGRATIONS = [
     );
     CREATE INDEX IF NOT EXISTS idx_title_suggestions_status ON title_suggestions(status, created_at);
     """,
+    # v13: Play-completion tracking that drives hiding recently-played catalog
+    # items from regular users.
+    #
+    # play_completions records a *genuine* completion (an item that reached the
+    # now-playing slot and played past a threshold), keyed by media_id
+    # (== catalog friendly_token for 'cm'). completed_at powers the time-based
+    # hide window. Items queued-then-refunded never reach now-playing, so they
+    # never land here.
+    #
+    # playlist_item_played tracks, per mutable (TV-show) playlist, which short
+    # (<1h) episodes have played in the *current pass*. Rows are cleared for a
+    # playlist the moment its last item (MAX position) plays, releasing the whole
+    # collection at once — so appending S2/S3 never re-hides S1 piecemeal.
+    """
+    CREATE TABLE IF NOT EXISTS play_completions (
+        id           INTEGER PRIMARY KEY AUTOINCREMENT,
+        media_type   TEXT NOT NULL,
+        media_id     TEXT NOT NULL,
+        completed_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
+    );
+    CREATE INDEX IF NOT EXISTS idx_play_completions_media ON play_completions(media_id);
+    CREATE INDEX IF NOT EXISTS idx_play_completions_at ON play_completions(completed_at);
+
+    CREATE TABLE IF NOT EXISTS playlist_item_played (
+        playlist_id INTEGER NOT NULL REFERENCES saved_playlists(id) ON DELETE CASCADE,
+        position    INTEGER NOT NULL,
+        media_type  TEXT NOT NULL,
+        media_id    TEXT NOT NULL,
+        played_at   TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
+        PRIMARY KEY (playlist_id, position)
+    );
+    CREATE INDEX IF NOT EXISTS idx_playlist_item_played_media ON playlist_item_played(media_id);
+    """,
 ]
 
 

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/config.py

@@ -149,6 +149,13 @@ class Config(BaseModel):
     pre_fire_lock_minutes_default: int = 15
     state_poll_interval_sec: float = 3.0
 
+    # Hide recently-played items from the public catalog (browse/search) for this
+    # many days after they actually finished playing. Admins (rank >= 3) always
+    # see them. Short (<1h) episodes of a mutable playlist are instead governed by
+    # playlist position (hidden until the playlist's last item plays). Set to 0 to
+    # disable recently-played hiding entirely.
+    catalog_recently_played_hide_days: int = 21
+
     # Bulk playlist loading (manual import + scheduled fire). CyTube validates
     # each queued item server-side (fetching custom manifests); adding faster
     # than it can validate triggers a transient queueFail (surfaced by api-gate

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/playlists/fire.py

@@ -58,6 +58,19 @@ async def fire_schedule(
 
             # Load scheduled playlist items
             items = await db.get_saved_playlist_items(playlist_id)
+            # For a mutable (TV-show) playlist, skip episodes already played in the
+            # current pass so a re-fire continues where it left off instead of
+            # replaying season 1. Immutable/promo playlists never have played rows,
+            # so this is a no-op for them.
+            played = await db.get_playlist_played_media_ids(playlist_id)
+            if played:
+                before = len(items)
+                items = [it for it in items if it["media_id"] not in played]
+                if before != len(items):
+                    logger.info(
+                        f"Schedule {schedule_id}: skipped {before - len(items)} already-played "
+                        f"episode(s) from mutable playlist {playlist_id}"
+                    )
             total_duration = 0
             last_item_uid = None
             for index, item in enumerate(items):
@@ -88,6 +101,11 @@ async def fire_schedule(
             fallback_id = schedule.get("fallback_playlist_id")
             if fallback_id:
                 fallback_items = await db.get_saved_playlist_items(fallback_id)
+                # Same continuation logic as the main playlist: skip already-played
+                # episodes of the (mutable) fallback so it advances across fires.
+                fb_played = await db.get_playlist_played_media_ids(fallback_id)
+                if fb_played:
+                    fallback_items = [it for it in fallback_items if it["media_id"] not in fb_played]
                 for index, item in enumerate(fallback_items):
                     if index and add_delay_sec:
                         await asyncio.sleep(add_delay_sec)

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/playlists/importer.py

@@ -72,12 +72,30 @@ class PlaylistImporter:
         self._add_max_retries = add_max_retries
         self._promo_director = promo_director
 
-    async def import_playlist(self, playlist_id: int) -> dict:
-        """Import all items from a saved playlist into the live queue."""
+    async def import_playlist(self, playlist_id: int, *, skip_played: bool = True) -> dict:
+        """Import items from a saved playlist into the live queue.
+
+        By default (``skip_played=True``) already-played episodes of the current
+        pass are skipped, so a mutable (TV-show) playlist continues where it left
+        off instead of replaying from the start — the same rule automated firing
+        uses. Pass ``skip_played=False`` to force-load the entire list regardless
+        of pass state.
+        """
         items = await self._db.get_saved_playlist_items(playlist_id)
         if not items:
             return {"success": False, "error": "Playlist is empty"}
 
+        skipped = 0
+        if skip_played:
+            played = await self._db.get_playlist_played_media_ids(playlist_id)
+            if played:
+                before = len(items)
+                items = [it for it in items if it["media_id"] not in played]
+                skipped = before - len(items)
+        if not items:
+            # Everything's already been played this pass (nothing left to add).
+            return {"success": True, "added": 0, "errors": 0, "skipped": skipped}
+
         # Suppress promo insertion for the whole load so promos aren't slotted
         # between items while the playlist is still being built.
         suppress_ctx = (
@@ -111,7 +129,7 @@ class PlaylistImporter:
                     logger.warning(f"Failed to add {item['media_id']}: {e}")
                     errors += 1
 
-        return {"success": True, "added": added, "errors": errors}
+        return {"success": True, "added": added, "errors": errors, "skipped": skipped}
 
 
 async def import_playlist_text(db, text: str, *, mediacms_url: str | None = None) -> dict:

kryten_webqueue-0.32.1/kryten_webqueue/queue/completion.py

@@ -0,0 +1,93 @@
+"""Play-completion recorder.
+
+Watches the now-playing item across poll cycles and records a completion only
+when the now-playing pointer moves off an item that had progressed past a
+threshold (default 50%) of its duration. This is the signal that drives hiding
+recently-played catalog items from regular users.
+
+Why threshold-on-advance rather than "item left the queue":
+
+* An item queued and then **refunded/removed** by an admin is pulled before it
+  ever reaches the now-playing slot, so it is never tracked here and can't be
+  mistaken for "played".
+* An admin **skipping the currently-playing item** early leaves its observed
+  progress below the threshold, so it also doesn't count.
+* A natural finish leaves progress near the end (well past the threshold), so it
+  is recorded exactly once when playback advances.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def _to_seconds(value) -> float:
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+class CompletionRecorder:
+    """Records genuine play-completions from the poll loop."""
+
+    def __init__(self, *, db, completion_threshold: float = 0.5):
+        self._db = db
+        self._threshold = completion_threshold
+        # State of the item currently occupying the now-playing slot.
+        self._cur_key: tuple | None = None      # (media_type, media_id)
+        self._cur_token: str | None = None      # resolved catalog friendly_token
+        self._cur_duration: float = 0.0
+        self._max_ct: float = 0.0               # furthest observed currentTime
+
+    async def on_poll(self, now_playing: dict | None) -> None:
+        """Called once per poll cycle with the latest now-playing payload."""
+        np = now_playing or {}
+        media_id = np.get("id")
+        media_type = np.get("type")
+        key = (media_type, media_id) if media_id else None
+
+        if key == self._cur_key:
+            # Same item still playing — track its furthest progress and fill in a
+            # duration if it wasn't known when it started.
+            ct = _to_seconds(np.get("currentTime"))
+            if ct > self._max_ct:
+                self._max_ct = ct
+            if not self._cur_duration:
+                self._cur_duration = _to_seconds(np.get("seconds") or np.get("duration"))
+            return
+
+        # Now-playing advanced (or stopped): finalize the item that just left.
+        if self._cur_key is not None:
+            await self._finalize(self._cur_token, self._cur_duration, self._max_ct)
+
+        # Begin tracking the newly-playing item.
+        self._cur_key = key
+        self._cur_token = None
+        self._max_ct = _to_seconds(np.get("currentTime"))
+        self._cur_duration = _to_seconds(np.get("seconds") or np.get("duration"))
+        if key is not None:
+            try:
+                meta = await self._db.resolve_media(media_id)
+            except Exception:
+                logger.debug("Failed to resolve now-playing media %r", media_id, exc_info=True)
+                meta = None
+            if meta:
+                self._cur_token = meta.get("friendly_token")
+                if not self._cur_duration:
+                    self._cur_duration = _to_seconds(meta.get("duration_sec"))
+
+    async def _finalize(self, token: str | None, duration: float, max_ct: float) -> None:
+        if not token:
+            return  # not a resolvable catalog ('cm') item
+        if duration <= 0:
+            return  # unknown duration — can't judge the threshold; don't hide
+        if max_ct < self._threshold * duration:
+            return  # skipped/removed before playing enough to count as played
+        try:
+            await self._db.record_play_completion(
+                friendly_token=token,
+                duration_sec=int(duration),
+            )
+        except Exception:
+            logger.warning("Failed to record play completion for %s", token, exc_info=True)

{kryten_webqueue-0.31.0 → kryten_webqueue-0.32.1}/kryten_webqueue/queue/poller.py

@@ -7,13 +7,14 @@ logger = logging.getLogger(__name__)
 class StatePoller:
     """Polls api-gate at a fixed interval to keep QueueShadow in sync."""
 
-    def __init__(self, *, api_gate, shadow, ws_manager, db=None, interval: float = 3.0, promo_director=None):
+    def __init__(self, *, api_gate, shadow, ws_manager, db=None, interval: float = 3.0, promo_director=None, completion_recorder=None):
         self._api_gate = api_gate
         self._shadow = shadow
         self._ws_manager = ws_manager
         self._db = db
         self._interval = interval
         self._promo_director = promo_director
+        self._completion_recorder = completion_recorder
         self._task: asyncio.Task | None = None
 
     async def start(self):
@@ -35,6 +36,12 @@ class StatePoller:
                 playlist = await self._api_gate.get_playlist()
                 now_playing = await self._api_gate.get_now_playing()
                 await self._shadow.apply_poll_result(playlist, now_playing)
+                # Record genuine play-completions (drives recently-played hiding).
+                if self._completion_recorder is not None:
+                    try:
+                        await self._completion_recorder.on_poll(now_playing)
+                    except Exception as e:
+                        logger.warning(f"Completion recorder error: {e}")
                 # Promo insertion runs after reconciliation, before broadcast.
                 if self._promo_director is not None:
                     try: