# 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.