# KueSync v0.12.9

**Sync Keynote / PowerPoint slides across Macs and PCs — from Bitfocus Companion, or machine-to-machine from a presenter remote (no Companion required).**
A Krometis Analytics product. © 2026 Krometis Analytics. All rights reserved.
kuesync.com · support@krometis.com

```
Agent Installer - macOS/      install on each presentation Mac
  KueSync-Agent-0.12.9.pkg
  uninstall.sh                (to remove KueSync later — run from Terminal; see "Uninstalling")
Agent Installer - Windows/    install on each presentation PC
  KueSync-Agent-Setup-0.12.9.exe
Companion Module/
  krometis-kuesync-0.12.9.tgz   import into Companion 4+ (recommended)
  krometis-kuesync/             drop-in folder for Companion 3's developer-modules path
```

Requires a Mac with an M-series chip (Apple silicon, M1 or later — KueSync is optimized for it) or Windows 10/11. All machines on the same network. Bitfocus Companion is
optional — a Leader machine with a presenter remote (or a phone clicker link) drives the fleet too.

> **What's new since the last public release (0.11.2):** **Kue Lights** — a full-screen Perfect-Cue-style cue
> light you can open on any machine (from the **menu bar / tray → Open Kue Lights**, Settings → Kue Lights
> display, or `/kuelights`): the whole screen flashes
> **green** on a forward cue and **red** on a back cue, in step with the fleet, triggered by **every** drive path
> including **Bitfocus Companion**; it has a **⛶ Full screen** button and shows a **×N count** when clicks come
> fast so you can see multiple pushes at a glance. **Smoother fleet pacing** so clicking fast never "stacks"
> advances — every machine lands on the same slide. A quick **forward-then-back always registers** (deliberate
> reversals are never dropped). **Faster cue-sheet (Showflow) follow** on followers. **KueSync Control:** the cue
> lamp is green/red and expanding Showflow no longer nudges the advancer. **Companion module:** update in place
> (no uninstall), a reliability fix, cleaner buttons, natural PREV/NEXT order, a control-password-mismatch
> warning, and a follower picker that scans your current network. Slide sync, network timing, failover and the
> control-password model are unchanged from the 0.11.2 baseline.

---

## 1. Install the Agent (on each presentation Mac)

Double-click **`Agent Installer - macOS/KueSync-Agent-0.12.9.pkg`** (Mac) or run **`Agent Installer - Windows/KueSync-Agent-Setup-0.12.9.exe`** (PC) and follow the prompts. The installer is
Developer ID–signed **and notarized by Apple**, so it opens with a normal double-click — no
security bypass needed. (The Windows installer is Authenticode-signed the same way.)
- When it finishes, the **KueSync** app (your KA logo) is in your Applications folder, and **KS**
  appears in the menu bar. Open it any time from Launchpad or Applications.
- The first time it moves a slide, macOS asks to let it control Keynote / PowerPoint — click **OK**.

Note each machine's **IP address** (System Settings → Network).

---

## 2. Add the Module to Companion (once, on the Companion Mac)

**Companion 4 or newer (recommended — one click, no developer path):**
1. Companion: **Settings → Modules → Import module package**.
2. Choose **`Companion Module/krometis-kuesync-0.12.9.tgz`**.
3. **Connections → Add connection →** search **KueSync** (or **Krometis**).

It installs like any built-in module and persists across restarts — no developer-modules folder needed.

**Companion 3 (or if you prefer the dev folder):**
1. Extract **`Companion Module/krometis-kuesync-0.12.9.tgz`** and copy the `krometis-kuesync` folder into your Companion developer-modules folder.
2. Companion: **Settings → Developer modules path** → point at that folder's parent → restart Companion.
3. **Connections → Add connection →** search **KueSync**.

Either way the module includes its dependencies — nothing to install.

---

## 3. Configure ONE connection for ALL machines

- **Machine 1–8 IP** — put each presentation Mac's IP in its own box (e.g. `192.168.1.51`).
  Find a Mac's IP in its **KS menu** (menu bar). Leave unused boxes blank. Every button drives all
  connected machines in sync.
- **Default port** — `37100`.
- **License key** — blank for the 7-day free trial (during the beta, the trial is your free access).

Status shows `connected/configured` (e.g. `3/3`).

**A Mac with two LAN connections?** The agent listens on every network at once, so just enter the IP
on the *same subnet as Companion*. The **KS menu** lists all of that Mac's addresses with their
interface names — copy the right one. To lock the agent to a single network, pick it under
**KS ▸ Set listen network** (it restarts the agent on just that interface).

---

## 4. Drive your slides

Open **Presets** and drag KueSync buttons onto a page:

