initial commit

2026-04-05 17:16:51 -04:00
commit 6bc7cf6318
14 changed files with 1829 additions and 0 deletions
@@ -0,0 +1,132 @@
+# OBS setup
+
+Configures OBS Studio on the Windows gaming PC to capture the game, encode
+with NVENC, and publish via WHIP to the local MediaMTX instance that the OBS
+script spawns.
+
+Prerequisites:
+
+- OBS Studio 30.0 or newer (WHIP output is built in from 30.x onward).
+- You already ran `.\scripts\install.ps1` in an elevated PowerShell, so
+  `bin\mediamtx.exe` exists and the `GameStream-UDP-8189` firewall rule is
+  registered (in the disabled state).
+
+## 1. Load the OBS script
+
+1. OBS -> **Tools -> Scripts -> +**
+2. Select `obs-script/game_stream.py` from this repo.
+3. In the properties panel on the right, set:
+
+   | Setting               | Value                                                         |
+   |-----------------------|---------------------------------------------------------------|
+   | MediaMTX binary       | `<repo>\bin\mediamtx.exe`                                     |
+   | MediaMTX config       | `<repo>\config\mediamtx.yml`                                  |
+   | Frontend directory    | `<repo>\frontend`                                             |
+   | Frontend HTTP port    | `8080` (default)                                              |
+   | Firewall rule name    | `GameStream-UDP-8189` (must match the rule created by install.ps1) |
+   | Public URL            | `https://stream.hetherman.cloud`                              |
+   | MediaMTX API URL      | `http://127.0.0.1:9997`                                       |
+
+4. Check the **Script Log** at the bottom - you should see
+   `[game_stream] game_stream.py loaded`.
+
+## 2. OBS output settings
+
+**Settings -> Output**, set **Output Mode** to **Advanced**.
+
+### Streaming tab
+
+| Setting          | Value                                                   |
+|------------------|---------------------------------------------------------|
+| Audio Encoder    | Opus (or FFmpeg AAC if Opus is unavailable - Opus is preferred for WebRTC) |
+| Video Encoder    | **NVIDIA NVENC HEVC** or **NVIDIA NVENC H.264**         |
+
+Use H.264 for maximum browser compatibility (all browsers). HEVC works in
+Safari and recent Chrome but not Firefox - stick with H.264 unless you have a
+specific reason.
+
+**Encoder settings (H.264):**
+
+| Setting             | Value             |
+|---------------------|-------------------|
+| Rate Control        | CBR               |
+| Bitrate             | 8000 Kbps         |
+| Keyframe Interval   | 2 s               |
+| Preset              | P5 (Quality)      |
+| Tuning              | Ultra Low Latency |
+| Multipass           | Two Passes (Quarter Resolution) |
+| Profile             | high              |
+| Look-ahead          | off               |
+| Psycho Visual Tuning | on               |
+| GPU                 | 0                 |
+| Max B-frames        | **0** (required for low-latency WebRTC) |
+
+With a 600 Mbps upload and up to 6 viewers at 8 Mbps each, 8000 Kbps leaves
+generous headroom. Push to 12000-15000 Kbps if you want higher quality.
+
+### Audio tab
+
+| Setting         | Value      |
+|-----------------|------------|
+| Audio Bitrate   | 128 Kbps   |
+| Sample Rate     | 48 kHz     |
+
+## 3. OBS stream settings
+
+**Settings -> Stream**
+
+| Setting  | Value                                         |
+|----------|-----------------------------------------------|
+| Service  | Custom                                        |
+| Protocol | **WHIP**                                      |
+| Server   | `http://localhost:8889/game/whip`             |
+| Bearer Token | (leave blank)                             |
+
+Save.
+
+## 4. First stream
+
+1. Click **Start Streaming**.
+2. Check the OBS Script Log - you should see:
+   - `Firewall rule 'GameStream-UDP-8189' ENABLED`
+   - `MediaMTX started (pid=...)`
+   - `Frontend HTTP server listening on 0.0.0.0:8080`
+   - `Viewers can watch at: https://stream.hetherman.cloud`
+3. Open `https://stream.hetherman.cloud` from another device, log in with
+   Authentik, and verify video plays.
+
+## 5. Stopping
+
+Click **Stop Streaming** in OBS. The script will:
+
+- Stop the MediaMTX subprocess
+- Stop the frontend HTTP server
+- Disable the firewall rule (`GameStream-UDP-8189` -> disabled)
+
+Verify the firewall state from PowerShell:
+
+```powershell
+Get-NetFirewallRule -DisplayName "GameStream-UDP-8189" | Select-Object Enabled
+```
+
+Should report `False` while not streaming, `True` while streaming.
+
+## Troubleshooting
+
+- **"MediaMTX binary not found"** in the script log: the path in the script
+  properties panel is wrong. Re-select it with the file picker.
+- **OBS cannot connect to WHIP**: MediaMTX did not start. Check the script
+  log for the actual reason; most commonly a port conflict on 8889 or 8189
+  (another process is already using them).
+- **Viewers see "Stream offline"** even after you click Start Streaming:
+  - Check that the MediaMTX API returns `ready: true`:
+    `curl http://localhost:9997/v3/paths/get/game`
+  - Check OBS's own streaming indicator - if it's red, OBS is not actually
+    sending to WHIP. Verify the URL and that the custom service / WHIP
+    protocol is selected.
+- **Viewers connect but playback freezes after a few seconds:** the UDP port
+  path is broken. Verify the firewall rule is enabled (`Get-NetFirewallRule`),
+  the router port-forward to NPM for UDP 8189 is correct, and the NPM Stream
+  entry points at `<PC-LAN-IP>:8189`.
+- **Autoplay is blocked / no audio:** browsers start the video muted so
+  autoplay works. There is a "Click to unmute" button in the status bar.