From 679c6ae7d66428a4d975249c039d2702a5cb294d Mon Sep 17 00:00:00 2001
From: cclohmar <claus.lohmar@lohmar.co.uk>
Date: Sun, 13 Sep 2026 12:30:57 +0100
Subject: [PATCH] docs: document live streaming architecture (go2rtc
 passthrough)

---
 README.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/README.md b/README.md
index 5cb3843..f9f9b6a 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,46 @@ STORAGE_PATH=/mnt/recordings ./deploy_nvr.sh
 
 ---
 
+## How Live Streaming Works
+
+NextNVR doesn't transcode video itself. It delegates all live-stream
+conversion to **go2rtc**, a separate binary it launches as a child process.
+The camera does the encoding — NextNVR and go2rtc pass the stream through
+unchanged.
+
+```
+IP Camera (RTSP)
+   │  sub stream:  /Streaming/Channels/102  (live view)
+   │  main stream: /Streaming/Channels/101  (recording)
+   ▼
+go2rtc (child process, listens on :1984)
+   │  holds persistent RTSP connections, re-serves as WebRTC / MSE / MJPEG
+   ▼
+NextNVR (proxies /go2rtc/ through its own port for a single browser origin)
+```
+
+### Two kinds of "live"
+
+| View | Mechanism | Notes |
+|------|-----------|-------|
+| **Live Wall grid** | 1 fps JPEG snapshot polling | Not a video stream. The snapshot engine grabs a frame every second and writes `latest.jpg`; the browser refreshes it every 3 seconds. Cheap — ideal for an overview. |
+| **Focus view** (click a tile) | Real stream via go2rtc | Opens go2rtc's `stream.html` player, which negotiates **WebRTC → MSE → MJPEG**. Uses the camera **substream** for low bandwidth. |
+
+### Codec & resolution
+
+- **Zero transcoding.** The recorder uses `-c copy` (stream-copy); go2rtc
+  passes the codec through unchanged. The browser receives exactly what the
+  camera encodes.
+- **Codec = your camera's codec.** Set cameras to **H.264** — WebRTC support
+  for H.265/HEVC is poor, and NextNVR will not re-encode it.
+- **Live view uses the substream** (`{id}_sub`); the **main stream**
+  (`{id}_main`) is recorded to disk but is not shown in the live view.
+- **Ports:** go2rtc runs on `:1984`; NextNVR reverse-proxies `/go2rtc/`
+  through its own port so a single origin serves the browser (no mixed-content
+  issues behind HTTPS).
+
+---
+
 ## Where to Store Recordings
 
 NextNVR saves video clips and snapshots to a directory you choose. By default this is `~/nvr_data`. You can change it in **Settings → Storage path** or by editing `config.json`.