Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

NVRDesk Documentation

NVRDesk is an open-source, cross-platform virtual IP camera written in Rust (MIT License) for POS / TPV visual auditing, desktop monitoring, and NVR/VMS streaming.

It converts desktops, screens, webcams, microphones, or external media streams (MP4, MJPEG, RTMP, RTSP) into standard ONVIF Profile S/T, RTSP / RTSPS, and SRT camera feeds with hardware-accelerated encoding and Zero-Idle CPU usage.

Highlights

  • Dual Video Streams: Simultaneous MainStream (/stream1, up to 1080p) and SubStream (/stream2, lightweight preview/AI detection), plus optional dedicated /webcam channel or PiP overlay.
  • POS Visual Auditing: Animated mouse click ripples, borderless PCI-safe keystroke OSD (masked_digits, shortcuts_and_special, all, off), and real-time POS ticket OSD via HTTP & WebSocket.
  • Visual Privacy Masks: Interactive live-preview mask editor in the embedded Web UI to black out PIN pads and sensitive areas before encoding or snapshots.
  • ONVIF Profile S & T: WS-Discovery (239.255.255.250:3702), WS-Security (PasswordDigest), Media / Media2 (H.264 & H.265), Motion + POS PullPoint Events, Two-Way Audio Backchannel, and HTTP JPEG Snapshots.
  • TLS & WAN Delivery: Built-in HTTPS + RTSPS (rustls) and pure-Rust SRT (srt-tokio) over MPEG-TS for branches behind NAT/LTE.
  • Enterprise Fleet Tools: Built-in templates (nvrdesk fleet init|validate), NVRDESK_* env provisioning, Ansible, Windows silent MSI GPO script, systemd, and macOS LaunchAgent.

Next Sections

POS Dynamic OSD & Privacy Masks API

NVRDesk exposes a local HTTP REST and WebSocket API so any POS / retail checkout application (or middleware) can inject real-time overlay text onto video recorded by the NVR/VMS: ticket numbers, active cashier, scanned items, cash drawer opens, voids, or supervisor alerts.

Each injected line renders simultaneously on MainStream, SubStream, and HTTP / MJPEG snapshots, and can optionally emit ONVIF PullPointSubscription events to trigger NVR recording bookmarks or alerts.


Base URL & Prerequisites

  • HTTP: http://<host>:8080 (port configurable via --http-port or [onvif].http_port)
  • HTTPS / WSS: https://<host>:8080 and wss://<host>:8080 (when --https or [tls].https_enabled = true)
  • Prerequisite: The embedded Web UI / HTTP server must remain enabled (daemon.web_ui_enabled = true, default; do not pass --no-web-ui).

HTTP REST Endpoints

1. Inject or Update OSD Text (POST /api/v1/osd/text)

Creates or replaces an OSD line identified by slot. Multiple visible slot entries can coexist simultaneously (sorted alphabetically by slot name).

  • Method & Path: POST /api/v1/osd/text
  • Headers: Content-Type: application/json

JSON Body Fields

FieldTypeRequiredDefaultDescription
textstringYes (unless action="clear")""Text displayed on screen. Sending empty text (or whitespace only) clears that slot.
slotstringNo"ticket"Logical identifier for the line (e.g. "cashier", "ticket", "drawer").
level"info" | "warning" | "alert"No"info"Visual severity: blue accent (info), amber (warning), or red (alert).
ttl_msinteger (u64)Nopos.default_ttl_ms (8000)Time-to-live in milliseconds before auto-expiring. 0 = sticky until explicitly cleared.
emit_eventbooleanNofalseWhen true and text is non-empty, publishes an ONVIF tns1:RuleEngine/PosEvent/Alert event.
action"clear"NonullWhen "clear", clears the specified slot (or all slots if slot is omitted).

Response (200 OK)

Returns a JSON array with currently active OSD lines:

[
  {
    "slot": "ticket",
    "text": "Ticket #4821 | Cashier: Ana | Total: $349.50",
    "level": "warning"
  }
]

2. List Active OSD Lines (GET /api/v1/osd/text)

Returns all non-expired active OSD lines.

curl http://127.0.0.1:8080/api/v1/osd/text

3. Clear a Specific Slot (DELETE /api/v1/osd/text/{slot})

Removes only the specified slot. Returns 204 No Content.

curl -X DELETE http://127.0.0.1:8080/api/v1/osd/text/drawer

4. Clear All Lines (DELETE /api/v1/osd/text)

Immediately clears all active OSD slots. Returns 204 No Content.

