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) andSubStream(/stream2, lightweight preview/AI detection), plus optional dedicated/webcamchannel 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 + POSPullPointEvents, 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 macOSLaunchAgent.
Next Sections
- POS Dynamic OSD & Privacy API
- Fleet Deployment, SRT & Media Sources
- NVR & VMS Compatibility Matrix
- Technical Roadmap
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-portor[onvif].http_port) - HTTPS / WSS:
https://<host>:8080andwss://<host>:8080(when--httpsor[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
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
text | string | Yes (unless action="clear") | "" | Text displayed on screen. Sending empty text (or whitespace only) clears that slot. |
slot | string | No | "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_ms | integer (u64) | No | pos.default_ttl_ms (8000) | Time-to-live in milliseconds before auto-expiring. 0 = sticky until explicitly cleared. |
emit_event | boolean | No | false | When true and text is non-empty, publishes an ONVIF tns1:RuleEngine/PosEvent/Alert event. |
action | "clear" | No | null | When "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(orwss://when--httpsis 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
PosOsdLineentries.
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:
- NVRDesk publishes the event into
EventBrokerunder the ONVIF topic:- Topic:
tns1:RuleEngine/PosEvent/Alert - Source:
Name="Slot" Value="<slot>" - Data:
Name="Message" Value="<level>: <text>"
- Topic:
- Any NVR/VMS subscribed to
/onvif/events_serviceviaCreatePullPointSubscription+PullMessagesreceives 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 from0.0to1.0relative to the output frame dimensions, so they cover the exact same screen region acrossMainStream(1080p),SubStream(360p), and HTTP snapshots. - Masks are drawn as opaque dark rectangles (
#0F172A, with optionallabelif 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_digitsPCI 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) withshortcuts_and_specialkeystroke OSD.pci-strict: Input overlays off, bottom-rightPIN-PADprivacy 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 candidateNvrDeskConfigJSON payload.
2. Deployment Templates (packaging/fleet/)
- Linux Ansible:
packaging/fleet/ansible/nvrdesk-pos.yml - Linux
systemdunit:packaging/fleet/linux/nvrdesk.service - Windows GPO / Silent MSI PowerShell:
packaging/fleet/windows/Install-NvrDeskPos.ps1(installs.msi, provisions config, opens firewall ports 8554/8080/3702, schedules interactive user-session task to bypass Session 0 capture isolation) - macOS
LaunchAgent:packaging/fleet/macos/com.nvrdesk.agent.plist
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 Platform | Auto-Discovery (WS-Discovery) | Video Codecs (Main / Sub) | Auth Mode | Audio (G.711) & Backchannel | Events (PullPoint) | Notes & Recommended Transport |
|---|---|---|---|---|---|---|
| Hikvision NVR / iVMS-4200 | Supported | H.264 / H.265 | RTSP Digest + WS-Security | PCMU / PCMA + Backchannel | MotionAlarm / PosEvent | Use TCP Interleaved RTSP; keep IDR <= 2s (fps * idr_interval_secs) and fixed ports (8554/8080). |
| Dahua NVR / SmartPSS | Supported | H.264 / H.265 | RTSP Digest + WS-Security | PCMU / PCMA + Backchannel | MotionAlarm / PosEvent | Enable RTSP over TCP on NVR channel add; use /snapshot/main for grid thumbnails. |
| Uniview (UNV) / EZStation | Supported | H.264 / H.265 | RTSP Digest + WS-Security | PCMU / Backchannel | MotionAlarm | Profile S (/onvif/media_service) and Profile T (/onvif/media2_service) verified. |
| Milestone XProtect | Supported (ONVIF Driver) | H.264 / H.265 | WS-Security PasswordDigest | PCMU + Backchannel (a=recvonly) | PullPoint (Events) | Select universal ONVIF Conformant driver (1 channel or Main + Sub); HTTPS/RTSPS optional. |
| Nx Witness / Network Optix | Supported | H.264 / H.265 | RTSP Digest + ONVIF | PCMU / Backchannel | Motion PullPoint | Auto-detects dual stream (/stream1 & /stream2) via ONVIF profiles and dedicated /webcam if enabled. |
Frigate NVR (go2rtc) | Direct RTSP / ONVIF | H.264 / H.265 + SRT | Optional Digest / Open LAN | PCMU (go2rtc transcode to Opus/AAC) | HTTP /api/v1/events or ONVIF | Supports direct rtsp://<host>:8554/stream1 + stream2 detect role (640x360@8fps) or SRT ingest into go2rtc. |
| Shinobi CCTV | ONVIF Scanner / RTSP | H.264 (recommended) | RTSP Digest | PCMU | Motion webhook / PullPoint | Add rtsp://<host>:8554/stream1 with TCP input or pull via /onvif/device_service. |
| Synology Surveillance Station | Supported (ONVIF) | H.264 / H.265 | WS-Security + Digest | PCMU / PCMA + Backchannel | MotionAlarm | Select 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,GetNetworkInterfacesPOST /onvif/media_service(Profile S):GetProfiles,GetStreamUri,GetSnapshotUri,GetVideoEncoderConfigurations,GetAudioEncoderConfigurationsPOST /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,UnsubscribeGET /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)
Recommended NVR / VMS Quirks & Tuning
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
- 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.
- Default pipeline uses native OS hardware encoders (Windows Media Foundation, macOS VideoToolbox, Linux VA-API) and
- Zero-Idle Encoding:
- Pause video encoding when no RTSP client or local recorder is active to keep background CPU near 0%.
- 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.
- 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), SOAPDevice/Media, HTTP snapshots, validation against ONVIF Device Manager & physical NVRs. - Phase 2 — Daemon, Embedded Web UI, Tray & Webcam/Mic:
axum+rust-embedWeb UI,tray-icon, Windows Session 0 daemon/user-agent split, optional webcam (nokhwa, channel or PiP), optional microphone (cpalG.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.