# Spout-to-NDI Normalizer — Unity integration

This drop folder contains:

- `spout_ndi_normalizer.exe` — the normalizer
- `SpoutNdiLauncher.cs` — Unity launcher component
- `README.md` — this file

## Quick start

1. Copy `spout_ndi_normalizer.exe` into your Unity project under
   `Assets/StreamingAssets/SpoutNdiNormalizer/spout_ndi_normalizer.exe`.
   (StreamingAssets is preserved verbatim into builds, so the same path works
   in Editor and in standalone Player.)

2. Drop `SpoutNdiLauncher.cs` anywhere under `Assets/`.

3. Add a GameObject (e.g. an empty "SpoutNdiLauncher" object) and attach the
   `SpoutNdiLauncher` component. Inspector fields:

   | Field            | Default                       | Notes |
   |------------------|-------------------------------|-------|
   | Exe Relative Path| `SpoutNdiNormalizer/spout_ndi_normalizer.exe` | Relative to `StreamingAssets/` |
   | Sender Name      | `Streamingle Spout Output`    | Must match Unity's KlakSpout / Spout sender exactly |
   | Target Fps       | `60`                          | Output cadence |
   | Monitor Index    | `1`                           | 0-based; -1 = start windowed |
   | Window Width/Height | `1280 / 720`               | Used only when `monitorIndex < 0` |
   | Vsync            | `true`                        | Toggleable at runtime via `V` key |
   | Skip If Already Running | `true`                 | Avoid duplicates on PlayMode reload |

4. Press Play. The exe spawns automatically and quits when Unity quits or
   crashes (uses `--parent-pid <unity-pid>` watchdog).

## Runtime hotkeys (in the normalizer window)

| Key     | Action                              |
|---------|-------------------------------------|
| F11     | Toggle borderless fullscreen        |
| F12     | Cycle target monitor                |
| V       | Toggle vsync                        |
| T       | Toggle always-on-top                |
| C       | Toggle cursor hide                  |
| P       | Dump pace_log.csv next to the exe   |
| ESC     | Exit fullscreen, or close window    |

The window title bar reports live pacing telemetry: pace fps, wake jitter
percentiles, tick interval distribution, callback duration, hold ratio,
sender format, GPU adapter, and source name.

## CLI args (advanced)

The launcher composes these for you, but the exe accepts them directly:

```
--sender <name>      Spout sender name (default: Streamingle Spout Output)
--fps <hz>           Target output cadence (default: 60)
--width <px>         Initial windowed width
--height <px>        Initial windowed height
--monitor <index>    Borderless fullscreen on this 0-based monitor index
--no-vsync           Free-run present (default: vsync on)
--topmost            Keep window above all other windows
--hide-cursor        Hide cursor while over the render area
--realtime           Aggressive scheduling (TIME_CRITICAL + Pro Audio MMCSS).
                     Default off — only enable for headless render-farm use.
                     Will starve Unity when our window is foreground.
--no-activate        Window cannot take focus on click. Recommended when
                     running alongside Unity Editor — clicks pass through and
                     Unity stays foreground. Disables our runtime hotkeys.
--parent-pid <pid>   Auto-exit if this process dies
```

## Troubleshooting

- **Title shows `NO SOURCE`**: Unity's Spout sender component hasn't started
  yet, or its sender name doesn't match. Set the same name in both places.
- **Title shows wrong GPU**: launcher chose the iGPU. Force-pick the dGPU in
  Windows Graphics Settings → Browse → spout_ndi_normalizer.exe → High performance.
- **Window doesn't appear**: launcher crashed before window creation. Run the
  exe manually from a console to see `stderr` messages.
- **Auto-exit didn't fire**: Unity's PID changed mid-session (very unusual).
  Just kill the orphan from Task Manager; next Unity Play will respawn it.

## Build provenance

This binary was produced from `spout-ndi-normalizer` source, MSVC `/MD` x64
Release, statically linked against Spout2 SDK. No external DLLs required —
the exe is self-contained on Windows 10 1803+ (high-resolution waitable
timer requirement).