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:

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.2.tgz, then add a Rey Kroona: Resi Studio Cues connection. It provides variables such as next_cue_name, next_cue_time_in_hms and playback_state for buttons.

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:

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.