optionally poll Frigate's event API for events MQTT never announces

Events created through Frigate's API are not tracked objects, so frigate/events
stays silent about them. A camera's own person detection wired up as a bridge
therefore went unused - measured at one front door that was ~22 events a day with
a usable face in 12 of 20, roughly doubling what FaceID could learn from.

Off by default since it costs an API request per interval.

Author: skycryer

CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to FaceID. The Home Assistant app shows this file in the
 update dialog; standalone users can watch GitHub releases.
 
+## 0.6.7 — 2026-07-25
+
+- **New: `poll_interval`** — optionally also poll Frigate's event API instead of relying
+  on MQTT alone. Events created through Frigate's API are not tracked objects and never
+  appear on `frigate/events`, so FaceID never saw them. A common case is a camera's own
+  person detection wired up as a reliability bridge: on one installation that was ~22
+  events per day at the front door, of which 12 in 20 held a usable face — roughly
+  doubling the events FaceID could learn from. Off by default; 30 seconds is sensible.
+- Polled events run through the same pipeline. They carry no bounding box, so their
+  snapshot is the full frame rather than a person crop — face detection copes, and the
+  clip path (sharper reference photos) applies as usual.
+
 ## 0.6.6 — 2026-07-25
 
 - **`match_top_k` is now adjustable in Settings** ("Photos averaged per match"). It was

app/mqtt_listener.py

@@ -13,6 +13,7 @@
 from collections import deque
 
 import paho.mqtt.client as mqtt
+import requests
 
 from .engine import FaceEngine, crop_face
 from .hires import upgrade_face
@@ -42,6 +43,10 @@ def __init__(self, cfg: dict, engine, gallery, frigate):
         self.ignore_thr = float(f.get("ignore_threshold", f.get("match_threshold", 0.5)))
         self.ignore_learning = bool(f.get("ignore_learning", True))
         self.hires_enroll = bool(f.get("hires_enroll", True))
+        # Ereignisse, die Frigate nicht per MQTT meldet (z. B. per API angelegte
+        # Kamera-Meldungen als Zuverlaessigkeits-Bruecke), per Abfrage nachziehen.
+        self.poll_interval = float(f.get("poll_interval", 0))
+        self._polled: deque = deque(maxlen=500)   # schon gesehene IDs
         self.prefix = str(f.get("mqtt_prefix", "faceid")).strip("/") or "faceid"
         self.present: dict[str, dict[str, float]] = {}  # camera -> {person: zuletzt gesehen}
         self._last_presence: dict[str, list] = {}  # zuletzt publizierter Stand je Kamera
@@ -61,6 +66,8 @@ def start(self):
         self.client = c
         threading.Thread(target=self._worker, daemon=True, name="faceid-worker").start()
         threading.Thread(target=self._finalizer, daemon=True, name="faceid-finalizer").start()
+        if self.poll_interval > 0:
+            threading.Thread(target=self._poller, daemon=True, name="faceid-poller").start()
 
     def _on_connect(self, client, userdata, flags, reason_code, properties):
         log.info("MQTT verbunden (%s)", reason_code)
@@ -157,6 +164,55 @@ def _process(self, eid: str):
                 st["best_unknown"] = {"crop": crop, "emb": emb, "det_score": float(face.det_score),
                                       "guess": name, "guess_score": float(score), "full": img}
 
