Nextcue/README.md

# Resi → ProPresenter countdown

Shows a countdown to the next Resi cue on ProPresenter's stage display, and optionally
the cue's name as a stage message. ProPresenter does the counting, so it's smooth; a small
background service on a Mac keeps it pointed at the right cue.

```
Resi (cloud) ──► always-on Mac (this service) ──► ProPresenter (timer, optional stage message)
```

It talks to Resi directly. Companion isn't needed for the countdown; the Companion
module in this kit is optional, for buttons and Stream Deck displays.

## What you need

- **An always-on Mac** on the same network as ProPresenter, ideally one that logs in
  automatically (an ingest or utility Mac). It can be the ProPresenter Mac itself.
- **A Resi login** that can see the campus's decoder.
- **ProPresenter 7.9 or newer.**

## 1. Set up ProPresenter (once per site)

1. **Settings → Network**: turn on **Enable Network**. Note the IP address and port.
2. **Timers**: add a **Countdown** timer named **`NextCue`** (any length; it gets overwritten).
3. **Stage layout**: in the layout your stage screen uses, add a **Timer** object set to
   **NextCue**. Add a **Stage Message** object only if you'll turn cue-name messages on.

## 2. Install the service (on the always-on Mac)

Copy this folder onto that Mac, open **Terminal**, and run:

```bash
zsh ~/Desktop/resi-propresenter-kit/install_bridge.sh
```

(adjust the path to wherever you put the folder). It asks for:

1. **Resi login email and password.** The password goes in that Mac's Keychain, not a file.
2. **Which decoder** feeds this campus, picked from a numbered list.
3. **ProPresenter's address**, e.g. `192.168.1.50:1025`. It checks it can reach it.
4. **Which timer** to drive (`NextCue`). It checks the timer exists.
5. **Whether to show cue names as a stage message.** Default is **no**: just the countdown.
   If yes, the name is sent once per cue (never repeated), so it won't keep flashing.

Then it starts the service and shows the first lines of its log. You should see
`NextCue -> <cue name> in 00:12:34`. From then on it starts at login, restarts itself if
it stops, and follows whatever event the decoder is playing. Nobody has to do anything on
service day.

If the installer warns that the Mac doesn't log in automatically, turn on **System
Settings → Users & Groups → Automatically log in as …** (FileVault must be off).
Otherwise the countdown won't come back after a reboot until someone logs in.

Run only **one copy per ProPresenter**: two copies fight over the same timer.

## 3. Optional: Companion module

In Companion: **Modules → Import module package** → `resi-studio-cues-0.1.5.tgz`, then add a
**Rey Kroona: Resi Studio Cues** connection: the Resi login, **Player position poll** 3000 ms,
and (once it has connected) the **Default decoder/player**. It provides variables such as
`next_cue_name`, `next_cue_time_in_hms` and `playback_state` for buttons.

**A button with the next cue's name and its countdown:** give the button two text
elements, split by a line if you like:

| Element | Text | Position |
|---|---|---|
| Cue name | `$(resi-studio-cues:next_cue_name)` | top-aligned, height 46%, **Shrink to fit** on |
| Countdown | `$(resi-studio-cues:next_cue_time_in_hms)` | bottom-aligned, full height |

Keeping the name to the top half lets a long cue name ("Message OUT (end of prayer; MC
comes out)") shrink to fit instead of running over the countdown.

## 4. Optional: the cue name in ProdDash

ProdDash's **Resi Cues** module (in the ProdDash repo) feeds the **Timers** tile a countdown
titled with the next cue's name. Show that card, not ProPresenter's `NextCue` timer, which
only ever says "NextCue". In a single-timer Timers tile, choose **Resi › Next cue** when
adding it (stored as `solo:resi-cues:next-cue`). In an "all timers" tile it's already listed.

Each screen keeps its own copy of its layout. After a named layout changes, reload it on
each screen: **Layouts** (the grid icon, left of the gear) → the layout's name.

## Day to day

| To… | Run (on that Mac) |
|---|---|
| Watch what it's doing | `tail -f ~/Library/Logs/resi-propresenter.log` |
| Change decoder / ProPresenter / password / stage message on-off | `zsh install_bridge.sh --setup` |
| Update to a newer script | run `zsh install_bridge.sh` from the new kit (keeps settings) |
| Remove it | `zsh install_bridge.sh --uninstall` |

## If something's wrong

- **`Resi rejected the login`**: the password changed. Run `--setup` again.
- **`Cannot reach ProPresenter`**: ProPresenter is closed, its IP changed, or Network is
  off. Run `--setup` to enter the new address.
- **`playback stopped — timer held`**: the decoder isn't moving, or Resi isn't reporting.
  It picks back up by itself when playback resumes.
- **Stage shows the cue name but no countdown**: the stage layout's timer object isn't set
  to `NextCue`.
- **Over SSH**: the installer asks for that Mac's login password first, to unlock its
  Keychain. Remote sessions keep it locked.

Resi's API is undocumented and unsupported, so don't open a Resi ticket about this tool.

## Working on it

| Path | What it is |
|---|---|
| `resi_to_propresenter.py` | The bridge. Python 3, standard library only. |
| `install_bridge.sh` | Installs it as a login service on the Mac it runs on, and runs `--setup` when needed. |
| `make_kit.sh` | Builds `resi-propresenter-kit.zip` for another site (no site settings inside). |
| `source/` | The Companion module `resi-studio-cues` (`dist/` is what ships, plus `manifest.json` and `HELP.md`). |
| `resi-studio-cues-0.1.5.tgz` | The current Companion package: import it in Companion → Modules. |

Tests. All run offline against fakes, except the end-to-end one:

```bash
python3 test_playhead.py        # the playhead estimator, nine Resi profiles plus slow-start cases
python3 test_stage_message.py   # stage message sent once per cue, never when switched off
python3 test_rate_limit.py      # backs off when Resi says "too many requests"
node source/backoff_test.js     # Companion module: login hold-off, no crash loop on a locked account
node source/config_test.js      # Companion module: settings always save, upgrade fills defaults, quieter cue refresh
```

`source/tick_test.js` is the Companion module's estimator test (run with JavaScriptCore's
`jsc`, with `var TARGET='dist/main.js'` loaded first). `test_end_to_end.py` drives a **real**
ProPresenter's `NextCue` timer and stage message, so it refuses to run without
`<address> --touch-live-propresenter`. Stop the installed bridge before using it.

The Companion package is `source/dist`, `source/manifest.json` and `source/HELP.md` (under
`companion/`), plus a vendored `node_modules` with `@companion-module/base` 1.14.1
(`source/npm_vendor.py` assembles one). Bump the version in `manifest.json` and the
package's `package.json` on every change.

**Running at North Attleboro:** the bridge, Companion and ProdDash all run on the NA Ingest
Mac, and all three use the `media@waters.church` Resi login. Keep them polling no faster than
every 3 seconds: Resi rate-limits the account when tools share it.

- ProPresenter (NA-ProP): `NextCue` timer on the stage screen's layout; stage messages off.
- Companion: page **5 Booth**, row 1, column 4 shows the next cue's name over its countdown.
- ProdDash: the NextCue tiles in the **BOH TV**, **Studio A Ingest** and **Studio B** layouts
  show Resi's countdown titled with the cue's name; FOH Booth and Mobile list all timers.