From ecad939a62bd51cfb1fedc294a7c2140debebce2 Mon Sep 17 00:00:00 2001 From: Kai Curry Date: Mon, 9 Feb 2026 14:36:35 -0100 Subject: [PATCH 1/6] Add detail to face recognition MQTT update docs Clarify that the weighted average favors larger faces and higher-confidence detections, that unknown attempts are excluded, and document when name/score will be null/0.0. --- docs/docs/integrations/mqtt.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index 535e1bb4b..5020d7955 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -134,6 +134,8 @@ Message published for updates to tracked object metadata, for example: #### Face Recognition Update +Published after each recognition attempt. The `id` is the tracked object's event ID, which can be used to look up the event via the API or match it to items in the UI. The `score` is a weighted average across all recognition attempts for this person object, not the score from a single attempt. The weighting favors larger faces (by pixel area, capped at 4000px) and higher-confidence detections. Attempts scored at or below `unknown_score` are excluded from the average. The `name` is the best matching person based on that weighted average, or `null` if no match. Both `name` and `score` will be `null` / `0.0` if fewer than `min_faces` attempts have been recorded or if two names are tied for the most detections. This message is published regardless of whether the score meets `recognition_threshold`. + ```json { "type": "face", From 535fe7aaef4eb08dae89e50278d2d9c895a99851 Mon Sep 17 00:00:00 2001 From: Kai Curry Date: Mon, 9 Feb 2026 14:48:34 -0100 Subject: [PATCH 2/6] Fix score decimal in MQTT face recognition documentation `0.0` in JSON is just `0`. --- docs/docs/integrations/mqtt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index 5020d7955..18281d2b7 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -134,7 +134,7 @@ Message published for updates to tracked object metadata, for example: #### Face Recognition Update -Published after each recognition attempt. The `id` is the tracked object's event ID, which can be used to look up the event via the API or match it to items in the UI. The `score` is a weighted average across all recognition attempts for this person object, not the score from a single attempt. The weighting favors larger faces (by pixel area, capped at 4000px) and higher-confidence detections. Attempts scored at or below `unknown_score` are excluded from the average. The `name` is the best matching person based on that weighted average, or `null` if no match. Both `name` and `score` will be `null` / `0.0` if fewer than `min_faces` attempts have been recorded or if two names are tied for the most detections. This message is published regardless of whether the score meets `recognition_threshold`. +Published after each recognition attempt. The `id` is the tracked object's event ID, which can be used to look up the event via the API or match it to items in the UI. The `score` is a weighted average across all recognition attempts for this person object, not the score from a single attempt. The weighting favors larger faces (by pixel area, capped at 4000px) and higher-confidence detections. Attempts scored at or below `unknown_score` are excluded from the average. The `name` is the best matching person based on that weighted average, or `null` if no match. Both `name` and `score` will be `null` / `0` if fewer than `min_faces` attempts have been recorded or if two names are tied for the most detections. This message is published regardless of whether the score meets `recognition_threshold`. ```json { From 565d7ba8b4d830d8e34bb0438f77d76f86c4a9ef Mon Sep 17 00:00:00 2001 From: Kai Curry Date: Mon, 9 Feb 2026 14:52:41 -0100 Subject: [PATCH 3/6] Clarify score is a running weighted average --- docs/docs/integrations/mqtt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index 18281d2b7..978bae9ee 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -134,7 +134,7 @@ Message published for updates to tracked object metadata, for example: #### Face Recognition Update -Published after each recognition attempt. The `id` is the tracked object's event ID, which can be used to look up the event via the API or match it to items in the UI. The `score` is a weighted average across all recognition attempts for this person object, not the score from a single attempt. The weighting favors larger faces (by pixel area, capped at 4000px) and higher-confidence detections. Attempts scored at or below `unknown_score` are excluded from the average. The `name` is the best matching person based on that weighted average, or `null` if no match. Both `name` and `score` will be `null` / `0` if fewer than `min_faces` attempts have been recorded or if two names are tied for the most detections. This message is published regardless of whether the score meets `recognition_threshold`. +Published after each recognition attempt. The `id` is the tracked object's event ID, which can be used to look up the event via the API or match it to items in the UI. The `score` is a running weighted average across all recognition attempts for this person object up to that point, not the score from a single attempt. The weighting favors larger faces (by pixel area, capped at 4000px) and higher-confidence detections. Attempts scored at or below `unknown_score` are excluded from the average. The `name` is the best matching person based on that weighted average, or `null` if no match. Both `name` and `score` will be `null` / `0` if fewer than `min_faces` attempts have been recorded or if two names are tied for the most detections. This message is published regardless of whether the score meets `recognition_threshold`. ```json { From b6189a6a74b46e2be06fbd2dadfa59b649764187 Mon Sep 17 00:00:00 2001 From: Kai Curry Date: Mon, 9 Feb 2026 16:27:37 -0100 Subject: [PATCH 4/6] Simplify MQTT tracked_object_update docs with inline comments Move scoring logic details to face recognition docs and keep MQTT reference concise with inline field comments and links. --- docs/docs/integrations/mqtt.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index 978bae9ee..eaa0de9ea 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -120,7 +120,7 @@ Message published for each changed tracked object. The first message is publishe ### `frigate/tracked_object_update` -Message published for updates to tracked object metadata, for example: +Message published for updates to tracked object metadata. All messages include an `id` field which is the tracked object's event ID, and can be used to look up the event via the API or match it to items in the UI. #### Generative AI Description Update @@ -134,14 +134,14 @@ Message published for updates to tracked object metadata, for example: #### Face Recognition Update -Published after each recognition attempt. The `id` is the tracked object's event ID, which can be used to look up the event via the API or match it to items in the UI. The `score` is a running weighted average across all recognition attempts for this person object up to that point, not the score from a single attempt. The weighting favors larger faces (by pixel area, capped at 4000px) and higher-confidence detections. Attempts scored at or below `unknown_score` are excluded from the average. The `name` is the best matching person based on that weighted average, or `null` if no match. Both `name` and `score` will be `null` / `0` if fewer than `min_faces` attempts have been recorded or if two names are tied for the most detections. This message is published regardless of whether the score meets `recognition_threshold`. +Published after each recognition attempt, regardless of whether the score meets `recognition_threshold`. See the [Face Recognition](/configuration/face_recognition) documentation for details on how scoring works. ```json { "type": "face", "id": "1607123955.475377-mxklsc", - "name": "John", - "score": 0.95, + "name": "John", // best matching person, or null if no match + "score": 0.95, // running weighted average across all recognition attempts "camera": "front_door_cam", "timestamp": 1607123958.748393 } @@ -149,13 +149,15 @@ Published after each recognition attempt. The `id` is the tracked object's event #### License Plate Recognition Update +Published when a license plate is recognized on a car object. See the [License Plate Recognition](/configuration/lpr) documentation for details. + ```json { "type": "lpr", "id": "1607123955.475377-mxklsc", - "name": "John's Car", - "plate": "123ABC", - "score": 0.95, + "name": "John's Car", // known name for the plate, or null + "plate": "123ABC", // recognized plate string + "score": 0.95, // recognition confidence "camera": "driveway_cam", "timestamp": 1607123958.748393 } From 91ab99003452b53c97bb39a913494a5124f9f502 Mon Sep 17 00:00:00 2001 From: Kai Curry Date: Mon, 9 Feb 2026 17:09:26 -0100 Subject: [PATCH 5/6] fix (expand) lpr doc link --- docs/docs/integrations/mqtt.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index eaa0de9ea..44f320e47 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -149,7 +149,7 @@ Published after each recognition attempt, regardless of whether the score meets #### License Plate Recognition Update -Published when a license plate is recognized on a car object. See the [License Plate Recognition](/configuration/lpr) documentation for details. +Published when a license plate is recognized on a car object. See the [License Plate Recognition](/configuration/license_plate_recognition) documentation for details. ```json { From 90237c31a5ed79de439838975a107cc93b3c2c4e Mon Sep 17 00:00:00 2001 From: Kai Curry Date: Mon, 9 Feb 2026 17:59:13 -0100 Subject: [PATCH 6/6] rm obvious lpr comments --- docs/docs/integrations/mqtt.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/integrations/mqtt.md b/docs/docs/integrations/mqtt.md index 44f320e47..66775a473 100644 --- a/docs/docs/integrations/mqtt.md +++ b/docs/docs/integrations/mqtt.md @@ -156,8 +156,8 @@ Published when a license plate is recognized on a car object. See the [License P "type": "lpr", "id": "1607123955.475377-mxklsc", "name": "John's Car", // known name for the plate, or null - "plate": "123ABC", // recognized plate string - "score": 0.95, // recognition confidence + "plate": "123ABC", + "score": 0.95, "camera": "driveway_cam", "timestamp": 1607123958.748393 }