zmesNg Event Notification Server Documentation

Github Repository

What is the Event Server and the ML Ecosystem?

The Event Notification Server (ES) is a companion daemon for ZoneMinder. It monitors ZoneMinder’s shared memory for new events and can push real-time notifications to clients via WebSockets, FCM (push to iOS/Android), and MQTT. It also supports per-monitor notification rules, time-based muting, and integration with zmNinjaNG (the newer-generation app for ZoneMinder).

The ML Ecosystem (zm_detect.py + pyzmNg) is the machine learning detection framework. They take a ZoneMinder event and run it through one or more ML pipelines — supporting multiple model types (object, face, ALPR, etc.). The ML hook is powered by pyzmNg, a standalone ML detection library that can also be used independently.

The ES and the hook can be used together or separately, as described below.

Choose your setup

There are two ways to use ML-powered object detection with ZoneMinder:

Path 1: Detection + optional push (no ES)

Wire zm_detect.py directly to ZoneMinder using EventStartCommand (requires ZM 1.38.1+). ZM calls the detection script automatically when an event starts. No daemon needed — simpler to set up. Can optionally send FCM push notifications directly (requires ZM 1.39.2+). See Path 1: Detection + Optional Push (no ES) for setup instructions.

Path 2: Full Event Server

Install and run the Event Notification Server alongside ZoneMinder. The ES detects new events via shared memory, invokes the ML hooks, and handles push notifications, WebSockets, MQTT, rules, and more. See Path 2: Full Event Server for setup instructions.

Feature comparison

Feature	Path 1	Path 2
Object / face / ALPR detection	✔	✔
Annotated images (objdetect.jpg)	✔	✔
Detection notes written to ZM events	✔	✔
Detection metadata (objects.json)	✔	✔
Local or remote ML (via pyzm.serve)	✔	✔
Push notifications (iOS/Android via FCM)	✔ 1	✔
WebSocket notifications	—	✔
MQTT publishing	—	✔
Notification rules / time-based muting	—	✔
zmNinjaNG integration	—	✔
Per-device monitor filtering (tokens.txt)	—	✔
ES control interface (dynamic config)	—	✔

¹ Path 1 push requires ZM 1.39.2+ and push.enabled: "yes" in objectconfig.yml. Devices register tokens via the ZM Notifications REST API (not tokens.txt). See push_config for setup.

If you only need detection results written to your ZM events (with optional push notifications), Path 1 is simpler to set up. If you need WebSocket notifications, MQTT, notification rules, or the ES control interface, you need Path 2.

See the Installation page for step-by-step setup instructions for either path.

Documentation

Installation

How to install the hooks and/or the Event Server (Path 1 and Path 2)

Machine Learning Hooks

How machine learning detection works, configuration reference

Key Principles — How Detection and Notifications Work

How detection and notifications work (Path 1 and Path 2)

Configuration Guide

How to use config files

Breaking Changes

Breaking changes. Always read this if you are upgrading.

Event Notification Server FAQ

Event Notification Server FAQ (Path 2)

Machine Learning Hooks FAQ

Machine Learning Hooks FAQ

Testing

How to run the unit and e2e test suites

For Developers writing their own consumers

If you want to use the Event Notification Server to make your own app/client

Guidelines for contrib

If you want to contribute hook scripts to the ES

pyzmNg

Documentation for pyzmNg, the ML detection library

zmNinjaNG

Documentation for zmNinjaNG, the newer-generation app for ZoneMinder