modules/propresenter-looks/README.md

@@ -0,0 +1,55 @@
+# ProPresenter Look — a ProdDash module
+
+Shows the audience **look** live in ProPresenter right now, as big as the
+tile allows, so anyone away from the ProPresenter machine can tell at a glance
+which look the outputs are on.
+
+- The look's name fills the tile and **flashes** when it changes.
+- **Modified** appears when someone changed the look by hand and it no longer
+  matches any saved look.
+- **since 10:42 AM** says when the look last changed.
+- If ProPresenter stops answering, the status dot goes red and the tile keeps
+  the **last known** look on screen, dimmed, until it comes back by itself.
+
+## Install
+
+This folder is a standard ProdDash module (id `propresenter-looks`). Per the
+ProdDash module guide, it installs one of two ways:
+
+1. **From the admin page's catalog**, once the folder is in the ProdDash repo
+   at `modules/propresenter-looks/`: `/admin` → Available modules →
+   *ProPresenter Look* → Install.
+2. **Drop it in**: copy this folder to the ProdDash data directory's
+   `modules/propresenter-looks/` and restart ProdDash.
+   - macOS: `~/Library/Application Support/ProdDash/modules/`
+   - Windows: `%APPDATA%\ProdDash\modules\`
+
+Then add a tile from **＋ Add tile → ProPresenter Look**.
+
+## Configure (in `/admin`)
+
+| Setting | What to enter |
+| --- | --- |
+| ProPresenter | Host / IP and port from ProPresenter's Settings › Network (Network enabled). |
+| Password | Only if ProPresenter's network API asks for one. |
+
+Each tile's gear has three switches: **Heading**, **Live status**, **Since**.
+
+## How it works
+
+The server entry polls ProPresenter's network API once a second
+(`GET /v1/look/current`, plus `GET /v1/looks` every ten seconds to name the
+saved look it matches) and streams the result to tiles over SSE. Browsers
+never talk to ProPresenter. No dependencies. Needs ProdDash 1.5.0 or later and
+ProPresenter 7.9+ (or 20+).
+
+## Testing without ProPresenter
+
+```bash
+node tools/pp-looks-mock.js 1601
+```
+
+Point the module at host `127.0.0.1`, port `1601`. The live look changes every
+8 seconds (`--every 3` for faster) and every fourth change is a hand-modified
+look. `--password <pw>` demands a password; `--no-list` acts like a
+ProPresenter without `GET /v1/looks`.