- **Transport** — NEXT, PREV (+ NEXT (static) / PREV (static)), FIRST, LAST, START, STOP, +5, −5, **RESYNC ALL**
- **Deck / Roll** — GO DECK (arm), SYNC ROLL, **END SHOW**, RUN CUE (+ (static) variants), **STOP AUTO**, PAUSE, RESUME, CANCEL
- **Go to slide** — one-touch buttons for slides 1–20
- **Status** — current slide (excludes hidden slides), **machines healthy**, **FLEET** (sync indicator), **per-machine slides**, **BUILD** position, **Current Leader**, license (+ providing machine)
- **Monitor** — presenter **notes**, **slide name**, **presentation name** (live, like OSCPoint)
- **Media** (PowerPoint) — PLAY/PAUSE video, VIDEO END, VIDEO STOP, **OPEN FILE**

Every button broadcasts to all machines at once. Each agent then waits the same brief **sync
window** (set in the connection, default 120 ms) on its own clock before changing the slide, so all
screens flip together — no clock sync between Macs required.

### Deck / roll buttons

- **GO DECK** brings every machine up **full screen at slide 1 and holds** — it does not advance.
  Use it to arm the show on standby.
- **SYNC ROLL** starts the synced roll **from the current slide** (press it after GO DECK). It
  advances all machines together, in lockstep, playing every in-slide build and animation, and at the
  end relies on **Keynote's own loop** to wrap cleanly to slide 1 (see below). Rolls until you stop it.
- **END SHOW** stops the roll **and exits the slideshow** on every machine (back to the editor) — the
  clean way to take the whole fleet down at the end.
- **RUN CUE** plays through once (with builds) and stops at the end.
- **STOP AUTO** stops the roll but **holds on the current slide** (stays full screen).

> **Enable Keynote's loop for SYNC ROLL.** In the Keynote deck: **Document inspector ▸ Document tab ▸
> Presentation ▸ check "Loop slideshow."** With that on, advancing past the last build wraps to slide
> 1 using Keynote's own behavior — every animation plays, no black screen — and because KueSync sends
> the same advance to every machine at the same gated moment, they all wrap together. (If a deck's
> loop is left off, KueSync falls back to restarting it at slide 1 at the end, which briefly shows the
> transition each lap.) Set this once per deck.

### Builds & animations play by default

**NEXT / PREV and SYNC ROLL / RUN CUE all step through in-slide builds and animations**, and stay in
sync across the fleet because every machine fires the same "next" at the same gated time — one press
advances one build, exactly like pressing the arrow key on a single Mac, mirrored on all of them.

This assumes every Mac is running the **same deck** (the normal case for a mirrored show). If a
machine misses a press it can slip a step — the **FLEET** indicator shows this and **RESYNC ALL**
snaps everyone back.

**Static variants** (NEXT (static), SYNC ROLL (static), etc.) use **absolute slide numbers** instead:
they keep machines perfectly locked and self-correcting but **skip builds**. Use them on build-free
decks and video walls.

Each agent fires the move at a shared moment so screens flip together. KueSync continuously measures
every machine and corrects each cue per machine, so the fleet stays dead-on with no clock setup, on
any network — including isolated direct-wired rigs. Leave **Sync timing** on Standard; **Relative**
exists only as a compatibility fallback.

### ⏹ STOP AUTO — disengage auto-advance

The red **STOP AUTO** button instantly halts any running roll or cue (SYNC ROLL / RUN CUE, builds or
static) and **holds on the current slide** — it sends no slide command, so nothing jumps; you simply
take back manual control with NEXT/PREV. (PAUSE freezes the timer and RESUME continues; STOP AUTO
ends the auto-run entirely.)

### Health, failover & drift (the redundancy promise)

- **Healthy ≠ connected.** Each agent sends a heartbeat every ~2s. A machine counts as **healthy**
  only if it reported within the **Health timeout** (default 6s) — so a backup whose agent has wedged
  or whose link went half-open turns **red** instead of sitting there falsely green. The **Healthy
  N/total** status button and the connection status both reflect health, not just an open socket.
- **Automatic feedback failover.** All the readouts (current slide, total, playing, FLEET) follow the
  first **healthy** machine. If the main machine dies, the backups keep the readouts alive instead of
  freezing on the dead one's last value.
- **FLEET** stays green while every healthy machine is on the same slide and turns **red the instant
  one slips**. Press it to **RESYNC ALL**.
- **Per-machine slides** status button shows each machine at a glance, e.g. `5·5·4` (✕ = unhealthy) —
  so you see *which* one drifted, not just that one did. Press it to RESYNC ALL.
