diff --git a/docs/docs/configuration/motion_detection.md b/docs/docs/configuration/motion_detection.md index a1937595a..53e63272a 100644 --- a/docs/docs/configuration/motion_detection.md +++ b/docs/docs/configuration/motion_detection.md @@ -110,18 +110,18 @@ Some cameras, like doorbell cameras, may have missed detections when someone wal motion: # Optional: Fraction of the frame that must change in a single update # before Frigate will completely ignore any motion in that frame. - # Values range between 0.0 and 1.0, where 1.0 (the default) means - # the feature is disabled. Setting this to 0.7 would cause Frigate to - # **skip** reporting motion boxes when more than 70% of the image - # appears to change (e.g. during lightning storms, IR/color mode - # switches, or other sudden lighting events). - skip_motion_threshold: 1.0 + # Values range between 0.0 and 1.0, leave unset (null) to disable. + # Setting this to 0.7 would cause Frigate to **skip** reporting + # motion boxes when more than 70% of the image appears to change + # (e.g. during lightning storms, IR/color mode switches, or other + # sudden lighting events). + skip_motion_threshold: 0.7 ``` This option is handy when you want to prevent large transient changes from triggering recordings or object detection. It differs from `lightning_threshold` because it completely suppresses motion instead of just forcing a recalibration. :::warning -When the skip threshold is exceeded, **no motion is reported** for that frame. That means you can miss something important, like a PTZ camera auto-tracking an object or activity while the camera is moving. If you prefer to guarantee that every frame is saved, leave motion enabled and accept occasional recordings containing scene noise — they typically only take up a few megabytes and are quick to scan in the timeline UI. +When the skip threshold is exceeded, **no motion is reported** for that frame, meaning **nothing is recorded** for that frame. That means you can miss something important, like a PTZ camera auto-tracking an object or activity while the camera is moving. If you prefer to guarantee that every frame is saved, leave this unset and accept occasional recordings containing scene noise — they typically only take up a few megabytes and are quick to scan in the timeline UI. ::: diff --git a/docs/docs/configuration/reference.md b/docs/docs/configuration/reference.md index 4a33c90ca..cac508195 100644 --- a/docs/docs/configuration/reference.md +++ b/docs/docs/configuration/reference.md @@ -485,10 +485,11 @@ motion: # Increasing this value will make motion detection more likely to consider lightning or ir mode changes as valid motion. # Decreasing this value will make motion detection more likely to ignore large amounts of motion such as a person approaching a doorbell camera. lightning_threshold: 0.8 - # Optional: The percentage of the image used to detect lightning or other substantial changes where motion detection needs to recalibrate - # When this threshold is exceeded the frame is entirely skipped for motion processing and **no motion recording** is retained. - # Use with care on PTZ cameras or other situations where you require guaranteed frame capture. - skip_motion_threshold: 1.0 + # Optional: Fraction of the frame that must change in a single update before motion boxes are completely + # ignored. Values range between 0.0 and 1.0. When exceeded, no motion boxes are reported and **no motion + # recording** is created for that frame. Leave unset (null) to disable this feature. Use with care on PTZ + # cameras or other situations where you require guaranteed frame capture. + skip_motion_threshold: None # Optional: Minimum size in pixels in the resized motion image that counts as motion (default: shown below) # Increasing this value will prevent smaller areas of motion from being detected. Decreasing will # make motion detection more sensitive to smaller moving objects. diff --git a/frigate/config/camera/motion.py b/frigate/config/camera/motion.py index fd699b7e1..ebba8613c 100644 --- a/frigate/config/camera/motion.py +++ b/frigate/config/camera/motion.py @@ -28,10 +28,10 @@ class MotionConfig(FrigateBaseModel): ge=0.3, le=1.0, ) - skip_motion_threshold: float = Field( - default=1.0, + skip_motion_threshold: Optional[float] = Field( + default=None, title="Skip motion threshold", - description="If more than this fraction of the image changes in a single frame, the detector will return no motion boxes and immediately recalibrate. This can save CPU and reduce false positives during lightning, storms, etc., but may miss real events such as a PTZ camera auto‑tracking an object. The trade‑off is between dropping a few megabytes of recordings versus reviewing a couple short clips. Range 0.0 to 1.0.", + description="If set to a value between 0.0 and 1.0, and more than this fraction of the image changes in a single frame, the detector will return no motion boxes and immediately recalibrate. This can save CPU and reduce false positives during lightning, storms, etc., but may miss real events such as a PTZ camera auto‑tracking an object. The trade‑off is between dropping a few megabytes of recordings versus reviewing a couple short clips. Leave unset (None) to disable this feature.", ge=0.0, le=1.0, ) diff --git a/frigate/motion/improved_motion.py b/frigate/motion/improved_motion.py index c91b585f8..b821e9532 100644 --- a/frigate/motion/improved_motion.py +++ b/frigate/motion/improved_motion.py @@ -182,8 +182,11 @@ class ImprovedMotionDetector(MotionDetector): # note: skipping means the frame is dropped and **no recording will be # created**, which could hide a legitimate object if the camera is actively # auto‑tracking. the alternative is to allow motion and accept a small - # recording that can be reviewed in the timeline. - if pct_motion > self.config.skip_motion_threshold: + # recording that can be reviewed in the timeline. disabled by default (None). + if ( + self.config.skip_motion_threshold is not None + and pct_motion > self.config.skip_motion_threshold + ): # force a recalibration so we transition to the new background self.calibrating = True return [] diff --git a/frigate/test/test_motion_detector.py b/frigate/test/test_motion_detector.py index 8dd2cdfaa..cdf4210a5 100644 --- a/frigate/test/test_motion_detector.py +++ b/frigate/test/test_motion_detector.py @@ -51,11 +51,11 @@ class TestImprovedMotionDetector(unittest.TestCase): return frame def test_skip_motion_threshold_default(self): - """With the default (1.0) setting, motion should still be reported.""" + """With the default (None) setting, motion should always be reported.""" frame = self._half_change_frame() boxes = self.detector.detect(frame) self.assertTrue( - boxes, "Expected motion boxes when skip threshold is at default" + boxes, "Expected motion boxes when skip threshold is unset (disabled)" ) def test_skip_motion_threshold_applied(self): diff --git a/web/src/types/frigateConfig.ts b/web/src/types/frigateConfig.ts index d49368846..dcf3c312f 100644 --- a/web/src/types/frigateConfig.ts +++ b/web/src/types/frigateConfig.ts @@ -106,7 +106,7 @@ export interface CameraConfig { frame_height: number; improve_contrast: boolean; lightning_threshold: number; - skip_motion_threshold: number; + skip_motion_threshold: number | null; mask: { [maskId: string]: { friendly_name?: string;