zoneminder/docs/stream_socket.rst

Monitor Stream Socket
=====================

Every monitor's ``zmc`` process serves the monitor's compressed media
(video access units and audio packets, as received from the camera) on a
local unix domain socket::

    ZM_PATH_SOCKS/stream_{monitor_id}.sock     e.g. /run/zm/stream_1.sock

The socket replaces the per-monitor media FIFOs
(``video_fifo_{id}.{codec}`` / ``audio_fifo_{id}.{codec}``) that previous
versions created when the RTSPServer option was enabled. Unlike the FIFOs,
the socket is always on, carries both streams on one connection, supports
multiple simultaneous consumers, delivers codec parameters in a handshake,
and makes packet loss observable per consumer. The same connection also
carries monitor lifecycle events (capture faults and analysis-state
changes) as a push channel. ZoneMinder's own ``zm_rtsp_server`` is a
consumer of this socket.

The path follows a fixed convention, so consumers can derive it from
``ZM_PATH_SOCKS`` (zm.conf) and the monitor id. It is also published in the
monitor's shared-memory ``stream_socket_path`` field (exposed by the web
Monitor object and the ``ZoneMinder::Memory`` Perl module) so a reader with
shm access does not need the convention or the producer's zm.conf. Either
way, connect with retry — the socket appears when zmc starts and survives
camera reconnects.

Only cameras that deliver encoded packets (the Ffmpeg source and anything
built on it) announce a media stream. Sources that hand zmc decoded images
(V4L2, MJPEG over HTTP, VNC) have no encoded stream to forward, so their
socket sends no HELLO or MEDIA and carries lifecycle events only.

Access control
--------------

Sockets are created with mode 0660, owned by the ZoneMinder user, with the
group taken from ``ZM_STREAM_SOCKET_GROUP`` (conf.d, defaults to the web
group). Grant a service access by group membership. Optionally,
``ZM_STREAM_SOCKET_ALLOWED_UIDS`` (comma-separated numeric uids) restricts
connections using kernel-verified peer credentials (``SO_PEERCRED`` on
Linux, ``getpeereid`` on the BSDs and macOS).

Per-consumer queue limits are tunable in conf.d:
``ZM_STREAM_SOCKET_MAX_CLIENTS`` (default 8),
``ZM_STREAM_SOCKET_QUEUE_BYTES`` (8 MiB),
``ZM_STREAM_SOCKET_QUEUE_MSGS`` (256) and
``ZM_STREAM_SOCKET_STALL_SECS`` (10). A consumer that exceeds its queue has
its oldest media messages dropped (never HELLO), observable as sequence
gaps and in STATS; a consumer accepting no data while its queue is full is
disconnected. A slow consumer never affects zmc or other consumers.

Wire protocol (version 1)
-------------------------

All integers are little-endian. Every message starts with a 24-byte fixed
header::

    u32  length      bytes following this field (20 + payload size)
    u8   version     protocol version, 1
    u8   type        message type, below
    u8   stream      0 = video, 1 = audio, 2 = monitor (EVENT frames)
    u8   flags       bit 0: keyframe (video); other bits reserved, 0
    u32  sequence    per-stream, counts every message produced
    u32  generation  stream epoch; a bump means re-init the decoder
    i64  pts_us      signed microseconds (AV_TIME_BASE_Q), shared clock;
                     AV_NOPTS_VALUE (0x8000000000000000) means unknown

``sequence`` counts messages *produced*, including any dropped from a slow
consumer's queue, so loss appears as gaps. ``generation`` increments when
stream parameters change (camera reconfigure, a stream added or removed);
fresh HELLOs follow, sequences restart at 0 and the cached keyframe is
dropped. zmc applies both streams' parameters in one step, so a change to
audio and video together is a single new generation and no generation ever
pairs one stream's new parameters with the other's old ones. Generations restart at 0 when zmc restarts, so a consumer should
key on the HELLOs it receives after a (re)connect, not on the number alone.

Message types:

``0x01 HELLO``
  Sent per stream on connect and again on every generation bump, audio
  first: the video HELLO is always the last HELLO of a generation, so on
  receiving it a consumer has that generation's complete parameter set (a
  stream not re-announced by then is gone and its packets stop). A
  generation that carries no video HELLO means the source currently has no
  video; a consumer that needs video waits for the next generation. The
  payload is a TLV list (u8 tag, u16 length, value; unknown tags must be
  skipped): ``0x01`` codec id (u32, AVCodecID), ``0x02`` extradata (raw
  ``codecpar->extradata``: SPS/PPS/VPS for H.26x, AudioSpecificConfig for
  AAC, sequence header OBU for AV1), ``0x03``/``0x04`` width/height (u32),
  ``0x05``/``0x06`` fps numerator/denominator (u32), ``0x07``/``0x08``
  sample rate/channels (u32), ``0x09``/``0x0A`` profile/level (u32).