+    def _poller(self):
+        """Frigate-Ereignisse abfragen, die per MQTT nie ankommen.
+
+        Manuell ueber die API angelegte Ereignisse sind fuer Frigate keine getrackten
+        Objekte und loesen ``frigate/events`` nicht aus — eine Kamera-eigene
+        Personenmeldung, die als Bruecke ein Ereignis anlegt, bliebe sonst ungenutzt.
+        Sie haben keine Bounding-Box, der Snapshot ist also das Vollbild; die Erkennung
+        laeuft ansonsten durch dieselbe Pipeline.
+        """
+        url = self.cfg["frigate"]["url"].rstrip("/")
+        # Beim Start nicht die halbe Historie aufrollen.
+        since = time.time() - min(self.poll_interval * 4, 300)
+        while True:
+            time.sleep(self.poll_interval)
+            try:
+                r = requests.get(f"{url}/api/events",
+                                 params={"label": "person", "has_snapshot": 1,
+                                         "limit": 50, "after": since - 30},
+                                 timeout=10)
+                if r.status_code != 200:
+                    continue
+                batch = r.json()
+            except (requests.RequestException, ValueError) as e:
+                log.debug("Poll fehlgeschlagen: %s", e)
+                continue
+            since = time.time()
+            for ev in batch:
+                eid = ev.get("id")
+                if not eid or eid in self._polled or eid in self.events:
+                    continue
+                cam = ev.get("camera", "")
+                if self.cameras and cam not in self.cameras:
+                    continue
+                self._polled.append(eid)
+                # Nur abgeschlossene Ereignisse — laufende meldet MQTT ohnehin.
+                if not ev.get("end_time"):
+                    continue
+                self.events[eid] = {
+                    "camera": cam, "attempts": 0, "best_score": 0.0, "best_person": None,
+                    "best_unknown": None, "last_try": 0.0, "done": False, "ended": True,
+                    "created": time.time(), "polled": True,
+                    "start_time": ev.get("start_time") or time.time(),
+                    "end_time": ev.get("end_time"),
+                }
+                try:
+                    self.queue.put_nowait({"eid": eid})
+                except queue.Full:
+                    log.warning("Queue voll — Poll-Ereignis %s verworfen", eid)
+
     def _finalizer(self):
         """Beendete Events abschließen: Unknown ablegen, 'unbekannt' melden, aufräumen."""
         while True:

docs/example-config.yaml

@@ -23,6 +23,11 @@ faceid:
   min_face_px: 48                      # minimum face size in the snapshot (pixels)
   det_size: 640                        # detection input size (higher = better far faces, slower)
   max_attempts: 6                      # recognition attempts per Frigate event
+  poll_interval: 0                     # seconds; >0 also polls Frigate's event API.
+                                       # Catches events MQTT never announces — notably
+                                       # ones created through Frigate's API (e.g. a
+                                       # camera's own person detection used as a
+                                       # reliability bridge). 30 is a sensible value.
   retry_seconds: 2.5                   # min. seconds between attempts on the same event
   cluster_eps: 0.55                    # DBSCAN cosine distance for grouping unknowns in the UI
   # review UI: unknown faces with a best-match score >= this get grouped into a

faceid-addon/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to FaceID. The Home Assistant app shows this file in the
 update dialog; standalone users can watch GitHub releases.
 
+## 0.6.7 — 2026-07-25
+
+- **New: `poll_interval`** — optionally also poll Frigate's event API instead of relying
+  on MQTT alone. Events created through Frigate's API are not tracked objects and never
+  appear on `frigate/events`, so FaceID never saw them. A common case is a camera's own
+  person detection wired up as a reliability bridge: on one installation that was ~22
+  events per day at the front door, of which 12 in 20 held a usable face — roughly
+  doubling the events FaceID could learn from. Off by default; 30 seconds is sensible.
+- Polled events run through the same pipeline. They carry no bounding box, so their
+  snapshot is the full frame rather than a person crop — face detection copes, and the
+  clip path (sharper reference photos) applies as usual.
+
 ## 0.6.6 — 2026-07-25
 
 - **`match_top_k` is now adjustable in Settings** ("Photos averaged per match"). It was

faceid-addon/app/mqtt_listener.py

@@ -13,6 +13,7 @@
 from collections import deque
 
 import paho.mqtt.client as mqtt
+import requests
 
 from .engine import FaceEngine, crop_face
 from .hires import upgrade_face
@@ -42,6 +43,10 @@ def __init__(self, cfg: dict, engine, gallery, frigate):
         self.ignore_thr = float(f.get("ignore_threshold", f.get("match_threshold", 0.5)))
         self.ignore_learning = bool(f.get("ignore_learning", True))
         self.hires_enroll = bool(f.get("hires_enroll", True))
+        # Ereignisse, die Frigate nicht per MQTT meldet (z. B. per API angelegte
+        # Kamera-Meldungen als Zuverlaessigkeits-Bruecke), per Abfrage nachziehen.
+        self.poll_interval = float(f.get("poll_interval", 0))
+        self._polled: deque = deque(maxlen=500)   # schon gesehene IDs
         self.prefix = str(f.get("mqtt_prefix", "faceid")).strip("/") or "faceid"
         self.present: dict[str, dict[str, float]] = {}  # camera -> {person: zuletzt gesehen}
         self._last_presence: dict[str, list] = {}  # zuletzt publizierter Stand je Kamera
