zm-py

A lightweight Python API client for ZoneMinder, built specifically for the Home Assistant ZoneMinder integration.

The official Home Assistant ZoneMinder component depends on zm-py==0.5.4. Active development of the integration has moved to nabbi/ha-zoneminder; it is unknown if or when those changes will be submitted back to HA core.

Project Status

This project is in maintenance mode. zm-py provides the limited set of ZoneMinder API interactions that Home Assistant needs (monitors, camera streaming, events, sensors, and switches). Bug fixes and compatibility updates are accepted; new feature development is not planned.

Not pyzm / pyzm2

zm-py is not a general-purpose ZoneMinder Python library. For full-featured ZoneMinder API access, see pyzm or its fork pyzm2. zm-py covers only the subset of the ZoneMinder API required by Home Assistant and carries no heavy dependencies. Replacing zm-py with pyzm or pyzm2 would require significant refactoring of the HA integration due to dependency conflicts and functional differences.

Origins

zm-py is based on code that was originally part of Home Assistant. Historical sources and authorship information is available as part of the Home Assistant project:

• ZoneMinder Platform
• ZoneMinder Camera
• ZoneMinder Sensor
• ZoneMinder Switch

Documentation

• API Reference — all public classes, methods, properties, and enums
• Architecture — package structure, design patterns, caching strategy, Mermaid diagrams
• Architecture diagrams:
  • Package architecture
  • Class relationships
  • Auth & request flow
  • Multi-server URL routing
  • ZoneMinder API endpoints
  • Monitor state model

Installation

PyPI

pip install zm-py

Usage

from zoneminder.zm import ZoneMinder

SERVER_HOST = "{{host}}:{{port}}"
USER = "{{user}}"
PASS = "{{pass}}"
SERVER_PATH = "{{path}}"

zm_client = ZoneMinder(
    server_host=SERVER_HOST,
    server_path=SERVER_PATH,
    username=USER,
    password=PASS,
    verify_ssl=False,
    stream_scale=50,       # optional: scale streams to 50%
    stream_maxfps=5.0,     # optional: cap MJPEG at 5 FPS
)

# Zoneminder authentication
zm_client.login()


# Get all monitors
monitors = zm_client.get_monitors()

for monitor in monitors:
    print(monitor)

>>> Monitor(id='monitor_id', name='monitor_name', controllable='is_controllable')


# Move camera down
controllable_monitors = [m for m in monitors if m.controllable]

for monitor in controllable_monitors:
    zm_client.move_monitor(monitor, "right")