initial commit

2026-04-05 17:16:51 -04:00
commit 6bc7cf6318
14 changed files with 1829 additions and 0 deletions
@@ -0,0 +1,74 @@
+# game-stream-app
+
+Low-latency browser-based game streaming to a small group of friends, gated by
+Authentik authentication.
+
+- **Streamer:** Windows PC with an NVIDIA GPU running OBS Studio.
+- **Viewers:** up to ~6 friends, any modern browser, no client install.
+- **Auth:** Authentik forward auth at the Nginx Proxy Manager (NPM) edge.
+- **Transport:** WebRTC (WHEP) for low latency, with LL-HLS fallback.
+- **Latency target:** ~200 ms over WebRTC, ~1-2 s over LL-HLS fallback.
+
+## How it works
+
+```
+OBS Studio (NVENC, WHIP out)
+    -> MediaMTX (localhost) ---> WHEP / HLS / API
+    -> Frontend HTTP server (localhost:8080)
+        -> NPM (TLS, Authentik forward auth, reverse proxy)
+            -> Friend's browser
+```
+
+Everything on the gaming PC (MediaMTX, HTTP server, Windows Firewall rule for
+the WebRTC UDP port) is spawned and torn down by an OBS Python script -
+`obs-script/game_stream.py`. You just click **Start Streaming** in OBS and the
+whole pipeline comes up; click **Stop Streaming** and it all goes away.
+
+## Repository layout
+
+| Path                          | Purpose                                                     |
+|-------------------------------|-------------------------------------------------------------|
+| `config/mediamtx.yml`         | MediaMTX configuration (WHIP in, WHEP/HLS out, locked-down) |
+| `config/npm-advanced.conf`    | Authentik forward-auth snippet for the NPM Advanced tab     |
+| `obs-script/game_stream.py`   | OBS script: lifecycle, HTTP server, firewall toggle         |
+| `frontend/index.html`         | Viewer page                                                 |
+| `frontend/js/player.js`       | WHEP client with HLS fallback                               |
+| `frontend/js/app.js`          | Status polling and DOM glue                                 |
+| `frontend/css/style.css`      | Dark theme                                                  |
+| `scripts/install.ps1`         | Downloads MediaMTX, creates the Windows Firewall rule       |
+| `docs/authentik-setup.md`     | Authentik proxy provider + group configuration              |
+| `docs/npm-setup.md`           | NPM proxy host + stream (UDP) configuration                 |
+| `docs/obs-setup.md`           | OBS encoder + WHIP output settings                          |
+
+## Setup at a glance
+
+1. **Clone** this repo onto the Windows gaming PC.
+2. **Install MediaMTX and the firewall rule:** open an elevated PowerShell in
+   the repo root and run `.\scripts\install.ps1`.
+3. **Configure Authentik** - see `docs/authentik-setup.md`.
+4. **Configure NPM** - see `docs/npm-setup.md`.
+5. **Configure OBS** - see `docs/obs-setup.md`, then add
+   `obs-script/game_stream.py` via Tools -> Scripts.
+6. **Click Start Streaming in OBS.** Friends can now open
+   `https://stream.hetherman.cloud`, log in with Authentik, and watch.
+
+## Security posture
+
+- TLS terminates at NPM with Let's Encrypt.
+- Every request is gated by Authentik forward auth before it reaches the
+  frontend, WHEP signaling, HLS, or the MediaMTX API.
+- MediaMTX only accepts publishers from `127.0.0.1` - nobody on the public
+  internet can hijack the stream.
+- The UDP port used for WebRTC media is opened on the Windows Firewall only
+  while streaming is active (toggled by the OBS script). Even though NPM and
+  the router still forward the port, the OS silently drops packets between
+  streams, so there is no exposed listener.
+- WebRTC media is DTLS-encrypted SRTP. An attacker who hits the UDP port
+  without an Authentik-authenticated WHEP session cannot decrypt or inject
+  media.
+- Removing a friend from the Authentik `stream-viewers` group revokes their
+  access on the next auth_request subrequest (within seconds).
+
+## License
+
+MIT