- **Reconnect realignment** (on by default): if a machine drops and rejoins mid-show it has missed
  advances, so KueSync snaps **just that machine** to the fleet's current slide — the others aren't
  disturbed. (It skips that machine's in-slide builds; a slide-boundary snap is the honest recovery.)
- **Auto-resync** (off by default, in the connection settings): if drift persists past the settle
  window for the configured seconds, KueSync snaps everyone to the primary's slide. It's **off by
  default because the snap skips builds** — turn it on for video walls / static decks where self-
  healing matters more than build fidelity.
- **Build step.** Because KueSync issues every advance, it tracks the build position within a slide
  (`build_step` variable = advances since the slide number changed) even though Keynote can't report
  it. That's the *intended* position; a machine that silently fell a build behind from an out-of-band
  action still can't be observed (see the caveat below) — RESYNC ALL to a slide boundary cures it.

> **Build-aware on PowerPoint; slide-level on Keynote.** On **Windows PowerPoint**, KueSync now reads
> the real build/click position (`build_index` / `build_count`) and the **FLEET** indicator is
> build-aware — it turns red when two machines sit on the *same slide* but different builds. On
> **Keynote**, the build index isn't exposed by scripting, so FLEET stays slide-level there; snap to a
> slide boundary (RESYNC ALL or a Go-to-slide button) to realign build state.

### Timing (on the button)

Open a **SYNC ROLL / RUN CUE** button's action:

- **Default slide timing (seconds)** — the interval between build/animation steps.
- **Override default timing per slide** — e.g. `7=120, 12=30`. **This now works *with* builds:** the
  hold is keyed to the slide the fleet is showing, so slide 7 can hold 120 s (e.g. an embedded video)
  while every other slide keeps advancing and playing its builds at the default interval. (On a slide
  that *also* has click-builds, the custom time applies to each step on that slide — most timed slides
  like a video are build-free, so this is usually just "hold this slide for N seconds.")
- **Start from slide 1**, **Loop deck**.

---

## 5. Licensing

Each connection runs free for **30 days**, then needs a license key (entered in the connection
settings, verified offline). The license button shows amber during trial, red on expiry. An
in-progress show is never cut off mid-cue. The trial start is stored so re-adding the connection
won't restart it, and rolling the clock back won't extend it. (It's deterrence, not DRM — it isn't
tamper-proof.)

---

## 6. Leader / Follower & redundancy (new in v6)

By default every Mac is a **Follower** — driven by Companion, exactly as before. v6 adds an optional
**Leader** mode so you can drive the whole synced fleet from one presentation Mac with a standard
**presenter remote** (PerfectCue, Logitech, Kensington…), with no Companion required. Companion keeps
working at the same time.

**Make a Mac a Leader**

1. On that Mac, open **KS menu (menu bar) › Leader / Follower Setup…** — this opens the local setup page.
2. Switch **Mode** to **Leader**, give it a **priority** (the main machine highest), then **Scan** your
   subnet and tick the **Followers** it should drive (or add IPs manually). Save.
3. The first time you enable Leader mode, KueSync guides you to allow it under **System Settings ›
   Privacy & Security › Input Monitoring** and **Accessibility** (one click each) — so it captures the
   remote and is show-ready immediately. Followers need none of this.
4. Use the **presenter remote** — KueSync captures the click and advances every machine (and itself) in
   perfect sync, builds and all. Default keys are Page Up/Down + arrows; use **Learn** to bind any remote.

**Redundant Leaders (automatic failover)**

Add one or more backup Leaders under **Redundant Leaders** (by IP). KueSync continuously elects the best
healthy Leader. If the active Leader freezes or drops, the strongest backup **promotes itself instantly**
and your next click drives the fleet — no console to touch. When the primary recovers it rejoins as a
silent standby and only reclaims control once it's **confirmed stable** (healthy for a settling window,
caught up to the current slide, and its remote is proven live) — a seamless, click-synchronized handover.
Followers are the source of truth, so two Leaders can never both drive the same machine (no split-brain).

**In Companion:** the new **Current Leader** status button shows who's driving, by machine number **and**
IP. Drag it on alongside the other status buttons.

---

## Security note

An agent with Automation permission can drive Keynote/PowerPoint on its Mac, so **on a shared or
untrusted network you should set a control password**: put `KUESYNC_TOKEN=yourpassword` in
`/usr/local/kuesync-agent/config.env` on each agent (then reload it), and enter the same token in
the Companion connection's **Control password** field. The password is sent as a header, not in the URL.
Without a token, anyone on the LAN can advance slides on these Macs.

---

## Uninstalling the Agent

Open **Terminal** (Applications ▸ Utilities ▸ Terminal), then drag `Agent Installer/uninstall.sh` into the window after typing `sudo bash ` (note the trailing space), and press Return. You'll be asked for your Mac password. For example:

```
sudo bash "/path/to/Agent Installer/uninstall.sh"
```

This stops and removes the KueSync agent, menu app, and helpers. (We run it from Terminal rather than a double-click because macOS blocks downloaded double-click scripts for security.)

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Module not in Add Connection list | Confirm the `krometis-kuesync` folder (with `node_modules`) is in the dev path; restart Companion. |
| Connection shows 0/N | Check each machine's IP/port; confirm KS shows "Running"; same network. |
| Buttons do nothing | Grant Automation permission on that Mac (Step 1). |
| Slide stuck at 0 | Open a document and start the show on that Mac. |
