Face Detection Events

Face detection events are generated when a camera detects a human face. All face events have category === 'face'.

The SDK uses a single ViewtronEvent object for both IPC and NVR face events. The difference is the source format:

• IPC v1.x -- smartType VFD (face detection) or VFD_MATCH (face match against database)
• NVR v2.0 -- smartType videoFaceDetect

Your code does not need to distinguish between them for basic face detection. Both set category to 'face' and provide source/target images. The difference is that NVR v2.0 populates the face property with demographic attributes (age, sex, glasses, mask), while IPC events leave it null.

Properties

All face events include the common ViewtronEvent properties:

Property	Type	Description
category	string	Always 'face'
eventType	string	Raw alarm code: 'VFD', 'VFD_MATCH' (IPC), or 'videoFaceDetect' (NVR)
eventDescription	string	'Face Detection' or 'Face Match'
source	string	'IPC' or 'NVR'
cameraName	string	Device name
cameraIp	string	Camera IP (NVR only)
cameraMac	string	Camera MAC address (NVR only)
channelId	string	NVR channel number (NVR only)
timestamp	string	Event timestamp from camera
sourceImage	string	Base64-encoded overview image
targetImage	string	Base64-encoded face crop image
sourceImageBytes	Buffer|null	Decoded overview image (lazy)
targetImageBytes	Buffer|null	Decoded face crop image (lazy)
hasImages	boolean	true if any image data is present

NVR Face Attributes

The face property is an object on NVR v2.0 events, or null on IPC events:

Property	Type	Description
face	object|null	null on IPC; object with attributes on NVR
face.age	string	Estimated age (e.g., '25', '35')
face.sex	string	'male' or 'female'
face.glasses	string	'yes' or 'no'
face.mask	string	'yes' or 'no'

All four attribute values are empty strings if the attribute is not present in the XML payload.

IPC vs NVR Comparison

Feature	IPC (v1.x)	NVR (v2.0)
Face detected	Yes	Yes
Age estimate	No (face is null)	Yes
Sex	No	Yes
Glasses	No	Yes
Mask	No	Yes
Face crop image	Yes (targetImage)	Yes (targetImage)
Overview image	Yes (sourceImage)	Yes (sourceImage)
Camera IP / MAC	No	Yes
Channel ID	No	Yes

Code Examples

Basic Face Detection

Works with both IPC and NVR events:

const { ViewtronServer } = require('viewtron-sdk');

const server = new ViewtronServer({ port: 5050 });

server.on('event', (event, clientIP) => {
  if (event.category === 'face') {
    console.log(`Face detected on ${event.cameraName} from ${clientIP}`);
    console.log(`  Type: ${event.eventDescription}`);
    console.log(`  Time: ${event.timestamp}`);
  }
});

server.start();

NVR Face Attributes

Check for the face property to access demographic data:

server.on('event', (event, clientIP) => {
  if (event.category === 'face') {
    console.log(`Face detected on ${event.cameraName}`);

    // NVR v2.0 provides demographic attributes
    if (event.face) {
      console.log(`  Age: ${event.face.age}`);
      console.log(`  Sex: ${event.face.sex}`);
      console.log(`  Glasses: ${event.face.glasses}`);
      console.log(`  Mask: ${event.face.mask}`);
    }
  }
});

You can also check event.source === 'NVR', but checking event.face directly is simpler and more reliable -- it tells you whether the data is actually present.

Saving Face Crop Images

Every face event includes two images -- an overview (source) showing the full scene, and a crop (target) showing just the detected face:

const fs = require('fs');

server.on('event', (event, clientIP) => {
  if (event.category === 'face') {
    const ts = Date.now();

    // Save the overview image
    if (event.sourceImageBytes) {
      fs.writeFileSync(`face_${ts}_scene.jpg`, event.sourceImageBytes);
    }

    // Save the cropped face image
    if (event.targetImageBytes) {
      fs.writeFileSync(`face_${ts}_crop.jpg`, event.targetImageBytes);
    }
  }
});

sourceImageBytes and targetImageBytes are Buffer objects decoded lazily from the base64 sourceImage and targetImage strings. They return null if no image data is present.

IPC Limitations

IPC v1.x face detection provides:

• Face detected notification (smartType VFD or VFD_MATCH)
• Source image (overview) and target image (face crop)
• Camera name and timestamp

It does not provide age, sex, glasses, or mask attributes. The face property is null on all IPC events. Demographic attributes require an NVR running firmware v2.0+.

Related Pages

• ViewtronEvent -- common properties and category routing
• Images -- working with face crop and overview images
• API Reference: Face Detection -- raw XML endpoint documentation