obs-game-stream-plugin/docs/obs-setup.md

# OBS setup

Configures OBS Studio on the Windows gaming PC to capture the game, encode
with NVENC H.264, and publish via RTMP to the local MediaMTX instance that the
OBS script spawns.

Prerequisites:

- OBS Studio 30.0 or newer.
- FFmpeg installed and on PATH: `winget install Gyan.FFmpeg` (admin PowerShell).
  MediaMTX uses FFmpeg to transcode audio AAC->Opus for WebRTC compatibility.
- You already ran `.\scripts\install.ps1` in an elevated PowerShell, so
  `bin\mediamtx.exe` exists and the `GameStream-UDP-48189` firewall rule is
  registered (in the disabled state).
- **Run OBS as Administrator** so the script can toggle the Windows Firewall
  rule with netsh.

## 1. Load the OBS script

1. OBS -> **Tools -> Scripts -> Python Settings** tab - point it at your Python
   3.11 installation (e.g. `C:\Users\<you>\AppData\Local\Programs\Python\Python311`).
   If OBS shows no properties after loading the script, this is the cause.
2. OBS -> **Tools -> Scripts -> +**
3. Select `obs-script/game_stream.py` from this repo.
4. 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    | `48080` (default)                                             |
   | Firewall rule name    | `GameStream-UDP-48189` (must match the rule created by install.ps1) |
   | Public URL            | `https://stream.hetherman.cloud`                              |
   | MediaMTX API URL      | `http://127.0.0.1:19997`                                      |

5. Check the **Script Log** at the bottom - you should see:
   - `[game_stream] MediaMTX started (pid=...)`
   - `[game_stream] Frontend HTTP server listening on 0.0.0.0:48080`
   - `[game_stream] game_stream.py loaded`

   MediaMTX and the HTTP server start immediately on script load (not on
   streaming started), so they are ready before OBS attempts RTMP.

## 2. OBS output settings

**Settings -> Output**, set **Output Mode** to **Advanced**.

### Streaming tab

| Setting          | Value                                                   |
|------------------|---------------------------------------------------------|
| Audio Encoder    | FFmpeg AAC (only option; MediaMTX+FFmpeg transcodes to Opus for WebRTC) |
| Video Encoder    | **NVIDIA NVENC H.264**                                  |

Use H.264 for maximum browser compatibility (all browsers). HEVC works in
Safari and recent Chrome but not Firefox.

**Encoder settings (H.264):**

| Setting             | Value             |
|---------------------|-------------------|
| Rate Control        | CBR               |
| Bitrate             | 8000-16000 Kbps   |
| Keyframe Interval   | 2 s               |
| Preset              | P5 (Quality)      |
| Tuning              | Ultra Low Latency |
| Multipass           | Two Passes (Quarter Resolution) |
| Profile             | high              |
| Look-ahead          | off               |
| Max B-frames        | **0** (required for low-latency WebRTC) |

### Audio tab

| Setting         | Value      |
|-----------------|------------|
| Audio Bitrate   | 128 Kbps   |
| Sample Rate     | 48 kHz     |

## 3. OBS stream settings

**Settings -> Stream**

| Setting  | Value                                         |
|----------|-----------------------------------------------|
| Service  | Custom                                        |
| Server   | `rtmp://127.0.0.1/game`                       |

> **Note:** Use RTMP (not WHIP). WHIP uses WebRTC which requires ICE/UDP
> negotiation between OBS and MediaMTX - this fails over localhost due to NAT
> hairpin issues. RTMP is plain TCP and works reliably on localhost.

Save.

## 4. First stream

1. Click **Start Streaming**.
2. Check the OBS Script Log - you should see:
   - `[game_stream] Firewall rule 'GameStream-UDP-48189' ENABLED`
   - `[game_stream] OBS streaming started -> viewers can watch at: https://stream.hetherman.cloud`
3. After 2-3 seconds, MediaMTX spawns FFmpeg to transcode the audio. The
   `game-opus` path becomes ready. The stream page will show **LIVE**.
4. Open `https://stream.hetherman.cloud` from another device, log in with
   Authentik, and verify video and audio play. Click the **"Click to play"**
   or **"Click to unmute"** button in the status bar if audio is muted.

## 5. Stopping

Click **Stop Streaming** in OBS. The script will:

- Disable the firewall rule (`GameStream-UDP-48189` -> disabled)

When OBS exits, the script also:

- Stops the MediaMTX subprocess (and with it, the FFmpeg transcoder)
- Stops the frontend HTTP server

Verify the firewall state from PowerShell:

```powershell
Get-NetFirewallRule -DisplayName "GameStream-UDP-48189" | Select-Object Enabled
```

Should report `False` while not streaming, `True` while streaming.

## Troubleshooting

- **No properties panel after loading script:** OBS is using the Microsoft
  Store Python stub. Install real Python 3.11 via `winget install Python.Python.3.11`
  and point OBS Python Settings to the install directory.
- **"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 / streaming fails immediately:** MediaMTX did not start.
  Check the script log for errors. Most commonly a port conflict on 1935, 48889,
  or 48189 (another process is already using them). Also check `bin\mediamtx.log`.
- **Stream page shows "Connecting..." but never goes LIVE:** FFmpeg failed to
  start the `game-opus` transcoder. Check `bin\mediamtx.log` for FFmpeg errors.
  Verify `ffmpeg -version` works in a new PowerShell (not the same session as
  before installing FFmpeg).
- **Viewers see "Stream offline"** even after you click Start Streaming:
  - Check that the MediaMTX API returns `ready: true` for the transcoded path:
    `curl http://localhost:19997/v3/paths/get/game-opus`
  - Check OBS's own streaming indicator - if it's red, OBS is not connected.
    Verify the RTMP server URL is `rtmp://127.0.0.1/game`.
- **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 for UDP 48189 goes to NPM, and the NPM Stream entry
  points at `<PC-LAN-IP>:48189`.
- **No audio:** the "Click to play" or "Click to unmute" button appears in the
  status bar when the browser blocks autoplay. Click it once. If audio is still
  absent, check `bin\mediamtx.log` to confirm FFmpeg started successfully and
  the `game-opus` path shows both H264 and Opus tracks.