``0x02 MEDIA``
  One complete video access unit or one audio packet (raw, not
  ADTS-wrapped — the HELLO extradata makes wrapping unnecessary). The
  bytes are exactly what the camera's demuxer produced, so the H.264/H.265
  NAL framing follows the source: RTSP cameras deliver Annex B start
  codes, while MP4/MKV file sources deliver AVCC length-prefixed NALs. A
  consumer can tell which from the HELLO extradata (an AVCC
  ``avcC``/``hvcC`` record starts with ``0x01``; Annex B parameter sets
  start with ``00 00 00 01``). ``zm_rtsp_server`` handles Annex B only.

``0x03 KEYFRAME``
  Sent once after HELLO to a newly connected consumer: the most recent
  cached video keyframe access unit, carrying its original pts. Lets a
  consumer render a first frame immediately instead of waiting up to a
  GOP; treat the next MEDIA keyframe as the stream anchor. The cache is
  cleared when the camera connection closes, so nothing is replayed from
  a previous capture session.

``0x04 STATS``
  Periodic (default every 5 s): u64 messages sent, u64 messages dropped
  for this consumer.

``0x05 BYE``
  zmc is shutting the stream down; the close that follows is not an error.

``0x06 EVENT``
  A monitor lifecycle event (``stream`` is ``2``). This is a push channel
  for capture-fault and analysis-state changes, independent of media: it
  flows even while the camera is disconnected and the media streams are
  stalled. ``sequence`` is a per-monitor event counter (its own series, not
  reset by a media generation bump), ``generation`` is the media epoch in
  effect at emission for correlation, and ``pts_us`` is 0 when no media is
  flowing — the event's own timestamp travels in a TLV.

  The payload is a ``u16`` event code followed by a TLV tail (u8 tag, u16
  length, value; unknown tags skipped). Event codes::

      0x0001 snapshot                current health + state, on connect
      0x0101 connection_failed       camera connect failed
      0x0102 connection_restored
      0x0103 prime_capture_failed    could not prime the capture source
      0x0104 prime_capture_restored
      0x0105 capture_failed          pre/capture/post capture failed
      0x0106 capture_resumed         pipeline recovered after any fault
      0x0201 state_changed           analysis state transition

  TLV tags: ``0x01`` wall_clock_us (u64, unix-epoch microseconds — the
  timestamp to surface), ``0x02`` message (utf8 detail), ``0x03`` state_id
  (u32, current state), ``0x04`` prev_state_id (u32, for state_changed),
  ``0x05`` detail (u32, errno / ffmpeg error code), ``0x06`` state_name
  (utf8, e.g. ``IDLE``/``ALARM``), ``0x07`` health_code (u16, the active
  fault code carried by a faulted snapshot; absent or 0 means healthy).

  ``snapshot`` is sent to every consumer on connect (after the HELLOs, the
  events analogue of the cached KEYFRAME) and is refreshed on every health
  or state change, so a late subscriber learns current status without
  waiting for the next transition. Its ``sequence`` is the number of events
  produced so far, i.e. the sequence the next broadcast EVENT will carry; the
  snapshot is a state message, not an event in that series, so a consumer
  seeds its gap tracking from it and must not treat the following EVENT with
  the same sequence as a duplicate. Both that sequence and the header
  ``generation`` are stamped when the consumer connects, so they describe
  the moment of connection rather than the last status change. The
  capture-fault edges are emitted by
  zmc once per transition; because the socket survives camera reconnects,
  ``connection_failed`` is observable exactly when media has stopped.

There are no client-to-server messages in version 1; zmc ignores inbound
bytes.

The reference encoder/decoder lives in ``src/zm_stream_socket_protocol.h``;
``src/zm_stream_socket_client.cpp`` is a reusable C++ consumer with
callbacks for HELLO, MEDIA/KEYFRAME, STATS, EVENT, BYE and disconnect, and
``tools/zm_stream_socket_dump.py`` is a dependency-free Python example that
prints every message.