@@ -61,6 +66,8 @@ def start(self):
         self.client = c
         threading.Thread(target=self._worker, daemon=True, name="faceid-worker").start()
         threading.Thread(target=self._finalizer, daemon=True, name="faceid-finalizer").start()
+        if self.poll_interval > 0:
+            threading.Thread(target=self._poller, daemon=True, name="faceid-poller").start()
 
     def _on_connect(self, client, userdata, flags, reason_code, properties):
         log.info("MQTT verbunden (%s)", reason_code)
@@ -157,6 +164,55 @@ def _process(self, eid: str):
                 st["best_unknown"] = {"crop": crop, "emb": emb, "det_score": float(face.det_score),
                                       "guess": name, "guess_score": float(score), "full": img}
 
+    def _poller(self):
+        """Frigate-Ereignisse abfragen, die per MQTT nie ankommen.
+
+        Manuell ueber die API angelegte Ereignisse sind fuer Frigate keine getrackten
+        Objekte und loesen ``frigate/events`` nicht aus — eine Kamera-eigene
+        Personenmeldung, die als Bruecke ein Ereignis anlegt, bliebe sonst ungenutzt.
+        Sie haben keine Bounding-Box, der Snapshot ist also das Vollbild; die Erkennung
+        laeuft ansonsten durch dieselbe Pipeline.
+        """
+        url = self.cfg["frigate"]["url"].rstrip("/")
+        # Beim Start nicht die halbe Historie aufrollen.
+        since = time.time() - min(self.poll_interval * 4, 300)
+        while True:
+            time.sleep(self.poll_interval)
+            try:
+                r = requests.get(f"{url}/api/events",
+                                 params={"label": "person", "has_snapshot": 1,
+                                         "limit": 50, "after": since - 30},
+                                 timeout=10)
+                if r.status_code != 200:
+                    continue
+                batch = r.json()
+            except (requests.RequestException, ValueError) as e:
+                log.debug("Poll fehlgeschlagen: %s", e)
+                continue
+            since = time.time()
+            for ev in batch:
+                eid = ev.get("id")
+                if not eid or eid in self._polled or eid in self.events:
+                    continue
+                cam = ev.get("camera", "")
+                if self.cameras and cam not in self.cameras:
+                    continue
+                self._polled.append(eid)
+                # Nur abgeschlossene Ereignisse — laufende meldet MQTT ohnehin.
+                if not ev.get("end_time"):
+                    continue
+                self.events[eid] = {
+                    "camera": cam, "attempts": 0, "best_score": 0.0, "best_person": None,
+                    "best_unknown": None, "last_try": 0.0, "done": False, "ended": True,
+                    "created": time.time(), "polled": True,
+                    "start_time": ev.get("start_time") or time.time(),
+                    "end_time": ev.get("end_time"),
+                }
+                try:
+                    self.queue.put_nowait({"eid": eid})
+                except queue.Full:
+                    log.warning("Queue voll — Poll-Ereignis %s verworfen", eid)
+
     def _finalizer(self):
         """Beendete Events abschließen: Unknown ablegen, 'unbekannt' melden, aufräumen."""
         while True:

faceid-addon/config.yaml

@@ -1,5 +1,5 @@
 name: FaceID
-version: "0.6.6"
+version: "0.6.7"
 slug: faceid
 description: Face recognition for Frigate — trainable gallery, clustered unknown review, HA sensors
 url: https://github.com/SkyTechNerds/faceid
@@ -35,6 +35,7 @@ options:
   trimmed_keep: 10
   dedupe_threshold: 0.65
   hires_enroll: true
+  poll_interval: 0
   backup_enabled: false
   backup_hour: 3
   backup_keep: 7
@@ -57,6 +58,7 @@ schema:
   trimmed_keep: int(0,100)
   dedupe_threshold: float(0.50,0.95)
   hires_enroll: bool
+  poll_interval: int(0,3600)
   backup_enabled: bool
   backup_hour: int(0,23)
   backup_keep: int(1,90)

faceid-addon/run.sh

@@ -64,6 +64,7 @@ faceid:
   trimmed_keep: $(cfg '.trimmed_keep')
   dedupe_threshold: $(cfg '.dedupe_threshold')
   hires_enroll: $(cfg '.hires_enroll')
+  poll_interval: $(cfg '.poll_interval')
   backup_enabled: $(cfg '.backup_enabled')
   backup_hour: $(cfg '.backup_hour')
   backup_keep: $(cfg '.backup_keep')