curl -X DELETE http://127.0.0.1:8080/api/v1/osd/text

5. Query Recent Events (GET /api/v1/events)

Returns up to the latest 25 events recorded in EventBroker (including tns1:RuleEngine/PosEvent/Alert and tns1:VideoSource/MotionAlarm).

[
  {
    "id": 1,
    "utc_time": "2026-11-21T01:22:10Z",
    "topic": "tns1:RuleEngine/PosEvent/Alert",
    "source_name": "Slot",
    "source_value": "drawer",
    "data_name": "Message",
    "data_value": "alert: MANUAL DRAWER OPEN WITHOUT SALE"
  }
]

WebSocket API (GET /api/v1/ws/osd)

Ideal for POS software updating the ticket on every scanned barcode without opening a new HTTP connection per item.

  • URL: ws://127.0.0.1:8080/api/v1/ws/osd (or wss:// when --https is active)
  • Incoming messages (client -> NVRDesk): JSON text following the same schema as POST /api/v1/osd/text.
  • Outgoing messages (NVRDesk -> client): JSON array with updated active PosOsdLine entries.

Example WebSocket payloads:

{"slot":"cashier","text":"POS 01 | Morning Shift | Luis M.","level":"info","ttl_ms":0}
{"slot":"ticket","text":"SKU 75010553 | Soda 600ml | $22.00","level":"info","ttl_ms":10000}
{"action":"clear","slot":"ticket"}

ONVIF Event Integration (PullPointSubscription)

When "emit_event": true is sent alongside non-empty text:

  1. NVRDesk publishes the event into EventBroker under the ONVIF topic:
    • Topic: tns1:RuleEngine/PosEvent/Alert
    • Source: Name="Slot" Value="<slot>"
    • Data: Name="Message" Value="<level>: <text>"
  2. Any NVR/VMS subscribed to /onvif/events_service via CreatePullPointSubscription + PullMessages receives the <wsnt:NotificationMessage> in real time.

[pos] Configuration & Static Privacy Masks

In nvrdesk.toml (or via PUT /api/v1/config / Web UI interactive Privacy Masks editor):

[pos]
osd_enabled = true
default_ttl_ms = 8000
osd_position = "top_left" # top_left | top_right | bottom_left | bottom_right

[[pos.privacy_masks]]
x = 0.70
y = 0.78
width = 0.28
height = 0.16
label = "PIN PAD"

