Overview

The Motion detection node detects camera and/or scene motion in the video, adds motion detection metadata to the frame metadata, and can drop frames when there is no motion to reduce downstream processing. This node makes it easy to build use cases such as motion triggered recordings, or to reduce downstream processing when there is no motion.

Inputs & Outputs

Inputs : 1, Media Format : Raw Video
Outputs : 1, Media Format: Raw Video
Output Metadata : MOtion Information

Properties

Property	Description	Type	Default	Required
`detect_camera_motion`	Detects camera view changing (such as pan/tilt/zoom).	`bool`	`false`	No
`detect_scene_motion`	Detects motion in the scene, optionally within specified regions of interest.	`bool`	`true`	No
`roi_labels`	Regions of interest labels	`string`	—	No
`rois`	Optional ROIs for scene motion detection. If defined, motion is only detected within these regions. Leave empty to detect motion in the full frame. Conditional on `roi_labels`. Format: comma-separated normalized `x,y` coordinate pairs; separate multiple polygons with semicolons (for example, `0.1,0.1,0.9,0.1,0.9,0.9`).	`string`	`null`	No
`sensitivity`	Higher sensitivity will detect smaller motions. Range: minimum `0`, maximum `100`. Step: `1`.	`integer`	`50`	No
`display`	Display motion detection state on video?	`bool`	`true`	No
`display_rois`	Display ROI polygons on video?	`bool`	`true`	No
`drop_frames_without_motion`	Drop frames without motion?	`bool`	`false`	No
`processing_interval`	Detect motion every nth frame. Higher values reduce processing load but delay detection. Leave empty to set automatically. Range: minimum `1`, maximum `30`. Step: `1`. Unit: frames.	`integer`	`1`	No
`reference_interval`	Update reference every nth frame. Higher values help detect slow movements better. Leave empty to set automatically. Range: minimum `2`, maximum `30`. Step: `1`. Unit: frames.	`integer`	`null`	No
`no_motion_interval`	Declare motion stopped after n seconds without motion. Leave empty to set automatically. Unit: seconds.	`number`	`null`	No
`processing_resolution`	Processing resolution. Options: Medium (`medium`); Small (`small`).	`enum`	`medium`	No
`thread_number`	Number of threads to use in parallel processing.	`number`	`null`	No
`debug`	Debug mode	`bool`	`false`	No

Output Metadata

The fields below are declared by this node's metadata schema; the JSON values are representative examples.

Path	Type	Description
`nodes.<node_id>.rois.fullframe.motion_delta`	`boolean`	`true` when pixel motion starts or stops
`nodes.<node_id>.rois.fullframe.motion`	`boolean`	`true` while pixel motion is being detected
`nodes.<node_id>.rois.fullframe.motion_score`	`integer`	Current measured amount of motion. A number between 0 and 1 that indicates the extent of detected scene motion. Larger number means higher amount of motion.
`nodes.<node_id>.rois.fullframe.motion_duration`	`integer`	Time in seconds that motion has remained active, when `motion` is True. -1 if `motion` is False
`nodes.<node_id>.rois.fullframe.time_since_motion_stopped`	`number`	Seconds elapsed since motion most recently stopped. -1 if `motion` is currently True.
`nodes.<node_id>.rois.camera.motion_delta`	`boolean`	`true` When camera motion starts or stops
`nodes.<node_id>.rois.camera.motion`	`boolean`	`true` While camera motion is being detected
`nodes.<node_id>.rois.camera.motion_score`	`integer`	Current measured amount of motion.
`nodes.<node_id>.rois.camera.motion_duration`	`integer`	Time in seconds that motion has remained active, when `motion` is True. -1 if `motion` is False.
`nodes.<node_id>.rois.camera.time_since_motion_stopped`	`number`	Seconds elapsed since motion most recently stopped. -1 if `motion` is currently True.
`nodes.<node_id>.rois.camera.motion_info.px`	`number`	Estimated horizontal camera translation in pixels.
`nodes.<node_id>.rois.camera.motion_info.py`	`number`	Estimated vertical camera translation in pixels.
`nodes.<node_id>.rois.camera.motion_info.t`	`number`	Estimated camera rotation in degrees.
`nodes.<node_id>.rois.camera.motion_info.z`	`number`	Estimated camera zoom factor. Numbers less than 1 imply zoom in, more than 1 imply zoom out.
`nodes.<node_id>.rois.<roi_label>.motion`	`boolean`	Value of motion.
`nodes.<node_id>.rois.<roi_label>.motion_delta`	`boolean`	Per-frame change in motion.
`nodes.<node_id>.rois.<roi_label>.motion_duration`	`integer`	Value of motion duration.
`nodes.<node_id>.rois.<roi_label>.motion_info.px`	`number`	Value of px.
`nodes.<node_id>.rois.<roi_label>.motion_info.py`	`number`	Value of py.
`nodes.<node_id>.rois.<roi_label>.motion_info.t`	`number`	Value of t.
`nodes.<node_id>.rois.<roi_label>.motion_info.z`	`number`	Value of z.
`nodes.<node_id>.rois.<roi_label>.motion_score`	`integer`	Value of motion score.
`nodes.<node_id>.rois.<roi_label>.time_since_motion_stopped`	`number`	Value of time since motion stopped.
`nodes.<node_id>.type`	`string`	Identifies the node type that produced this metadata.

JSON example

{
  "nodes": {
    "annotate_motion1": {
      "rois": {
        "camera": {
          "motion": false,
          "motion_delta": false,
          "motion_duration": 0,
          "motion_info": {
            "px": 0.0,
            "py": 0.0,
            "t": 0.0,
            "z": 0.0
          },
          "motion_score": 0,
          "time_since_motion_stopped": 0.0
        },
        "fullframe": {
          "motion": false,
          "motion_delta": false,
          "motion_duration": 0,
          "motion_score": 0,
          "time_since_motion_stopped": 0.0
        }
      },
      "type": "annotate_motion"
    }
  }
}