Merge 952dc1c3ef into efe585a920

* keep global camera config subscribers broad when only one camera exists at startup

* update glossary

docs/docs/frigate/glossary.md

@@ -5,20 +5,40 @@ title: Glossary
 
 The glossary explains terms commonly used in Frigate's documentation.
 
+## Alert
+
+The higher-priority of the two [review item](#review-item) severities, the other being a [detection](#detection). By default a review item is an alert when it involves a `person` or `car`; the qualifying [labels](#label) and [zones](#zone) can be configured. [See the review docs for more info](/configuration/review)
+
+## Attribute
+
+A property detected on an [object](#object) that exists alongside its [label](#label). Unlike a [sub label](#sub-label), an object can carry several attributes at once. Some attributes come directly from the object detection [model](#model) — for example `face`, `license_plate`, or delivery carrier logos such as `amazon`, `ups`, and `fedex` — while others come from a [custom object classification model](/configuration/custom_classification/object_classification) configured with the `attribute` type. Attributes are visible in the Tracked Object Details pane in Explore, in `frigate/events` MQTT messages, and through the HTTP API.
+
 ## Bounding Box
 
-A box returned from the object detection model that outlines an object in the frame. These have multiple colors depending on object type in the debug live view.
+A box returned by the object detection [model](#model) that outlines a detected [object](#object) in the frame. In the Debug view, bounding boxes are colored by object [label](#label).
 
 ### Bounding Box Colors
 
 - At startup different colors will be assigned to each object label
 - A dark blue thin line indicates that object is not detected at this current point in time
 - A gray thin line indicates that object is detected as being stationary
-- A thick line indicates that object is the subject of autotracking (when enabled).
+- A thick line indicates that object is the subject of autotracking (when enabled)
+
+## Class
+
+The categories a classification [model](#model) is trained to distinguish between. Each class is a distinct visual category the model predicts, plus a `none` class for inputs that don't fit any category. For example, a custom object classification model for `person` objects might use the classes `delivery_person`, `resident`, and `none`. The predicted class is applied to the [object](#object) as either a [sub label](#sub-label) or an [attribute](#attribute), depending on the model's configuration. [See the object classification docs for more info](/configuration/custom_classification/object_classification)
+
+## Detection
+
+The lower-priority of the two [review item](#review-item) severities, the other being an [alert](#alert). By default, any review item that does not qualify as an alert is a detection; the qualifying [labels](#label) and [zones](#zone) can be configured. Despite the name, a detection is a category of review item — not the same as the object detection performed by the [model](#model). [See the review docs for more info](/configuration/review)
 
 ## False Positive
 
-An incorrect detection of an object type. For example a dog being detected as a person, a chair being detected as a dog, etc. A person being detected in an area you want to ignore is not a false positive.
+An incorrect result from the object detection [model](#model), where it assigns the wrong [label](#label) to something in the frame — for example a dog identified as a person, or a chair identified as a dog. A person correctly identified in an area you want to ignore is not a false positive.
+
+## Label
+
+The type assigned to a detected [object](#object) by the object detection [model](#model), drawn from the model's labelmap — for example `person`, `car`, or `dog`. Frigate tracks `person` by default; additional labels are tracked by adding them to the objects configuration. [See the available objects docs for the full list](/configuration/objects)
 
 ## Mask
 
@@ -26,44 +46,56 @@ There are two types of masks in Frigate. [See the mask docs for more info](/conf
 
 ### Motion Mask
 
-Motion masks prevent detection of [motion](#motion) in masked areas from triggering Frigate to run object detection, but do not prevent objects from being detected if object detection runs due to motion in nearby areas. For example: camera timestamps, skies, the tops of trees, etc.
+A motion mask stops [motion](#motion) in the masked area from triggering object detection. It does not stop an object from being detected when object detection runs because of motion in a nearby area. Use motion masks for parts of the frame that change constantly but never contain objects you care about — camera timestamps, the sky, the tops of trees, and so on.
 
 ### Object Mask
 
-Object filter masks drop any bounding boxes where the bottom center (overlap doesn't matter) is in the masked area. It forces them to be considered a [false positive](#false-positive) so that they are ignored.
+An object filter mask drops any [bounding box](#bounding-box) whose bottom center falls inside the masked area (overlap elsewhere doesn't matter). The object is forced to be treated as a [false positive](#false-positive) and ignored.
 
 ## Min Score
 
-The lowest score that an object can be detected with during tracking, any detection with a lower score will be assumed to be a false positive
+The lowest score a detected object can have to be kept during tracking. Anything scoring below the minimum is assumed to be a [false positive](#false-positive) and discarded.
+
+## Model
+
+A machine learning model that Frigate uses to detect or classify objects. The object detection model locates [objects](#object) in each frame and returns their [labels](#label) and [bounding boxes](#bounding-box). Additional enrichment models run on tracked objects to add detail: face recognition, license plate recognition, bird classification, custom object and state classification, and the embedding models used for semantic search. [See the object detectors docs for more info](/configuration/object_detectors)
 
 ## Motion
 
-When pixels in the current camera frame are different than previous frames. When many nearby pixels are different in the current frame they grouped together and indicated with a red motion box in the live debug view. [See the motion detection docs for more info](/configuration/motion_detection)
+A change in pixels between the current camera frame and previous frames. When many nearby pixels change together, they are grouped and shown as a red motion box in the debug live view. [See the motion detection docs for more info](/configuration/motion_detection)
+
+## Object
+
+Something Frigate can detect and follow in a camera frame, identified by its [label](#label) (for example a person or a car). The object types Frigate watches for are set in the `objects` configuration. Once an object is detected and followed across frames it becomes a [tracked object](#tracked-object-event-in-previous-versions), which may also carry a [sub label](#sub-label) and [attributes](#attribute). [See the available objects docs for more info](/configuration/objects)
 
 ## Region
 
-A portion of the camera frame that is sent to object detection, regions can be sent due to motion, active objects, or occasionally for stationary objects. These are represented by green boxes in the debug live view.
+A portion of the camera frame sent to the object detection [model](#model). Regions are selected because of [motion](#motion), active objects, or occasionally to recheck stationary objects, and are shown as green boxes in the debug live view.
 
 ## Review Item
 
-A review item is a time period where any number of events/tracked objects were active. [See the review docs for more info](/configuration/review)
+A period of time during which one or more [tracked objects](#tracked-object-event-in-previous-versions) were active, grouped together for review. Each review item is categorized as either an [alert](#alert) or a [detection](#detection). [See the review docs for more info](/configuration/review)
 
 ## Snapshot Score
 
-The score shown in a snapshot is the score of that object at that specific moment in time.
+The object's score at the specific moment the snapshot was captured.
+
+## Sub Label
+
+A more specific identity assigned to a [tracked object](#tracked-object-event-in-previous-versions) in addition to its [label](#label). A `person` may get the name of a recognized face, a `car` may get the name of a known license plate, and a `bird` may get its species. An object can have only one sub label at a time. Sub labels are produced by face recognition, license plate recognition, bird classification, custom object classification configured with the `sub label` type, and semantic search triggers.
 
 ## Threshold
 
-The threshold is the median score that an object must reach in order to be considered a true positive.
+The median score an object must reach to be considered a true positive.
 
 ## Top Score
 
-The top score for an object is the highest median score for an object.
+The highest median score an object reached over its lifetime.
 
 ## Tracked Object ("event" in previous versions)
 
-The time period starting when a tracked object entered the frame and ending when it left the frame, including any time that the object remained still. Tracked objects are saved when it is considered a [true positive](#threshold) and meets the requirements for a snapshot or recording to be saved.
+An [object](#object) followed from the moment it enters the frame until it leaves, including any time it stays still. A tracked object is saved once it is considered a [true positive](#threshold) and meets the requirements for a snapshot or recording.
 
 ## Zone
 
-Zones are areas of interest, zones can be used for notifications and for limiting the areas where Frigate will create a [review item](#review-item). [See the zone docs for more info](/configuration/zones)
+A user-defined area of interest within the camera frame. Zones can be used for notifications and to limit where Frigate creates a [review item](#review-item). [See the zone docs for more info](/configuration/zones)

frigate/config/camera/updater.py

@@ -73,7 +73,12 @@ class CameraConfigUpdateSubscriber:
 
         base_topic = "config/cameras"
 
-        if len(self.camera_configs) == 1:
+        # global subscribers must hear every camera; only narrow per-camera workers
+        is_global_subscriber = (
+            CameraConfigUpdateEnum.add in self.topics
+            or CameraConfigUpdateEnum.remove in self.topics
+        )
+        if not is_global_subscriber and len(self.camera_configs) == 1:
             base_topic += f"/{list(self.camera_configs.keys())[0]}"
 
         self.subscriber = ConfigSubscriber(

frigate/test/test_video.py

@@ -1,3 +1,4 @@
+import io
 import unittest
 
 import cv2
@@ -13,6 +14,7 @@ from frigate.util.object import (
     get_region_from_grid,
     reduce_detections,
 )
+from frigate.video.ffmpeg import _read_frame_into
 
 
 def draw_box(frame, box, color=(255, 0, 0), thickness=2):
@@ -352,3 +354,57 @@ class TestRegionGrid(unittest.TestCase):
 
         region = get_region_from_grid(frame_shape, box, 320, region_grid)
         assert region[2] - region[0] > 320
+
+
+class _ChunkedPipe(io.RawIOBase):
+    """Stub stdout that returns the queued chunks one readinto at a time."""
+
+    def __init__(self, chunks):
+        self._chunks = [bytes(c) for c in chunks]
+
+    def readable(self) -> bool:
+        return True
+
+    def readinto(self, b) -> int:
+        if not self._chunks:
+            return 0
+        chunk = self._chunks.pop(0)
+        n = min(len(b), len(chunk))
+        b[:n] = chunk[:n]
+        if n < len(chunk):
+            self._chunks.insert(0, chunk[n:])
+        return n
+
+
+class TestReadFrameInto(unittest.TestCase):
+    """Cover the partial-read path of the capture loop helper."""
+
+    def test_full_frame_in_one_call(self):
+        buf = bytearray(8)
+        n = _read_frame_into(_ChunkedPipe([b"\x01\x02\x03\x04\x05\x06\x07\x08"]), buf)
+        assert n == 8
+        assert bytes(buf) == b"\x01\x02\x03\x04\x05\x06\x07\x08"
+
+    def test_short_reads_are_reassembled(self):
+        buf = bytearray(8)
+        pipe = _ChunkedPipe([b"\x01\x02\x03", b"\x04\x05", b"\x06\x07\x08"])
+        n = _read_frame_into(pipe, buf)
+        assert n == 8
+        assert bytes(buf) == b"\x01\x02\x03\x04\x05\x06\x07\x08"
+
+    def test_eof_before_full_buffer_returns_partial_count(self):
+        buf = bytearray(8)
+        n = _read_frame_into(_ChunkedPipe([b"\x01\x02\x03"]), buf)
+        assert n == 3
+
+    def test_immediate_eof_returns_zero(self):
+        buf = bytearray(8)
+        n = _read_frame_into(_ChunkedPipe([]), buf)
+        assert n == 0
+
+    def test_writes_into_existing_memoryview(self):
+        backing = bytearray(8)
+        view = memoryview(backing)
+        n = _read_frame_into(_ChunkedPipe([b"abcdefgh"]), view)
+        assert n == 8
+        assert bytes(backing) == b"abcdefgh"

frigate/video/ffmpeg.py

@@ -52,6 +52,32 @@ def _get_record_segment_time(config: CameraConfig) -> int:
         return DEFAULT_RECORD_SEGMENT_TIME
 
 
+def _read_frame_into(stream, buffer) -> int:
+    """Read len(buffer) bytes from stream directly into buffer.
+
+    Returns the number of bytes actually read. A return value less than
+    len(buffer) indicates the stream reached EOF (or the pipe was closed)
+    before the buffer could be filled — the contents of buffer past the
+    returned offset must be treated as undefined.
+
+    BufferedReader.read(n) is documented to return "up to" n bytes, and a
+    subprocess pipe will hand back a short read if the producer closes
+    mid-frame even on a blocking pipe. Reading directly into the
+    pre-allocated frame buffer also avoids the extra Python bytes
+    allocation and copy that ``buffer[:] = stream.read(n)`` performs on
+    every frame.
+    """
+    target = len(buffer)
+    view = memoryview(buffer)
+    pos = 0
+    while pos < target:
+        n = stream.readinto(view[pos:])
+        if not n:
+            return pos
+        pos += n
+    return pos
+
+
 def capture_frames(
     ffmpeg_process: sp.Popen[Any],
     config: CameraConfig,
@@ -92,7 +118,7 @@ def capture_frames(
             frame_name = f"{config.name}_frame{frame_index}"
             frame_buffer = frame_manager.write(frame_name)
             try:
-                frame_buffer[:] = ffmpeg_process.stdout.read(frame_size)
+                bytes_read = _read_frame_into(ffmpeg_process.stdout, frame_buffer)
             except Exception:
                 # shutdown has been initiated
                 if stop_event.is_set():
@@ -110,6 +136,23 @@ def capture_frames(
 
                 continue
 
+            if bytes_read < frame_size:
+                # ffmpeg's stdout pipe was closed (or returned EOF) before
+                # the full frame could be received. The buffer holds a
+                # partial frame, so don't pass it to detection: a
+                # half-frame in shared memory will produce garbage
+                # detections, and continuing to read would resume in the
+                # middle of the next frame, putting capture out of sync
+                # with frame boundaries until the next watchdog restart.
+                if stop_event.is_set():
+                    break
+
+                logger.error(
+                    f"{config.name}: ffmpeg returned an incomplete frame "
+                    f"({bytes_read}/{frame_size} bytes); exiting capture thread..."
+                )
+                break
+
             frame_rate.update()
 
             # don't lock the queue to check, just try since it should rarely be full