Coordinate Rules for privacy_masks

  • All coordinates (x, y, width, height) are normalized from 0.0 to 1.0 relative to the output frame dimensions, so they cover the exact same screen region across MainStream (1080p), SubStream (360p), and HTTP snapshots.
  • Masks are drawn as opaque dark rectangles (#0F172A, with optional label if the box is at least ~2 characters x 22 px) before composing POS OSD, keystroke/click overlays, and encoding video or JPEG snapshots.

Code Examples

Bash (curl)

# 1) Display sticky cashier banner (ttl_ms = 0)
curl -X POST http://127.0.0.1:8080/api/v1/osd/text \
  -H "Content-Type: application/json" \
  -d '{"slot":"cashier","text":"Register 02 | Operator: Ana P.","level":"info","ttl_ms":0}'

# 2) Post temporary checkout line (default 8 seconds)
curl -X POST http://127.0.0.1:8080/api/v1/osd/text \
  -H "Content-Type: application/json" \
  -d '{"slot":"ticket","text":"Ticket #4821 | Total: $349.50 | Card","level":"info"}'

# 3) Alert manual cash drawer open and emit ONVIF event
curl -X POST http://127.0.0.1:8080/api/v1/osd/text \
  -H "Content-Type: application/json" \
  -d '{"slot":"drawer","text":"MANUAL DRAWER OPEN","level":"alert","ttl_ms":12000,"emit_event":true}'

Python (requests)

import json

import requests


def send_pos_osd(
    base_url: str,
    slot: str,
    text: str,
    level: str = "info",
    ttl_ms: int = 8000,
    emit_event: bool = False,
) -> list:
    try:
        payload = {
            "slot": slot,
            "text": text,
            "level": level,
            "ttl_ms": ttl_ms,
            "emit_event": emit_event,
        }
        response = requests.post(
            f"{base_url}/api/v1/osd/text",
            headers={"Content-Type": "application/json"},
            data=json.dumps(payload),
            timeout=2.0,
        )
        response.raise_for_status()
        return response.json()
    except requests.RequestException as err:
        print(f"Error sending POS OSD: {err}")
        return []


if __name__ == "__main__":
    send_pos_osd(
        "http://127.0.0.1:8080",
        slot="ticket",
        text="Ticket #4822 | Partial void -$85.00",
        level="warning",
        ttl_ms=10000,
        emit_event=True,
    )

JavaScript / Node.js (fetch + WebSocket)

async function sendPosOsd(baseUrl, payload) {
  const res = await fetch(`${baseUrl}/api/v1/osd/text`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}`);
  }
  return res.json();
}

function connectPosOsdSocket(wsUrl) {
  const ws = new WebSocket(wsUrl);
  ws.addEventListener("open", () => {
    ws.send(JSON.stringify({
      slot: "ticket",
      text: "Ticket #9012 | Scanning items...",
      level: "info",
      ttl_ms: 8000,
    }));
  });
  ws.addEventListener("message", (event) => {
    console.log("Active OSD lines:", JSON.parse(event.data));
  });
  return ws;
}

NVRDesk Fleet Deployment, SRT Relay & Media Sources Guide

Phase 4 introduces enterprise POS fleet provisioning tools, pure-Rust SRT cloud streaming, and FFmpeg-backed additional media sources.


1. Fleet Templates & CLI Provisioning

List built-in POS fleet templates:

nvrdesk fleet templates

Available profiles:

  • pos-cashier: 1080p@15fps H.264, masked_digits PCI keystroke OSD, click ripples, motion events, Zero-Idle.
  • pos-self-checkout: Dual stream + customer PiP webcam + G.711 microphone audio + local ring backup.
  • kiosk-audit: Lightweight 720p@10fps (900 kbps) with shortcuts_and_special keystroke OSD.
  • pci-strict: Input overlays off, bottom-right PIN-PAD privacy mask, HTTPS + RTSPS TLS enabled.
  • cloud-srt: Always-on 1080p@15fps H.264 configured for SRT Caller push + ring backup.

Generate & validate a terminal configuration with deterministic ONVIF UUIDv5 identity:

nvrdesk fleet init pos-cashier \
  --site store-01 \
  --terminal-id caja-04 \
  --camera-name "POS Caja 04" \
  --username admin \
  --password "StrongPassword!" \
  --out /etc/nvrdesk/nvrdesk.toml

nvrdesk fleet validate --config /etc/nvrdesk/nvrdesk.toml

Environment Variables (NVRDESK_*)

Any setting below overrides loaded TOML values automatically (highest precedence stays with explicit CLI flags):

NVRDESK_SITE, NVRDESK_TERMINAL_ID, NVRDESK_CAMERA_NAME, NVRDESK_SERIAL_NUMBER, NVRDESK_BIND, NVRDESK_RTSP_PORT, NVRDESK_HTTP_PORT, NVRDESK_USERNAME, NVRDESK_PASSWORD, NVRDESK_SRT_TARGET, NVRDESK_SRT_PASSPHRASE, NVRDESK_SRT_STREAM_ID, NVRDESK_SOURCE_URI, NVRDESK_CONTROLLER_URL.

Provisioning REST API

  • GET /api/v1/fleet/templates: returns built-in template catalog.
  • POST /api/v1/fleet/apply-template: applies { "template": "pos-cashier", "overrides": { "site": "...", "terminal_id": "..." } } live with disk persistence and hot-reload.
  • GET /api/v1/fleet/manifest: exports inventory JSON (site, terminal_id, device_uuid, endpoints, validation).
  • POST /api/v1/config/validate: validates a candidate NvrDeskConfig JSON payload.

2. Deployment Templates (packaging/fleet/)


3. SRT Cloud / WAN Push (Pure-Rust MPEG-TS over SRT)

Run as SRT Caller pushing encrypted MPEG-TS (7 * 188 = 1316 byte chunks) to a cloud VMS/MediaMTX server:

nvrdesk --no-tray \
  --srt-mode caller \
  --srt-target vms.example.com:9000 \
  --srt-stream-id "#!::r=store-01/pos-01,m=publish" \
  --srt-passphrase "SecretSrtKey123" \
  --srt-latency-ms 120

4. Additional Media Sources (MP4, MJPEG, RTMP, RTSP Relay)

Requires ffmpeg installed on PATH (or --ffmpeg-path). All NVRDesk overlays, privacy masks, POS OSD, snapshots, motion events, dual streams, and SRT push work seamlessly on external sources:

# Loop an MP4 file for NVR/POS testing
nvrdesk --no-tray --source mp4 --source-uri ./samples/pos_demo.mp4

# Convert a legacy HTTP MJPEG camera into ONVIF Profile S/T + RTSP + H.264/H.265
nvrdesk --no-tray --source mjpeg --source-uri http://192.168.1.90/mjpg/video.mjpg

# Restream an RTMP or upstream RTSP feed
nvrdesk --no-tray --source rtmp --source-uri rtmp://127.0.0.1/live/cam1
nvrdesk --no-tray --source rtsp-relay --source-uri rtsp://user:pass@192.168.1.91:554/h264

NVRDesk Public NVR & VMS Compatibility Matrix

NVRDesk implements standard ONVIF Profile S / Profile T (Media2 + Events PullPoint), WS-Discovery (239.255.255.250:3702), RTSP 1.0 (TCP Interleaved & UDP Unicast), RTSPS/HTTPS (rustls), and SRT + MPEG-TS.


Summary Matrix

NVR / VMS PlatformAuto-Discovery (WS-Discovery)Video Codecs (Main / Sub)Auth ModeAudio (G.711) & BackchannelEvents (PullPoint)Notes & Recommended Transport
Hikvision NVR / iVMS-4200SupportedH.264 / H.265RTSP Digest + WS-SecurityPCMU / PCMA + BackchannelMotionAlarm / PosEventUse TCP Interleaved RTSP; keep IDR <= 2s (fps * idr_interval_secs) and fixed ports (8554/8080).
Dahua NVR / SmartPSSSupportedH.264 / H.265RTSP Digest + WS-SecurityPCMU / PCMA + BackchannelMotionAlarm / PosEventEnable RTSP over TCP on NVR channel add; use /snapshot/main for grid thumbnails.
Uniview (UNV) / EZStationSupportedH.264 / H.265RTSP Digest + WS-SecurityPCMU / BackchannelMotionAlarmProfile S (/onvif/media_service) and Profile T (/onvif/media2_service) verified.
Milestone XProtectSupported (ONVIF Driver)H.264 / H.265WS-Security PasswordDigestPCMU + Backchannel (a=recvonly)PullPoint (Events)Select universal ONVIF Conformant driver (1 channel or Main + Sub); HTTPS/RTSPS optional.
Nx Witness / Network OptixSupportedH.264 / H.265RTSP Digest + ONVIFPCMU / BackchannelMotion PullPointAuto-detects dual stream (/stream1 & /stream2) via ONVIF profiles and dedicated /webcam if enabled.
Frigate NVR (go2rtc)Direct RTSP / ONVIFH.264 / H.265 + SRTOptional Digest / Open LANPCMU (go2rtc transcode to Opus/AAC)HTTP /api/v1/events or ONVIFSupports direct rtsp://<host>:8554/stream1 + stream2 detect role (640x360@8fps) or SRT ingest into go2rtc.
Shinobi CCTVONVIF Scanner / RTSPH.264 (recommended)RTSP DigestPCMUMotion webhook / PullPointAdd rtsp://<host>:8554/stream1 with TCP input or pull via /onvif/device_service.
Synology Surveillance StationSupported (ONVIF)H.264 / H.265WS-Security + DigestPCMU / PCMA + BackchannelMotionAlarmSelect ONVIF Generic brand; enable fixed onvif.device_uuid via nvrdesk fleet init for persistent IDs.

Protocol Compatibility Checklist

ONVIF Endpoints (http://<host>:8080 or https://<host>:8080)

  • POST /onvif/device_service: GetDeviceInformation, GetCapabilities, GetServices, GetSystemDateAndTime, GetScopes, GetNetworkInterfaces
  • POST /onvif/media_service (Profile S): GetProfiles, GetStreamUri, GetSnapshotUri, GetVideoEncoderConfigurations, GetAudioEncoderConfigurations
  • POST /onvif/media2_service (Profile T): tr2:GetProfiles, tr2:GetStreamUri, tr2:GetVideoEncoderConfigurations (advertises both H.264 & H.265)
  • POST /onvif/events_service: GetServiceCapabilities, CreatePullPointSubscription, PullMessages, Renew, Unsubscribe
  • GET /snapshot/main, /snapshot/sub, /snapshot/webcam: HTTP JPEG snapshots with privacy masks and POS OSD baked in

RTSP & SRT URLs

  • MainStream: rtsp://<user>:<pass>@<host>:8554/stream1 (alias /stream)
  • SubStream: rtsp://<user>:<pass>@<host>:8554/stream2
  • Dedicated Webcam: rtsp://<user>:<pass>@<host>:8554/webcam
  • RTSPS (TLS): rtsps://<host>:8322/stream1
  • SRT WAN Push (MPEG-TS over SRT): srt://<vms-host>:9000 (with optional AES passphrase + streamid, e.g. #!::r=store-01/pos-01,m=publish)

1. Hikvision / Dahua / Synology Continuous POS Recording

Static POS screens can cause some NVRs to report “No Video” if no frames/keyframes arrive. NVRDesk guarantees constant GOP cadence (idr_interval_secs = 2 default) with SPS/PPS headers repeated on every IDR frame.

Recommended settings:

[main_stream]
codec = "h264"
fps = 15
bitrate_bps = 2000000
idr_interval_secs = 2

[sub_stream]
enabled = true
max_width = 640
fps = 8
bitrate_bps = 450000

2. Frigate NVR config.yml Example

cameras:
  pos_caja_01:
    ffmpeg:
      inputs:
        - path: rtsp://192.168.10.51:8554/stream1
          roles: [record]
        - path: rtsp://192.168.10.51:8554/stream2
          roles: [detect]
    onvif:
      host: 192.168.10.51
      port: 8080
      user: admin
      password: "ChangeMe!"

3. Cloud / Remote Matrix VMS via SRT (MediaMTX / MistServer / OBS / vMix / Nimble)

When POS branches sit behind CG-NAT/LTE without inbound firewall ports, configure NVRDesk in SRT Caller mode:

nvrdesk fleet init cloud-srt --site store-01 --terminal-id pos-02 \
  --srt-target vms.company.com:9000 --srt-passphrase "BranchSecretPass!" --out /etc/nvrdesk/nvrdesk.toml

NVRDesk muxes H.264/H.265 into 1316-byte aligned MPEG-TS (PAT + PMT + PES) chunks in pure Rust (srt-tokio) and pushes them to the central relay with automatic exponential backoff.

NVRDesk Technical Roadmap

NVRDesk is a cross-platform, MIT-licensed virtual IP camera in Rust focused on POS terminal monitoring and general desktop-to-NVR streaming.

Design Principles

  1. MIT-Clean Multimedia Core (Route 1 + Optional FFmpeg):
    • Default pipeline uses native OS hardware encoders (Windows Media Foundation, macOS VideoToolbox, Linux VA-API) and openh264 (BSD-2-Clause) as software fallback.
    • Optional FFmpeg backend via external CLI/pipe adapter (or opt-in feature flag) so official releases remain strictly MIT.
  2. Zero-Idle Encoding:
    • Pause video encoding when no RTSP client or local recorder is active to keep background CPU near 0%.
  3. NVR Compatibility First:
    • Support RTP over TCP Interleaved and UDP Unicast.
    • Maintain constant frame cadence and periodic IDR + SPS/PPS headers even on static POS screens.
    • Provide MainStream + SubStream profiles for NVR live-grid and continuous recording.
  4. POS Security & Auditability:
    • Visible mouse cursor, animated mouse click indicators, and keystroke OSD rendered into both MainStream and SubStream.
    • Configurable privacy masks, digit masking, and sensitive-window exclusions.

Milestones

  • Phase 0 — Foundations & PoC: Cargo workspace, cross-platform CI (Windows/Linux/macOS), screen+cursor -> I420 -> OpenH264 -> RTSP -> VLC/ffplay.
  • Phase 1 — ONVIF Profile S MVP & POS Input Overlay: Dual stream (Main/Sub), global mouse-click + keystroke overlays (nvrdesk-input), RTSP Digest auth, WS-Discovery (239.255.255.250:3702), SOAP Device/Media, HTTP snapshots, validation against ONVIF Device Manager & physical NVRs.
  • Phase 2 — Daemon, Embedded Web UI, Tray & Webcam/Mic: axum + rust-embed Web UI, tray-icon, Windows Session 0 daemon/user-agent split, optional webcam (nokhwa, channel or PiP), optional microphone (cpal G.711/AAC), hardware encoders + optional FFmpeg backend, optional local ring-buffer recording.
  • Phase 3 — POS Integration & Profile T: HTTP/WS dynamic POS ticket OSD API, static privacy masks, H.265/Media2, HTTPS & RTSPS (rustls), audio backchannel, motion/event PullPoint, native installers (.msi, .dmg, .deb).
  • Phase 4 — Enterprise Scale (Completed): Fleet configuration templates (nvrdesk fleet), NVRDESK_* env provisioning, Ansible/GPO/systemd/LaunchAgent templates, pure-Rust SRT (srt-tokio) + MPEG-TS muxer, external MP4/MJPEG/RTMP/RTSP FFmpeg sources, and public VMS/NVR compatibility matrix.