Merge pull request 'SPL Meter 0.4.2: the device picker can build the tool it needs' (#18) from claude/spl-devices-without-binary into main

Time left on the video ProPresenter is playing — the one number a booth
needs during a bumper or sermon video — was missing: the module only read
the configured timers, and the video countdown lives in the transport
routes. Verified live on ProPresenter 21.4:
  GET /v1/transport/presentation/current → { is_playing, uuid, name,
    artist, audio_only, duration }
  GET /v1/transport/presentation/time    → bare seconds as a sub-second
    float — better than /v1/timer/video_countdown's whole-second string,
    so no quantization phase lock is needed, only an anchor hold (a frame
    is broadcast only when the anchor drifts, not per poll).

The Video card rides the ProPresenter source: transport current on the
slow lane, position on the hot path (skipped while no media is loaded),
running/paused/idle from is_playing and position, the media name (minus
its file extension) as the detail line. It persists as an idle '—'
between videos — a wall tile must not appear and vanish with the media —
and is absent only on a ProPresenter whose transport routes 404.

No looping flag exists anywhere in the API, so looping is inferred: the
same media's position jumping backwards is a wrap, and the flag sticks
until the media changes. Each tile gets a 'Looping videos' switch
(default off): off, a looping background's meaningless time is hidden —
the card sits out of a multi-card tile, and a solo Video tile shows a
quiet 'Looping' card instead of sitting empty. Shown loops never take
the warn/overrun tones: a 15 s background flashing red every wrap would
cry wolf all service.

The picker offers 'Video' as its own tile (solo gear carries the loop
switch); pp-timers-mock gains the transport routes with a 4-minute cycle
(bumper playing → paused → resumed → nothing → looping background).
Verified in the browser across the whole cycle, both tile kinds, and the
per-tile toggle. Selftests pass.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

README.md

@@ -303,9 +303,11 @@ below. Nothing is installed without someone clicking.
   status, NOW and NEXT labels, slide count, progress bar, the next list and
   its item tags, plus tidy titles.
 - **Timers** — live ProPresenter timers (countdown, countdown-to-time,
-  elapsed) and LTC timecode as auto-sized cards. The ＋ picker lists every
-  discovered timer (and the LTC card) as its own tile, or add "All timers"
-  and pick a selection via the tile's "Timers ▾" menu; overruns are
+  elapsed), the **video countdown** (time left on what ProPresenter is
+  playing, with a per-tile "Looping videos" switch so looping backgrounds
+  stay hidden) and LTC timecode as auto-sized cards. The ＋ picker lists
+  every discovered timer (and the LTC card) as its own tile, or add "All
+  timers" and pick a selection via the tile's "Timers ▾" menu; overruns are
   unmistakably red. Read-only — no start/stop controls. Admin config is in
   three groups: **ProPresenter** (endpoint host : port, API password),
   **LTC Timecode** (the listener switch, and — when it's on — the audio

modules/propresenter-timers/client.js

@@ -70,6 +70,7 @@ const DEFAULTS = {
   showDetail: true,
   showSeconds: true,
   leadingZeros: false,
+  showLoops: false,
   clock24h: true,
   clockSeconds: true,
   clockDate: false,
@@ -384,7 +385,12 @@ export default function create({ root, moduleApi }) {
       for (const source of state.sources) {
         for (const timer of source.timers) {
           if (keyOf(source, timer) !== solo) continue;
-          return [{ id: source.id, source, items: [{ key: solo, source, timer }] }];
+          // A solo video tile with looping media hidden must not sit empty:
+          // it shows a quiet card instead of a countdown nobody should read.
+          const shown = timer.looping && pref('showLoops') !== true
+            ? { ...timer, state: 'idle', remainingMs: null, elapsedMs: null, startedAt: null, asOf: null, status: { text: 'Looping', tone: 'muted' } }
+            : timer;
+          return [{ id: source.id, source, items: [{ key: solo, source, timer: shown }] }];
         }
       }
       // The timer this tile was added for is not offered right now. Nothing is
@@ -398,7 +404,11 @@ export default function create({ root, moduleApi }) {
       const items = [];
       for (const timer of source.timers) {
         const key = keyOf(source, timer);
-        if (!hidden.has(key)) items.push({ key, source, timer });
+        if (hidden.has(key)) continue;
+        // A looping background's time means nothing — the card sits out
+        // while a loop plays (per tile: the "Looping videos" switch).
+        if (timer.looping && pref('showLoops') !== true) continue;
+        items.push({ key, source, timer });
       }
       // Every timer of a live source hidden on purpose: nothing to say.
       if (!items.length && source.timers.length) continue;
@@ -666,7 +676,9 @@ export default function create({ root, moduleApi }) {
           card.mono = null;
         }
         text = value === null ? '—' : fmtDuration(value, { ...digits, up: timer.kind === 'countdown' });
-        tone = toneFor(timer, value);
+        // A shown loop never warns or overruns — it wraps at zero by design,
+        // and a background flashing red every pass would cry wolf all service.
+        tone = timer.looping ? (timer.state === 'running' ? 'ok' : 'muted') : toneFor(timer, value);
         statusText = timer.status?.text || defaultStatus(timer, value, tone);
         statusTone = timer.status?.tone || tone;
         detailText = timer.detail || '';

modules/propresenter-timers/ltc-listener.js

@@ -10,13 +10,23 @@
  * onUpdate roughly 4×/s:
  *
  *   { state: 'running'|'stopped'|'nosignal', time, fps, df }   healthy
- *   { error: '<what is wrong and how to fix it>' }             not capturing
+ *   { error: '<short, for the tiles>', detail: '<for admin/log>' }  not capturing
  *
- * The capture binary is per-machine (gitignored): if it is missing this
- * tries one swiftc compile of the source next to it, and otherwise says to
- * build it on any same-architecture Mac and copy it over. A dead child is
- * restarted with backoff — fast for a crash, slow for config-shaped
- * failures (unknown device, ambiguous name) that never fix themselves.
+ * Error strings are two-tier on purpose: `error` is what a dashboard tile
+ * shows (short — "Not configured — see Admin"), `detail` is the full story
+ * for the admin health line and the log.
+ *
+ * The capture binary is per-machine (gitignored), and a catalog install or
+ * update ships source only — the update even wipes a previously built
+ * binary. ensureCaptureBinary() therefore rebuilds it with swiftc in the
+ * background as part of coming up: kicked when the LTC source starts and by
+ * the admin device picker, never on the event loop (a blocking build once
+ * froze the whole server — see spl-meter's history), built to a temp name
+ * and renamed so a killed build can't leave a half-written "binary", and
+ * rebuilt when a module update leaves the source newer than the binary.
+ * A dead capture child is restarted with backoff — fast for a crash, slow
+ * for config-shaped failures (unknown device, ambiguity) that never fix
+ * themselves.
  *
  * macOS gotcha this file can't fix: microphone permission. A ProdDash
  * server launched over SSH or from a bare launchd job gets SILENT ZEROS
@@ -27,7 +37,7 @@
 
 const path = require('path');
 const fs = require('fs');
-const { spawn, spawnSync } = require('child_process');
+const { spawn } = require('child_process');
 const { LtcDecoder, ChannelExtractor, fmtTc } = require('./ltc');
 
 const RESTART_MS = 5000;
@@ -41,6 +51,100 @@ const RUNNING_WINDOW_MS = 400;
 /** stderr line the capture prints once the device is open. */
 const CAPTURING_RE = /capturing "(.+)": (\d+) channels @ (\d+) Hz/;
 
+/* ── the capture tool: build it when the install didn't bring one ──────── */
+
+/** Tile-facing words (short); the detail goes to admin health and the log. */
+const TOOL_BUILDING = 'Capture tool building…';
+const TOOL_MISSING = 'Capture tool unavailable — see Admin';
+const BUILD_HELP = 'LTC capture tool could not be built here — build it on any Mac of the '
+  + 'same architecture with `swiftc -O -o ltc-capture ltc-capture.swift` (both files are in '
+  + 'the module folder) and copy the binary next to ltc-capture.swift';
+
+let building = false;
+let buildFailed = false;
+
+/**
+ * Make sure the capture tool exists, building it in the background when it
+ * does not — module scope, so the LTC source can kick it the moment it
+ * starts and the admin device picker can kick it before any device is
+ * configured (a listener-only build would deadlock: no tool → no device
+ * list → no device → no listener). A catalog install ships source only and
+ * a catalog update deletes the module folder (old binary included), so this
+ * IS the install step for the tool.
+ *
+ * Never blocks (a synchronous build once held the whole server's event loop
+ * — every module — for the duration). Builds to a temp name and renames, so
+ * a killed or crashed build can't leave a truncated file that looks like a
+ * ready binary. A binary older than the source (a module update over an
+ * existing folder) keeps serving while a replacement builds behind it.
+ *
+ * @returns {{ready:boolean, error:string, detail:string}} `ready` = a binary
+ *   is usable right now; otherwise `error` is the short tile text and
+ *   `detail` the full one.
+ */
+function ensureCaptureBinary({ moduleDir, log, onReady }) {
+  const bin = path.join(moduleDir, 'ltc-capture');
+  const src = bin + '.swift';
+  const ok = { ready: true, error: '', detail: '' };
+  let haveBin = false;
+  let stale = false;
+  try {
+    haveBin = fs.existsSync(bin);
+    if (haveBin && fs.existsSync(src)) stale = fs.statSync(src).mtimeMs > fs.statSync(bin).mtimeMs;
+  } catch { /* treat as missing */ }
+  if (haveBin && !stale) return ok;
+  if (!fs.existsSync(src)) {
+    return haveBin ? ok : { ready: false, error: TOOL_MISSING, detail: 'ltc-capture.swift is missing from the module folder' };
+  }
+  const notYet = haveBin ? ok : {
+    ready: false,
+    error: building || !buildFailed ? TOOL_BUILDING : TOOL_MISSING,
+    detail: building || !buildFailed ? 'Building the LTC capture tool — ready in a moment' : BUILD_HELP,
+  };
+  if (building || buildFailed) return notYet;
+
+  building = true;
+  const tmp = bin + '.building';
+  log(stale ? 'ltc-capture is older than its source — rebuilding it in the background'
+    : 'ltc-capture binary missing — building it in the background');
+  const build = spawn('swiftc', ['-O', '-o', tmp, src], { stdio: ['ignore', 'ignore', 'pipe'] });
+  let buildErr = '';
+  build.stderr.setEncoding('utf8');
+  build.stderr.on('data', (t) => { buildErr = (buildErr + t).slice(-800); });
+  const giveUp = setTimeout(() => {
+    try { build.kill('SIGKILL'); } catch { /* already gone */ }
+  }, 300000);
+  giveUp.unref?.();
+  build.on('error', (err) => {
+    clearTimeout(giveUp);
+    building = false;
+    buildFailed = true;
+    try { fs.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
+    log(`swiftc could not be run: ${err.message}`);
+  });
+  build.on('exit', (code) => {
+    clearTimeout(giveUp);
+    building = false;
+    if (code === 0 && fs.existsSync(tmp)) {
+      try {
+        fs.renameSync(tmp, bin);
+      } catch (err) {
+        buildFailed = true;
+        log(`ltc-capture built but could not be moved into place: ${err.message}`);
+        return;
+      }
+      buildFailed = false;
+      log('ltc-capture built');
+      if (typeof onReady === 'function') onReady();
+      return;
+    }
+    buildFailed = true;
+    try { fs.rmSync(tmp, { force: true }); } catch { /* nothing to clean */ }
+    log(`ltc-capture build failed (exit ${code})` + (buildErr ? `: ${buildErr.trim().split('\n').pop()}` : ''));
+  });
+  return notYet;
+}
+
 /**
  * @param {{device:string, channel:number, moduleDir:string, log:Function,
  *          onUpdate:(u:object)=>void}} opts
@@ -75,25 +179,24 @@ function createLtcListener({ device, channel, moduleDir, log, onUpdate }) {
     return 'nosignal';
   }
 
-  function ensureBinary() {
-    if (fs.existsSync(bin)) return '';
-    const src = bin + '.swift';
-    log('ltc-capture binary missing — trying a one-time swiftc build');
-    const built = spawnSync('swiftc', ['-O', '-o', bin, src], { timeout: 120000 });
-    if (built.status === 0 && fs.existsSync(bin)) {
-      log('ltc-capture compiled');
-      return '';
-    }
-    return 'LTC capture tool missing — build it on any Apple Silicon Mac with '
-      + '`swiftc -O -o modules/propresenter-timers/ltc-capture modules/propresenter-timers/ltc-capture.swift` '
-      + 'and copy it here';
-  }
-
   function start() {
     if (stopped) return;
-    const missing = ensureBinary();
-    if (missing) {
-      report({ error: missing });
+    const tool = ensureCaptureBinary({
+      moduleDir,
+      log,
+      onReady() {
+        // The build this start() was waiting on landed — go now.
+        if (!stopped) { clearTimeout(restartTimer); restartTimer = null; start(); }
+      },
+    });
+    if (!tool.ready) {
+      report({ error: tool.error, detail: tool.detail });
+      // onReady is only the FAST path (a successful build restarts us at
+      // once). The slow retry must stay armed regardless: a failed build
+      // never calls back, and a binary can also arrive from outside — scp'd
+      // in on a machine whose toolchain can't build (AB's broken CLT).
+      // Waiting on onReady alone deadlocked exactly that way in production:
+      // "Capture tool building…" forever, with a working binary on disk.
       scheduleRestart(BAD_CONFIG_RETRY_MS);
       return;
     }
@@ -113,7 +216,10 @@ function createLtcListener({ device, channel, moduleDir, log, onUpdate }) {
       const channels = Number(m[2]);
       const rate = Number(m[3]);
       if (channel > channels) {
-        report({ error: `"${m[1]}" has ${channels} input channels — channel ${channel} is configured. Fix it in Admin.` });
+        report({
+          error: 'Channel not on this device — see Admin',
+          detail: `"${m[1]}" has ${channels} input channels — channel ${channel} is configured. Fix it in Admin.`,
+        });
         try { child.kill(); } catch { /* exiting anyway */ }
         return;
       }
@@ -135,17 +241,21 @@ function createLtcListener({ device, channel, moduleDir, log, onUpdate }) {
     });
 
     child.on('error', (err) => {
-      report({ error: `LTC capture failed to start: ${err.message}` });
+      report({ error: TOOL_MISSING, detail: `LTC capture failed to start: ${err.message}` });
     });
 
     child.on('exit', (code) => {
       child = null;
       if (stopped) return;
       // The capture's own failure text (unknown device, ambiguous name,
-      // permission hint) is the most useful thing we can show.
+      // permission hint) is the most useful DETAIL we have; the tile just
+      // needs to know the input is down and where to fix it.
       const said = stderrTail.split('\n').reverse().find((l) => l.includes('ltc-capture:') && !CAPTURING_RE.test(l));
       const quickDeath = Date.now() - startedAt < 3000;
-      report({ error: (said ? said.replace(/^.*ltc-capture:\s*/, '') : `LTC capture exited (code ${code})`) + (quickDeath ? '' : ' — restarting') });
+      report({
+        error: quickDeath ? 'Audio device unavailable — see Admin' : 'Audio capture restarting…',
+        detail: (said ? said.replace(/^.*ltc-capture:\s*/, '') : `LTC capture exited (code ${code})`) + (quickDeath ? '' : ' — restarting'),
+      });
       scheduleRestart(quickDeath ? BAD_CONFIG_RETRY_MS : RESTART_MS);
     });
   }
@@ -188,4 +298,4 @@ function createLtcListener({ device, channel, moduleDir, log, onUpdate }) {
   };
 }
 
-module.exports = { createLtcListener };
+module.exports = { createLtcListener, ensureCaptureBinary };

modules/propresenter-timers/module.json

@@ -1,7 +1,7 @@
 {
   "id": "propresenter-timers",
   "name": "Timers",
-  "version": "1.4.2",
+  "version": "1.6.0",
   "proddash": ">=1.4.0",
   "description": "Timers, Clocks, and LTC From configured Modules",
   "provides": [
@@ -161,6 +161,12 @@
       "default": false,
       "group": "Show"
     },
+    "showLoops": {
+      "type": "switch",
+      "label": "Looping videos",
+      "default": false,
+      "group": "Show"
+    },
     "showHeadings": {
       "type": "switch",
       "label": "Source headings",

modules/propresenter-timers/server.js

@@ -81,7 +81,7 @@
 const http = require('http');
 const path = require('path');
 const { spawn } = require('child_process');
-const { createLtcListener } = require('./ltc-listener');
+const { createLtcListener, ensureCaptureBinary } = require('./ltc-listener');
 const { createTimerPhase } = require('./phase');
 const manifest = require('./module.json');
 
@@ -255,6 +255,21 @@ function createProPresenterSource({ config, log }) {
   /** uuid → phase tracker: whole-second reports → one stable anchor (see phase.js). */
   const phases = new Map();
 
+  /* The video countdown — time left on what the presentation layer is
+     playing, from the transport routes (verified live on ProPresenter 21.4):
+       GET /v1/transport/presentation/current → { is_playing, uuid, name,
+         artist, audio_only, duration }   (no looping flag exists — inferred)
+       GET /v1/transport/presentation/time    → bare seconds, sub-second
+         float — better than /v1/timer/video_countdown's whole-second string,
+         so no quantization phase lock is needed, only an anchor hold. */
+  let media = null;      // { uuid, name, duration, playing } from the slow lane
+  let mediaAt = 0;
+  let transportOk = null; // null until the first answer; false = no transport route (older ProPresenter)
+  let videoPos = null;   // playback position in seconds (float)
+  let videoAsOf = 0;     // server ms when videoPos was measured
+  let videoAnchor = null; // published { remainingMs, asOf }, held while it predicts the measurements
+  let loopingUuid = '';  // media seen wrapping — a looping background
+
   function url(target) {
     const built = new URL(`http://${host}:${port}${target}`);
     if (password) built.searchParams.set('password', password);
@@ -390,13 +405,137 @@ function createProPresenterSource({ config, log }) {
     return out;
   }
 
+  /**
+   * Follow the presentation transport layer. Failures here only drop the
+   * video card, never the whole source — the timers must survive a
+   * ProPresenter build with transport quirks.
+   */
+  async function pollVideo() {
+    if (tick % SLOW_EVERY === 1) {
+      try {
+        const raw = await requestJson('/v1/transport/presentation/current');
+        const uuid = String(raw?.uuid || '');
+        if (!media || media.uuid !== uuid) {
+          if (media && media.uuid !== uuid) loopingUuid = '';
+          videoPos = null;
+          videoAnchor = null;
+        }
+        media = uuid ? {
+          uuid,
+          name: String(raw.name || ''),
+          duration: Number(raw.duration) > 0 ? Number(raw.duration) : 0,
+          playing: Boolean(raw.is_playing),
+        } : null;
+        mediaAt = Date.now();
+        transportOk = true;
+      } catch (err) {
+        media = null; // the slow lane retries in ~2 s
+        if (err && err.status === 404) transportOk = false; // no transport route on this build
+      }
+    }
+    if (!media) {
+      videoPos = null;
+      videoAnchor = null;
+      return;
+    }
+    try {
+      const pos = Number(await requestJson('/v1/transport/presentation/time'));
+      if (Number.isFinite(pos) && pos >= 0) {
+        // Same media, position jumped back by more than a stutter: it
+        // wrapped — a looping background. Sticks until the media changes.
+        // (A video manually re-triggered from the start looks the same and
+        // is mislabeled for that pass; loops re-wrap, replays don't recur.)
+        if (videoPos !== null && media.playing && videoPos - pos > 1.5) loopingUuid = media.uuid;
+        videoPos = pos;
+        videoAsOf = Date.now();
+      } else {
+        videoPos = null;
+      }
+    } catch {
+      videoPos = null;
+    }
+  }
+
+  /** The video countdown as one synthetic timer card (id 'video'). The card
+      persists as an idle "—" between videos — a wall tile must not appear
+      and vanish with the media — and is only absent entirely on a
+      ProPresenter without transport routes. */
+  function videoTimer() {
+    if (transportOk !== true) return null;
+    if (!media) {
+      return {
+        id: 'video',
+        label: 'Video',
+        kind: 'countdown',
+        state: 'idle',
+        asOf: mediaAt || updatedAt,
+        startedAt: null,
+        elapsedMs: null,
+        remainingMs: null,
+        targetMs: null,
+        looping: false,
+        status: null,
+        detail: '',
+      };
+    }
+    const playing = media.playing;
+    const dur = media.duration > 0 ? media.duration * 1000 : null;
+    let remainingMs = null;
+    let asOf = videoAsOf || mediaAt;
+    if (videoPos !== null && dur !== null) {
+      remainingMs = Math.max(0, dur - videoPos * 1000);
+      if (playing) {
+        // Hold the published anchor while it still predicts the measured
+        // position: the tiles extrapolate locally, and a fresh anchor per
+        // poll would broadcast a frame every 500 ms for nothing.
+        const p = videoAnchor;
+        const predicted = p ? p.remainingMs - (videoAsOf - p.asOf) : NaN;
+        if (p && Math.abs(predicted - remainingMs) < 120) {
+          remainingMs = p.remainingMs;
+          asOf = p.asOf;
+        } else {
+          videoAnchor = { remainingMs, asOf };
+        }
+      } else {
+        videoAnchor = null;
+      }
+    } else {
+      videoAnchor = null;
+    }
+    const looping = media.uuid === loopingUuid;
+    return {
+      id: 'video',
+      label: 'Video',
+      kind: 'countdown',
+      state: playing ? 'running' : videoPos > 0 ? 'paused' : 'idle',
+      asOf,
+      startedAt: null,
+      elapsedMs: remainingMs !== null && dur !== null ? dur - remainingMs : null,
+      remainingMs,
+      targetMs: dur,
+      looping,
+      status: looping ? { text: playing ? 'Looping' : 'Paused', tone: 'muted' } : null,
+      // The media name, without the file extension nobody reads on a wall.
+      detail: media.name.replace(/\.(mp4|mov|m4v|mxf|avi|mkv|mp3|wav|aiff?)$/i, ''),
+    };
+  }
+
   function status() {
     if (!configured) return 'error';
     if (reachable) return 'ok';
     return lastError ? 'error' : 'connecting';
   }
 
-  function message() {
+  /** Short, for the tiles — a dashboard warns, the admin page explains.
+      The client prefixes the source label, so no "ProPresenter" here. */
+  function tileMessage() {
+    if (!configured) return 'Not configured — see Admin';
+    if (reachable) return `${timers.length} timer${timers.length === 1 ? '' : 's'}`;
+    return 'Unreachable';
+  }
+
+  /** The full story, for the admin health line. */
+  function adminMessage() {
     if (!configured) return 'No ProPresenter host configured — set one in Admin, or switch ProPresenter timers off';
     if (reachable) return `Polling ${host}:${port}, ${timers.length} timer${timers.length === 1 ? '' : 's'}`;
     return lastError ? `Unreachable at ${host}:${port} — ${lastError}` : `Reaching ${host}:${port}…`;
@@ -404,7 +543,7 @@ function createProPresenterSource({ config, log }) {
 
   function publish() {
     if (stopped) return;
-    emit({ status: status(), message: message(), timers, updatedAt });
+    emit({ status: status(), message: tileMessage(), timers, updatedAt });
   }
 
   async function pollTick() {
@@ -420,6 +559,9 @@ function createProPresenterSource({ config, log }) {
       const currentTimes = await requestJson('/v1/timers/current');
       updatedAt = Date.now();
       timers = mergeTimers(currentTimes, updatedAt);
+      await pollVideo();
+      const video = videoTimer();
+      if (video) timers.push(video);
       reachable = true;
       lastError = '';
     } catch (err) {
@@ -450,7 +592,7 @@ function createProPresenterSource({ config, log }) {
       clearTimeout(pollTimer);
     },
     health() {
-      return { status: status(), message: message() };
+      return { status: status(), message: adminMessage() };
     },
   };
 }
@@ -464,7 +606,9 @@ function createLtcSource({ config, log, moduleDir }) {
   let emit = () => {};
   let listener = null;
   let stopped = false;
-  /** The listener's latest word: { state, time, fps, df, ageMs } | { error } | null while starting. */
+  /** The listener's latest word: { state, time, fps, df, ageMs } |
+      { error, detail } (error = short tile text, detail = the admin/log
+      story) | null while starting. */
   let word = null;
 
   function rateText() {
@@ -516,8 +660,16 @@ function createLtcSource({ config, log, moduleDir }) {
     kind: 'ltc',
     start(e) {
       emit = e;
+      // Kick the capture-tool build right away: a catalog install ships
+      // source only and a catalog update wipes any previously built binary,
+      // so coming up after an install/update must rebuild it without
+      // waiting for a device to be picked or a listener to need it.
+      ensureCaptureBinary({ moduleDir, log });
       if (!device) {
-        word = { error: 'LTC timecode is on but no audio device is selected — pick one in Admin' };
+        word = {
+          error: 'Not configured — see Admin',
+          detail: 'LTC timecode is on but no audio device is selected — pick one in Admin',
+        };
         publish();
         return;
       }
@@ -539,7 +691,8 @@ function createLtcSource({ config, log, moduleDir }) {
       listener = null;
     },
     health() {
-      return { status: status(), message: message() };
+      // The admin page gets the full story; the tiles got the short one.
+      return { status: status(), message: (word && word.error && word.detail) || message() };
     },
   };
 }
@@ -588,7 +741,15 @@ function createModuleSource({ moduleId, name, shellPort, log }) {
   let silenceTimer = null;
   let backoff = BACKOFF_MIN_MS;
 
-  function message() {
+  /** Short, for the tiles; the lastError detail belongs to the admin line.
+      The client prefixes the source label, so it isn't repeated here. */
+  function tileMessage() {
+    if (state === 'ok') return `${timers.length} timer${timers.length === 1 ? '' : 's'}`;
+    if (state === 'connecting') return 'Connecting…';
+    return 'Unavailable';
+  }
+
+  function adminMessage() {
     if (state === 'ok') return `${timers.length} timer${timers.length === 1 ? '' : 's'}${via ? ` (${via})` : ''}`;
     if (state === 'connecting') return lastError ? `reconnecting — ${lastError}` : 'connecting…';
     return `unreachable — ${lastError}`;
@@ -596,7 +757,7 @@ function createModuleSource({ moduleId, name, shellPort, log }) {
 
   function publish() {
     if (stopped) return;
-    emit({ label, status: state, message: message(), timers, updatedAt });
+    emit({ label, status: state, message: tileMessage(), timers, updatedAt });
   }
 
   function accept(raw) {
@@ -774,7 +935,7 @@ function createModuleSource({ moduleId, name, shellPort, log }) {
       if (!stopped && !stream && via === 'poll') connectStream();
     },
     health() {
-      return { status: state, message: message() };
+      return { status: state, message: adminMessage() };
     },
   };
 }
@@ -942,6 +1103,8 @@ const GEAR = {
   all: { instanceSchema: FULL_SCHEMA, instanceGroups: FULL_GROUPS },
   /** One ProPresenter or module timer: its elements, and the tone its digits take per state. */
   timer: gearOf([...TIMER_ELEMENTS, ...COLOURS], OPEN_COLOURS),
+  /** The video countdown: a timer card, plus whether looping media counts. */
+  video: gearOf([...TIMER_ELEMENTS, 'showLoops', ...COLOURS], OPEN_COLOURS),
   /** The timecode: running, no signal (warning) and stopped (idle) — it never overruns, and frames are frames. */
   ltc: gearOf(['showNames', 'showStatus', 'runningColor', 'warningColor', 'idleColor'], OPEN_COLOURS),
   /** The time of day: plain digits, so only how they read. */
@@ -955,6 +1118,7 @@ function gearFor(source, timer) {
   if (source.kind === 'ltc') return GEAR.ltc;
   if (source.kind === 'clock') return GEAR.clock;
   if (timer.kind === 'clock') return GEAR.providerClock;
+  if (source.id === 'propresenter' && timer.id === 'video') return GEAR.video;
   return GEAR.timer;
 }
 
@@ -1163,7 +1327,8 @@ module.exports = {
       for (const t of src.timers) {
         const description = src.kind === 'ltc' ? 'The incoming LTC timecode on its own'
           : src.kind === 'clock' ? 'The time of day on its own'
-            : `This ${src.label} ${KIND_WORD[t.kind] || 'timer'} on its own`;
+            : src.id === 'propresenter' && t.id === 'video' ? 'Time left on the video ProPresenter is playing'
+              : `This ${src.label} ${KIND_WORD[t.kind] || 'timer'} on its own`;
         // Layouts from before 1.3.0 hold 'timer:<uuid>' / 'ltc' — the same tiles.
         const aliases = src.id === 'propresenter' ? [`timer:${t.id}`] : src.kind === 'ltc' ? ['ltc'] : [];
         out.push({ id: `solo:${src.id}:${t.id}`, name: t.label, description, ...oneCard, ...gearFor(src, t), ...(aliases.length ? { aliases } : {}) });
@@ -1172,7 +1337,7 @@ module.exports = {
     return out;
   },
 
-  routes() {
+  routes({ log }) {
     return {
       'GET /state': (req, res) => {
         sendJson(res, 200, { state: current ? current.getState() : emptyState() });
@@ -1195,7 +1360,15 @@ module.exports = {
 
       // The admin device picker asks this machine what it can hear. The
       // options shape matches the admin select's optionsRoute contract.
+      // Opening the picker also kicks the capture-tool build when a catalog
+      // install/update left only the source — without this, no tool meant
+      // no device list, and no device meant nothing would ever build it.
       'GET /ltc/devices': (req, res) => {
+        const tool = ensureCaptureBinary({ moduleDir: __dirname, log });
+        if (!tool.ready) {
+          sendJson(res, 200, { options: [], error: tool.detail || tool.error });
+          return;
+        }
         const bin = path.join(__dirname, 'ltc-capture');
         const child = spawn(bin, ['--list'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 4000 });
         let err = '';

modules/spl-meter/module.json

@@ -1,7 +1,7 @@
 {
   "id": "spl-meter",
   "name": "SPL Meter",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "proddash": ">=1.5.0",
   "description": "Calibrated sound level, Leq and RTA from an audio input on this machine",
   "permissions": [

modules/spl-meter/server.js

@@ -20,7 +20,7 @@
  */
 
 const path = require('path');
-const { createSplListener } = require('./spl-listener');
+const { createSplListener, ensureCaptureBinary } = require('./spl-listener');
 
 /** Reference level of a sound level calibrator. Effectively always 94 dB. */
 const CALIBRATOR_DB = 94;
@@ -114,11 +114,19 @@ module.exports = {
       error: '',
       streams: new Set(),
       silentSince: null,
+      toolMissing: '',
       listener: null,
       lastSent: '',
       pinger: null,
     };
 
+    // Before anything else: the device picker shells out to this tool, so a
+    // machine that installed the module from the catalog (source only — the
+    // binary is gitignored) needs the build kicked off here. Waiting for a
+    // listener would never happen: no tool means no device list, and no
+    // device means no listener.
+    state.toolMissing = ensureCaptureBinary({ moduleDir, log });
+
     if (!config.enabled) {
       state.error = 'Sound level measurement is off — turn it on in ProdDash settings';
       return { stop() { teardown(); }, health: () => ({ status: 'error', message: state.error }) };
@@ -177,6 +185,9 @@ module.exports = {
     return {
       stop() { teardown(); },
       health() {
+        if (state.toolMissing && !fsExists(path.join(moduleDir, 'spl-capture'))) {
+          return { status: 'error', message: state.toolMissing };
+        }
         if (state.error) return { status: 'error', message: state.error };
         if (!state.frame) return { status: 'connecting', message: 'waiting for the first reading' };
         const quiet = silentMs();
@@ -300,6 +311,13 @@ module.exports = {
       /** Device list for the admin page. Runs the capture tool's --list,
           which is the only thing that knows what CoreAudio can see. */
       'GET /devices': async (req, res) => {
+        const missing = ensureCaptureBinary({ moduleDir: __dirname, log });
+        if (missing) {
+          if (state) state.toolMissing = missing;
+          log(`device list unavailable — ${missing}`);
+          json(res, 200, { options: [] });
+          return;
+        }
         try {
           const devices = await listDevices();
           json(res, 200, {
@@ -438,6 +456,10 @@ function listDevices() {
   });
 }
 
+function fsExists(p) {
+  try { return require('fs').existsSync(p); } catch { return false; }
+}
+
 function json(res, code, body) {
   const text = JSON.stringify(body);
   res.writeHead(code, {

modules/spl-meter/spl-listener.js

@@ -17,7 +17,8 @@
  * module's ltc-capture. It normally arrives already built — compiled beside
  * the app, or copied from any Mac of the same architecture. When it is
  * missing this will build it, but in the background and never on the event
- * loop: see ensureBinary for what that cost the first time it was wrong.
+ * loop, and from module scope so the device picker can trigger it too — see
+ * ensureCaptureBinary for what both of those cost the first time round.
  *
  * The same macOS gotcha applies as for LTC, and is worth repeating because
  * it costs an afternoon every time: a ProdDash launched over SSH or from a
@@ -30,6 +31,74 @@ const path = require('path');
 const fs = require('fs');
 const { spawn } = require('child_process');
 
+const BUILD_HELP = 'Sound level capture tool missing — build it on any Apple Silicon Mac with '
+  + '`swiftc -O -o modules/spl-meter/spl-capture modules/spl-meter/spl-capture.swift` '
+  + 'and copy it next to spl-capture.swift';
+const BUILDING = 'Building the capture tool — this takes a minute or two';
+
+/**
+ * Build the capture tool if it is missing, WITHOUT blocking, and shared by
+ * everything that needs it.
+ *
+ * This lives at module scope rather than inside a listener because of a trap
+ * the first version walked into: the admin page's device picker runs the tool
+ * with --list, but the build only ran when a listener started, and a listener
+ * only starts once a device has been picked. On a machine that got the module
+ * from the catalog — source only, the binary being gitignored — the picker
+ * was empty, and nothing would ever fill it.
+ *
+ * It also must never block. It was a spawnSync once, copied from the LTC
+ * listener where the source is a third the size and builds in seconds. Here
+ * it took nearly two minutes on the production Mac and held the Node event
+ * loop for all of it, freezing every other module, then did it again on the
+ * next retry.
+ *
+ * The binary should normally already be there: built beside the app, or
+ * copied from any Mac of the same architecture. This is the fallback.
+ *
+ * @returns {string} '' when the tool is ready, otherwise what to say.
+ */
+let building = false;
+let buildFailed = false;
+
+function ensureCaptureBinary({ moduleDir, log, onReady }) {
+  const bin = path.join(moduleDir, 'spl-capture');
+  if (fs.existsSync(bin)) return '';
+  const src = bin + '.swift';
+  if (!fs.existsSync(src)) return 'spl-capture.swift is missing from the module folder';
+  if (building) return BUILDING;
+  if (buildFailed) return BUILD_HELP;
+
+  building = true;
+  log('spl-capture binary missing — building it in the background');
+  const build = spawn('swiftc', ['-O', '-o', bin, src], { stdio: ['ignore', 'ignore', 'pipe'] });
+  let buildErr = '';
+  build.stderr.setEncoding('utf8');
+  build.stderr.on('data', (t) => { buildErr = (buildErr + t).slice(-800); });
+  const giveUp = setTimeout(() => {
+    try { build.kill('SIGKILL'); } catch { /* already gone */ }
+  }, 300000);
+  build.on('error', (err) => {
+    clearTimeout(giveUp);
+    building = false; buildFailed = true;
+    log(`swiftc could not be run: ${err.message}`);
+  });
+  build.on('exit', (code) => {
+    clearTimeout(giveUp);
+    building = false;
+    if (code === 0 && fs.existsSync(bin)) {
+      log('spl-capture built');
+      buildFailed = false;
+      if (typeof onReady === 'function') onReady();
+      return;
+    }
+    buildFailed = true;
+    log(`spl-capture build failed (exit ${code})`
+      + (buildErr ? `: ${buildErr.trim().split('\n').pop()}` : ''));
+  });
+  return BUILDING;
+}
+
 const RESTART_MS = 5000;
 /** An immediate exit is config-shaped (bad device, channel out of range) —
     retrying every 5 s would only fill the log with the same sentence. */
@@ -53,64 +122,13 @@ function createSplListener(opts) {
   let stallTimer = null;
   let startedAt = 0;
   let meta = null;
-  let building = false;
-  let buildFailed = false;
   let lastFrameWall = 0;
 
-  const BUILD_HELP = 'Sound level capture tool missing — build it on any Apple Silicon Mac with '
-    + '`swiftc -O -o modules/spl-meter/spl-capture modules/spl-meter/spl-capture.swift` '
-    + 'and copy it next to spl-capture.swift';
-
-  /**
-   * Build the capture tool if it is missing, WITHOUT blocking.
-   *
-   * This used to be a spawnSync, copied from the LTC listener where the
-   * source is a third the size and builds in a few seconds. Here it took
-   * nearly two minutes on the production Mac and froze the entire ProdDash
-   * server for every second of it — one module's optional helper took the
-   * whole dashboard down, then did it again on every retry. Nothing that
-   * runs while a service might be on is allowed to hold the event loop.
-   *
-   * The build is a fallback for a module installed from the catalog on a
-   * machine with a Swift toolchain. The normal path is a binary built
-   * alongside the app, or copied from any same-architecture Mac.
-   *
-   * @returns {string} '' when the binary is ready, otherwise what to say.
-   */
+  /** '' when the tool is ready, otherwise what to say about it. */
   function ensureBinary() {
-    if (fs.existsSync(bin)) return '';
-    const src = bin + '.swift';
-    if (!fs.existsSync(src)) return 'spl-capture.swift is missing from the module folder';
-    if (building) return 'Building the capture tool — this takes a minute or two';
-    if (buildFailed) return BUILD_HELP;
-
-    building = true;
-    log('spl-capture binary missing — building it in the background');
-    const build = spawn('swiftc', ['-O', '-o', bin, src], { stdio: ['ignore', 'ignore', 'pipe'] });
-    let buildErr = '';
-    build.stderr.setEncoding('utf8');
-    build.stderr.on('data', (t) => { buildErr = (buildErr + t).slice(-800); });
-    const giveUp = setTimeout(() => {
-      try { build.kill('SIGKILL'); } catch { /* already gone */ }
-    }, 300000);
-    build.on('error', (err) => {
-      clearTimeout(giveUp);
-      building = false; buildFailed = true;
-      log(`swiftc could not be run: ${err.message}`);
-    });
-    build.on('exit', (code) => {
-      clearTimeout(giveUp);
-      building = false;
-      if (code === 0 && fs.existsSync(bin)) {
-        log('spl-capture built');
-        buildFailed = false;
-        if (!stopped) { clearTimeout(restartTimer); restartTimer = null; start(); }
-        return;
-      }
-      buildFailed = true;
-      log(`spl-capture build failed (exit ${code})` + (buildErr ? `: ${buildErr.trim().split('\n').pop()}` : ''));
-    });
-    return 'Building the capture tool — this takes a minute or two';
+    return ensureCaptureBinary({ moduleDir, log, onReady() {
+      if (!stopped) { clearTimeout(restartTimer); restartTimer = null; start(); }
+    } });
   }
 
   function scheduleRestart(ms) {
@@ -137,7 +155,7 @@ function createSplListener(opts) {
       onUpdate({ error: missing });
       // A build in flight calls start() itself when it lands; anything else
       // is config-shaped and should back off hard rather than spin.
-      if (!building) scheduleRestart(BAD_CONFIG_RETRY_MS);
+      if (missing !== BUILDING) scheduleRestart(BAD_CONFIG_RETRY_MS);
       return;
     }
 
@@ -236,4 +254,4 @@ function createSplListener(opts) {
   };
 }
 
-module.exports = { createSplListener };
+module.exports = { createSplListener, ensureCaptureBinary };

package.json

@@ -1,6 +1,6 @@
 {
   "name": "proddash",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "private": true,
   "description": "Modular production dashboard for Waters Church \u2014 zero-dependency Node server + vanilla client",
   "license": "UNLICENSED",

server.js

@@ -373,7 +373,18 @@ function mountModule(id) {
   const log = makeLog(id);
   try {
     const serverPath = path.join(man.dir, man.server);
-    // Re-require fresh config on every (re)mount; the module code itself stays cached.
+    // Drop the module's code from the require cache so every (re)mount runs
+    // the files on disk. Without this a module UPDATE swaps the folder while
+    // the process keeps executing the old code until ProdDash itself
+    // restarts — the manifest (read fresh from disk) then reports a version
+    // the running code isn't, and anything new in the update silently
+    // doesn't happen. Modules already have to come up clean on re-init
+    // (module guide), so a fresh load on config remounts is the same
+    // contract without the trap.
+    const cachePrefix = man.dir.endsWith(path.sep) ? man.dir : man.dir + path.sep;
+    for (const key of Object.keys(require.cache)) {
+      if (key.startsWith(cachePrefix)) delete require.cache[key];
+    }
     const mod = require(serverPath);
     const config = effectiveConfig(id);
     // What a module needs to reach the rest of ProdDash — another module's
@@ -1060,13 +1071,22 @@ async function installModule(id) {
   if (download) {
     const staging = path.join(INSTALLED_MODULES_DIR, `.${id}.installing`);
     fs.rmSync(staging, { recursive: true, force: true });
+    const shipped = new Set();
     for (const [rel, data] of remoteEntry.files) {
       if (!safeRelPath(rel)) continue;
+      shipped.add(rel);
       const target = path.join(staging, rel);
       fs.mkdirSync(path.dirname(target), { recursive: true });
       fs.writeFileSync(target, data);
     }
     const dest = path.join(INSTALLED_MODULES_DIR, id);
+    // Per-machine executables — a capture tool compiled here, or copied in
+    // by hand on a machine whose toolchain can't build it — are gitignored,
+    // so the repo never ships them. Replacing the folder must not destroy
+    // them: carry executables the download doesn't include over from the
+    // copy being replaced (or from the app's bundled copy on a first
+    // install), or "update" quietly kills a working module.
+    carryOverExecutables([dest, path.join(BUNDLED_MODULES_DIR, id)], staging, shipped);
     unmountModule(id);
     fs.rmSync(dest, { recursive: true, force: true });
     fs.renameSync(staging, dest);
@@ -1083,6 +1103,43 @@ async function installModule(id) {
   return { id, version: String(now?.version || ''), source: now?.source || '', downloaded: download };
 }
 
+/**
+ * Copy executable files (any execute bit) that `shipped` does not include
+ * from the first existing source dir into `staging`, keeping their relative
+ * path and mode. Executables only, on purpose: they are the per-machine
+ * build artifacts (gitignored, so never in a download), while stray text
+ * files from an old version — code an update deliberately removed — must
+ * NOT be resurrected.
+ */
+function carryOverExecutables(sourceDirs, staging, shipped) {
+  const from = sourceDirs.find((d) => {
+    try { return fs.statSync(d).isDirectory(); } catch { return false; }
+  });
+  if (!from) return;
+  const walk = (rel) => {
+    for (const e of fs.readdirSync(path.join(from, rel), { withFileTypes: true })) {
+      const relPath = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isDirectory()) {
+        walk(relPath);
+        continue;
+      }
+      if (!e.isFile() || shipped.has(relPath) || !safeRelPath(relPath)) continue;
+      try {
+        const stat = fs.statSync(path.join(from, relPath));
+        if (!(stat.mode & 0o111)) continue;
+        const target = path.join(staging, relPath);
+        fs.mkdirSync(path.dirname(target), { recursive: true });
+        fs.copyFileSync(path.join(from, relPath), target);
+        fs.chmodSync(target, stat.mode);
+        console.log(`[proddash] module update kept per-machine executable "${relPath}"`);
+      } catch (err) {
+        console.error(`[proddash] could not carry "${relPath}" across the update:`, err?.message || err);
+      }
+    }
+  };
+  walk('');
+}
+
 /** Remove a module: an installed copy is deleted; a bundled one is switched
     off and hidden (its folder belongs to the app). Settings are kept so a
     later reinstall picks them up again. */

tools/pp-timers-mock.js

@@ -152,10 +152,39 @@ const server = http.createServer((req, res) => {
   if (p === '/v1/timers') return sendJson(res, TIMERS.filter((t) => !DROP.has(t.id.uuid)));
   if (p === '/v1/timers/current') return sendJson(res, currentTimes().filter((t) => !DROP.has(t.id.uuid)));
   if (p === '/v1/timecode/status' && !NO_LTC) return sendJson(res, timecodeStatus());
+  if (p === '/v1/transport/presentation/current') return sendJson(res, transport().current);
+  if (p === '/v1/transport/presentation/time') return sendJson(res, transport().time);
 
   sendJson(res, { error: 'not found' }, 404);
 });
 
+/* ── transport (video countdown): a 4-minute cycle ─────────────────
+   0–60 s   "Sermon Bumper.mp4" (3:00) playing
+   60–75 s  the same bumper paused at 1:00
+   75–90 s  playing again
+   90–120 s nothing loaded
+   120–240 s "Autumn Loop.mp4" (0:15) playing and wrapping — the module
+             must infer looping from the position jumping back.
+   Shapes match ProPresenter 21.4 live: `current` = { is_playing, uuid,
+   name, artist, audio_only, duration }, `time` = bare seconds (float). */
+function transport() {
+  const phase = ((Date.now() - startedAt) / 1000) % 240;
+  const none = { current: { is_playing: false, uuid: '', name: '', artist: '', audio_only: false, duration: 0 }, time: -1 };
+  if (phase < 90) {
+    const playing = phase < 60 || phase >= 75;
+    const pos = Math.min(phase, 60) + (phase >= 75 ? phase - 75 : 0);
+    return {
+      current: { is_playing: playing, uuid: 'MEDIA-BUMPER', name: 'Sermon Bumper.mp4', artist: '', audio_only: false, duration: 180 },
+      time: Math.round(pos * 10) / 10,
+    };
+  }
+  if (phase < 120) return none;
+  return {
+    current: { is_playing: true, uuid: 'MEDIA-LOOP', name: 'Autumn Loop.mp4', artist: '', audio_only: false, duration: 15 },
+    time: Math.round(((phase - 120) % 15) * 10) / 10,
+  };
+}
+
 /* ── stage-display websocket (/stagedisplay) ─────────────────────── */
 
 const cryptoMod = require('crypto');