# STREAMING.md — 24x7 RTMP desktop stream (reachableceo KDE, #798)

## What runs where
- `ukrrs-rtmp-stream.service` (system, User=reachableceo,
  Slice=ukrrs-rt.slice = cores 6-7, MemoryMax 4G) runs
  `/usr/local/sbin/ukrrs-rtmp-stream.sh` forever:
  finds the newest xorgxrdp X server owned by reachableceo, x11grabs the
  whole screen, encodes (x264 superfast, scaled to 1920w, ~30fps, 6M/9M
  VBR), captures desktop audio if a pulse monitor exists, pushes
  FLV/RTMP to `RTMP_URL`, and self-heals: session gone -> wait; display
  number changed -> follow; resolution changed -> restart encoder;
  ffmpeg died -> respawn in ~5-20s.
- `ukrrs-ultix-rtmp-rx` (compose `rtmp/`, mediamtx 1.20.1 pinned,
  host net, **127.0.0.1:1935 only**) = local receiver for UAT + local
  mirror. Everything else in mediamtx is disabled.
- Host ffmpeg 7.1.5 is pre-installed OS tooling (ruling 2026-09-05,
  #798): intentionally used host-side like open-terminal (#610).

## Config
- Tunables (fps/res/bitrate/preset/user): `/etc/ukrrs/rtmp-stream.env`
- Push target (SECRET once it carries a stream key):
  `~/.creds/rtmp-stream.env` -> `RTMP_URL=rtmp://host:1935/app/key`
  Never anywhere else (not repo, not unit, not logs).
- After editing either: `systemctl restart ukrrs-rtmp-stream`

## Cloudron cutover (when the streaming-server details arrive)
1. Put the ingest URL incl. stream key in `~/.creds/rtmp-stream.env`
   (chmod 600 already; keep one `RTMP_URL=` line).
2. `systemctl restart ukrrs-rtmp-stream`
3. Verify: `journalctl -u ukrrs-rtmp-stream -f` shows `LIVE: ... -> rtmp://<cloudron>`

## Watch it
- Local mirror: `ffplay rtmp://127.0.0.1:1935/live/desktop` (or VLC).
- Ops: `systemctl status ukrrs-rtmp-stream`;
  `journalctl -u ukrrs-rtmp-stream -n 50`.

## Known limits (interim 8 vCPU, all measured 2026-09-05)
- Encode is CPU-bound inside the 2-core rt-slice fence: 1920w superfast
  runs at ~186% of one core (93% of the fence). 2560w veryfast does NOT
  fit (sat the fence at ~13fps) — do not raise until post-#601.
- x11grab on the xorgxrdp X server tops out near ~20 delivered fps on a
  2816x1890 session (GetImage latency, not CPU). Static desktop looks
  perfect; fast full-screen motion is slightly soft. Post-#601 options:
  NVENC (compute cards), or 2560w veryfast on more cores.
- After a reboot there is NO desktop until the human RDPs in (autologin
  off by ruling) — the streamer waits and starts on first session. That
  is "24x7 = whenever the desktop exists".
- Audio rides `auto_null.monitor` (silent dummy) until an RDP client
  forwards audio; the wrapper re-picks the monitor source on every
  (re)start.

## Files
- `staged/ukrrs-rtmp-stream.sh` wrapper (installed to /usr/local/sbin)
- `staged/etc-ukrrs-rtmp-stream.env` tunables template
- `staged/systemd/ukrrs-rtmp-stream.service` unit
- `rtmp/` compose + mediamtx.yml + uat-creds.env (loopback UAT target)
- `18-rtmp-stream.sh` installer (idempotent, self-elevating)
- `19-rtmp-uat.sh` evidence UAT (logs/19-rtmp-uat.out + frames)