Skip to main content

Face Detection & Recognition Camera API

Viewtron AI security cameras include built-in face detection that runs entirely on the camera hardware — no cloud service or external AI software required. When a face is detected in the camera's field of view, the camera sends an HTTP POST webhook to your server with a cropped face image, the full scene image, and face attributes including estimated age, sex, glasses, and mask status.

The camera also supports face recognition (matching) through an on-camera face sample library. When a detected face matches a stored sample, the camera sends a VFD_MATCH event with the match result. Face recognition matching is available on IPC cameras directly — the NVR forwards face detection events (videoFaceDetect) but does not forward match data. 8-channel NVRs support both face detection and face database/recognition, while 4-channel NVRs support face detection only.

What You Can Build​

  • VIP arrival alerts — detect known faces from a stored library and notify staff when important guests or employees arrive
  • Access control integration — grant or deny entry based on face recognition match results
  • Demographic analytics — aggregate age and sex attributes across face detections to understand visitor demographics
  • Mask compliance monitoring — detect whether people are wearing masks in healthcare or clean room environments
  • Face crop archives — save every detected face crop image with timestamp for after-the-fact review
  • Multi-camera face tracking — correlate face detections across camera locations by storing and comparing face crops
  • Attendance systems — log employee arrivals and departures using face recognition matching

How It Works​

  1. Configure face detection on the camera — enable VFD (Video Face Detection) and set sensitivity and detection zones
  2. Enable HTTP POST webhooks — point the camera or NVR at your server's IP and port
  3. Upload face samples (optional) — add face images to the on-camera library for face recognition matching
  4. Your server receives XML when a face is detected — the POST includes a full scene image, cropped face image, and face attributes
  5. Parse the event using the Viewtron Python SDK (pip install viewtron) or Node.js SDK
  6. Take action — save face crops, log attributes to a database, send alerts on recognition matches

Event Data Included​

Each face detection webhook POST contains:

FieldDescription
smartTypeVFD (IPC) or videoFaceDetect (NVR)
targetIdDetection tracking ID
rectFace bounding box coordinates (x1, y1, x2, y2)
ageAge classification: child, young, middleAged, old (NVR v2.0)
sexGender classification: male, female (NVR v2.0)
glassesGlasses detection: yes, no, unknown (NVR v2.0)
maskMask detection: yes, no, unknown (NVR v2.0)
sourceBase64DataFull scene JPEG image (base64 encoded, ~400-500 KB)
targetBase64DataSquare face crop JPEG image (base64 encoded, ~10-20 KB, typically 184x184)
currentTimeDetection timestamp

Face Recognition (VFD_MATCH) — IPC Only​

When a detected face matches a sample in the on-camera library, the IPC sends a VFD_MATCH event with the match result. This event type is IPC only — the NVR does not forward match data.

Face Attribute Values​

AttributePossible Values
agechild, young, middleAged, old
sexmale, female
glassesyes, no, unknown
maskyes, no, unknown

Parsing Face Detection Events​

The simplest way to receive face detection events. The SDK's ViewtronServer handles HTTP connections, keepalives, XML parsing, and version detection — you just write the callback:

pip install viewtron
from viewtron import ViewtronServer
import os

IMG_DIR = "images"
os.makedirs(IMG_DIR, exist_ok=True)

def on_event(event, client_ip):
    if event.category != "face":
        return
    print(f"Face detected from {client_ip}")

    # NVR v2.0 includes face attributes
    age = event.get_face_age()
    sex = event.get_face_sex()
    glasses = event.get_face_glasses()
    mask = event.get_face_mask()
    if age:
        print(f"  Age: {age}, Sex: {sex}, Glasses: {glasses}, Mask: {mask}")

    # Save face crop image
    target = event.get_target_image_bytes()
    if target:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-face-crop.jpg", "wb") as f:
            f.write(target)

    # Save full scene image
    overview = event.get_source_image_bytes()
    if overview:
        with open(f"{IMG_DIR}/{event.get_time_stamp()}-face-scene.jpg", "wb") as f:
            f.write(overview)

server = ViewtronServer(port=5002, on_event=on_event)
server.serve_forever()

See the Python SDK reference for the full list of methods and event classes.

Face Sample Library​

For face recognition (matching), upload face samples to the camera's on-device library. The camera compares detected faces against stored samples and sends VFD_MATCH events when a match is found.

Face library error codes:

CodeDescription
150Face library full
151Face sample already exists
152Face sample not found
153Invalid face image format
154Face not detected in sample image
155Multiple faces in sample image
156Face image too small
157Face image too blurry
158Face library database error
159Face library operation timeout
note

Face recognition (VFD_MATCH) requires an 8-channel NVR or direct IPC connection. 4-channel NVRs support face detection but not face database/recognition. Even with a face database configured on the NVR, only videoFaceDetect events are forwarded via HTTP Post — match data is not included.

Relevant API Endpoints​

EndpointPurposeReference
GetSmartVfdConfigRead face detection configurationFace Detection Config
SetHttpPostConfigConfigure webhook destinationWebhook Config
GetAlarmStatusPoll current alarm state (vfdAlarm)Alarm Status

Integrations​

Viewtron face detection also integrates with automation platforms via published packages:

PlatformPackageWhat It Does
Home Assistantviewtron-home-assistantFace detection events as native HA sensors for access control automations
Node-REDnode-red-contrib-viewtronFace detection events direct to Node-RED flows — no middleware needed

All face detection processing runs on the camera hardware. There is no cloud API dependency, which is important for deployments that need to comply with facial recognition regulations. The NVR v2.0 format includes face attributes (age, sex, glasses, mask) that the IPC v1.x format does not — see the face detection video demo for a walkthrough of both formats.

Questions & Development Inquiries​

Mike Haldas is available for questions, consultation, and custom software development for Viewtron API related projects. Email details about your project to mike@viewtron.com.