Face Detect

Face Detect operator properties for Script Engine. Detects frontal faces in the video stream and reports the bounding box, a quality rating, and (optionally) facial landmarks — eye and mouth aspect ratios, head forward and sideways angles. Can also automatically save snapshots of the best-quality detection to disk as JPEGs, optionally cropped to just the face. Useful for automated headshot capture, presence detection, attention-aware effects, or feeding face metadata to other components in a project.

Property	Type	Access	Description
`PrivateId`	`string`	`get/set`	Private identifier used when accessing the best-result image through the API. Acts as a simple access key — clients reading the saved best-quality image must supply this value. Set to a unique string when exposing the result publicly.
`UseCompRoi`	`bool`	`get/set`	Whether to limit detection to the project's region of interest. [default=false]. When true, only the part of the frame inside the project's region of interest is scanned for faces, which is faster and avoids false positives in irrelevant areas. Disable to scan the full frame.
`ProcessingExpansionPercentage`	`int`	`get/set`	How much area around the last detected face to keep scanning, as a percentage. [min=100, max=500, default=200]. Once a face has been found, the detector concentrates on a region around its last position to save processing time. 100% scans only the last bounding box; higher values expand the scan area, which is more tolerant of fast head movement at a small extra processing cost.
`BoundingBoxOnly`	`bool`	`get/set`	Whether to skip landmark detection and image saving and only report bounding boxes. [default=false]. When true, the operator runs the cheapest possible mode — it just locates faces and reports their bounding box and rating, with no eye/mouth landmarks and no JPEG snapshots to disk. Lock-related settings (landmarks, eye threshold, save-to-disk, JPEG quality) are disabled while this is on. Useful when you only need to know "is there a face, and where" for downstream effects or scripting.
`CropToFace`	`bool`	`get/set`	Whether the operator's output image is cropped to the detected face. [default=false]. When true, the video this operator outputs is cropped down to just the detected face's bounding box — handy for feeding a face-only image into downstream effects. Disable to pass the full frame through unchanged (the detection still happens, it's just not reflected in the output image).
`EnableLandmarkDetection`	`bool`	`get/set`	Whether to detect eye/mouth landmarks and head angles in addition to the face bounding box. [default=false]. When true, the operator also reports `LeftEye`, `RightEye`, `Mouth`, `FaceForwardAngle`, and `FaceSidewaysAngle`. Costs a little more processing time per frame. Cannot be used with `BoundingBoxOnly`.
`EyeApprovalThreshold`	`int`	`get/set`	Minimum eye-aspect-ratio for a detection to count as approved, as a percentage. [min=10, max=60, default=20]. Used to weed out detections where the eyes appear too closed (blinks, looking down) to be considered a good headshot. Lower values are more permissive; higher values only approve detections where the eyes are clearly open.
`MaxResultAge`	`int`	`get/set`	How long the best-quality detection is kept before being replaced, in seconds. [min=5, max=120, default=10]. The operator continuously tracks the best (highest-rated) detection it has seen recently. After this many seconds without a better detection, the best result is reset so a new best can be picked. Shorter values make the "best result" follow recent activity more closely; longer values keep a strong result around longer.
`MinimumSaveInterval`	`int`	`get/set`	Minimum time between consecutive saves to disk, in seconds. [min=1, max=60, default=5]. Prevents the operator from saving snapshots too frequently. Even if a new best detection is found sooner, the operator waits at least this long before writing another file.
`JpegQuality`	`int`	`get/set`	Quality of the saved JPEG snapshot, as a percentage. [min=10, max=100, default=70]. 100 is the highest quality (and largest file); lower values produce smaller files with more visible compression artefacts. 70 is a typical balance for archival snapshots.
`BestResultFileName`	`string`	`get/set`	Filename used for the best-result JPEG saved to disk. Just the file name (without path). The full path is built from `CustomTargetPath` plus this name. Existing files with the same name are overwritten on each save.
`CustomTargetPath`	`String`	`get/set`	Custom directory the best-result snapshot is written to. Leave empty to use the project's default snapshot folder. Set to an absolute path to write the file somewhere else — for example a network share so other systems can read it.
`EnableSaveToDisk`	`bool`	`get/set`	Whether to save the best detection to disk as a JPEG. [default=false]. When true, the operator periodically writes the current best-quality detection to `CustomTargetPath`/`BestResultFileName`, no faster than `MinimumSaveInterval` seconds apart. Disable to keep face detection in-memory only.
`LastSavedResultFile`	`string`	`get`	Full path of the most recently saved snapshot file (read-only). Updated automatically each time the operator writes a new best-result image. Useful for scripts that need to know which file to read or upload.
`FaceFound`	`bool`	`get`	True while a face is currently detected in the frame (read-only). Useful from a script to react to presence — for example, only show overlay graphics when there's actually a face on screen.
`FaceBoundingBox`	`string`	`get`	Bounding box of the detected face as a JSON string (read-only). Format: `{"x":0,"y":0,"width":0,"height":0}`. Coordinates are in pixels relative to the input frame. Easy to parse from a script that needs to drive other components (cropping, blurring, overlays) at the face's location.
`FaceRating`	`double`	`get`	Quality rating of the most recent detection (read-only). A higher value is a stronger, more confident detection. Used internally to pick the "best" result to save to disk; available to scripts as a confidence score.
`LeftEye`	`double`	`get`	Left-eye openness, as an aspect ratio (read-only). Higher values mean the eye appears more open; lower values suggest a blink or a closed eye. Only populated when `EnableLandmarkDetection` is true. Useful for blink detection or attention scoring.
`RightEye`	`double`	`get`	Right-eye openness, as an aspect ratio (read-only). See `LeftEye`. Only populated when `EnableLandmarkDetection` is true.
`Mouth`	`double`	`get`	Mouth openness, as an aspect ratio (read-only). Higher values mean the mouth is more open. Only populated when `EnableLandmarkDetection` is true. Useful for talking-head detection or simple "is the person speaking" hints.
`FaceForwardAngle`	`double`	`get`	Forward (nodding) angle of the head, in degrees (read-only). 0 means the head is upright; positive values lean forward (chin down), negative values lean back (chin up). Only populated when `EnableLandmarkDetection` is true.
`FaceSidewaysAngle`	`double`	`get`	Sideways (turning) angle of the head, in degrees (read-only). 0 means the head is facing the camera straight on; positive values turn one way, negative the other. Only populated when `EnableLandmarkDetection` is true. Useful for filtering out side-profile shots when picking the best headshot.
`MiniLog`	`FormattedMessage`	`get`	Most recent status, info, or error message from the operator (read-only). The operator writes here when it loads, when it saves a snapshot, when a new best detection is picked, or when something goes wrong.
`FacesFound`	`int`	`get`	Total number of frames in which a face was detected since the operator started (read-only).
`SavedResults`	`int`	`get`	Total number of best-result snapshots saved to disk since the operator started (read-only). Only grows while `EnableSaveToDisk` is true.
`ResultQueueSize`	`int`	`get`	Number of pending detection results waiting to be processed (read-only, debug). Should sit close to zero on a healthy system. A growing queue suggests detection is running slower than the incoming frame rate.
`JpegPerformance`	`string`	`get`	Time spent compressing the most recent snapshot to JPEG, formatted as a millisecond string (read-only, debug).
`FaceDetectionTime`	`string`	`get`	Time spent detecting the face on the most recent frame, formatted as a millisecond string (read-only, debug).
`FaceFeatureDetectionTime`	`string`	`get`	Time spent detecting facial landmarks on the most recent frame, formatted as a millisecond string (read-only, debug). Only meaningful when `EnableLandmarkDetection` is true.
`FaceProcessingTime`	`string`	`get`	Total per-frame processing time for the operator, formatted as a millisecond string (read-only, debug). Sum of detection, landmark detection, and JPEG compression. Useful for monitoring the operator's overall load on the pipeline.

Inherits from: AbstractOperator, AbstractAudioMetering.

See also: Face Detect in Operators — user-facing introduction, screenshots, and section summaries.