Timers: LTC timecode via the stage-display websocket

ProPresenter's HTTP API has no timecode route (verified: 21.4 returns
404), but its classic stage-display websocket still answers — so LTC now
comes from a stage layout field labeled "LTC": a zero-dependency RFC6455
client (stage-ws.js) authenticates (new stagePassword admin config),
resolves the LTC-labeled frame's uid from the layout list, and treats any
message carrying that uid as the timecode text. "Receiving" is a 2.5s
staleness heuristic; frozen or placeholder text reads as no-signal. The
HTTP probe stays authoritative when it ever answers (a 404 verdict is
retried once a minute), and the LTC card surfaces the reason when
timecode is unavailable (bad stage password, no LTC field). pp-timers-mock
grows a /stagedisplay websocket with --stage-pwd and --no-ltc-field to
exercise every path.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Waters Church
2026-08-31 17:05:23 -04:00
co-authored by Claude Fable 5
parent f80790e3a1
commit 444f03938d
7 changed files with 551 additions and 15 deletions
+3 -1
View File
@@ -210,7 +210,9 @@ export default function create({ root, moduleApi }) {
if (ltc.supported === false) {
mode = 'unavailable';
card.timeEl.textContent = '—';
card.stateEl.textContent = 'Timecode not available on this ProPresenter';
// The server says why when it knows (stage password rejected, no
// stage field labeled LTC, …) — surface that over the generic line.
card.stateEl.textContent = ltc.note || 'Timecode not available on this ProPresenter';
} else if (ltc.supported === null) {
mode = 'waiting';
card.timeEl.textContent = displayTime(ltc.time);
+5
View File
@@ -18,6 +18,11 @@
"type": "password",
"label": "API password (only if set in ProPresenter)",
"default": ""
},
"stagePassword": {
"type": "password",
"label": "Stage display password (for LTC — ProPresenter Settings → Network)",
"default": ""
}
}
}
+53 -10
View File
@@ -23,10 +23,15 @@
* "overr" as overrun. The API exposes NO per-timer color anywhere.
* GET /v1/timecode/status → NOT in the published spec. The spec (fetched
* 2026-08, 0 mentions of "timecode", not in the /v1/status/updates
* allowlist either) documents no timecode/LTC route at all. We probe this
* candidate route once per connection anyway so a future ProPresenter
* that adds it lights up without a module update; a 404 marks LTC
* "not available on this ProPresenter" (ltc.supported = false).
* allowlist either) documents no timecode/LTC route at all — verified
* live: ProPresenter 21.4 returns 404. We probe this candidate route
* once per connection anyway so a future ProPresenter that adds it
* lights up without a module update.
*
* Because the HTTP API has no timecode, LTC actually comes from the classic
* stage-display websocket (see stage-ws.js): a stage layout field labeled
* "LTC" streams its text to us. Source precedence: the HTTP route if it ever
* answers (authoritative), else the stage field, else "not available".
*
* ProPresenter's built-in HTTP server is easily overwhelmed (see the hot-path
* notes in ../propresenter-now-next/propresenter-core). So: requests run
@@ -47,6 +52,8 @@ const REQUEST_TIMEOUT_MS = 4000;
/** SSE comment ping cadence — keeps idle connections alive through sleepy Wi-Fi. */
const HEARTBEAT_MS = 15000;
const { createStageLtcClient } = require('./stage-ws');
/** Set by init(), read by the routes — both are rebuilt together on remount. */
let current = null;
@@ -56,9 +63,10 @@ function clearedState(enabled) {
reachable: false,
lastError: '',
timers: [],
// supported: null = not probed yet (or ProPresenter unreachable),
// true/false once a reachable ProPresenter answered the probe.
ltc: { supported: null, time: '', receiving: false },
// supported: null = no verdict yet (probing, or ProPresenter
// unreachable); true once a timecode source is live; false when both
// sources came up empty (note says why, when we know).
ltc: { supported: null, time: '', receiving: false, source: '', note: '' },
};
}
@@ -85,6 +93,23 @@ module.exports = {
/** null = probe /v1/timecode/status on the next reachable tick. */
let ltcSupported = null;
let ltcLast = { time: '', receiving: false };
/** Live view of the stage-display websocket's LTC field (stage-ws.js). */
let stageLtc = { bound: false, time: '', receiving: false, note: '' };
/** One LTC verdict from both sources: HTTP route wins if it ever
answers (authoritative), else the stage-display field. */
function composeLtc() {
if (ltcSupported === true) {
return { supported: true, source: 'api', time: ltcLast.time, receiving: ltcLast.receiving, note: '' };
}
if (stageLtc.bound) {
return { supported: true, source: 'stage', time: stageLtc.time, receiving: stageLtc.receiving, note: '' };
}
if (ltcSupported === null && !stageLtc.note) {
return { supported: null, source: '', time: '', receiving: false, note: '' };
}
return { supported: false, source: '', time: '', receiving: false, note: stageLtc.note || '' };
}
function url(target) {
const built = new URL(`http://${host}:${port}${target}`);
@@ -197,7 +222,10 @@ module.exports = {
}
async function pollLtc() {
if (ltcSupported === false) return;
// A 404 verdict is retried once a minute — an endpoint appearing
// without an unreachable spell (ProPresenter hot-swapped in testing,
// or some future in-place upgrade) must not stay invisible forever.
if (ltcSupported === false && tick % 120 !== 0) return;
try {
const body = await requestJson('/v1/timecode/status');
if (ltcSupported === null) log('timecode endpoint answered — LTC card is live');
@@ -221,7 +249,7 @@ module.exports = {
reachable: latest.reachable,
lastError: latest.lastError,
timers: latest.timers,
ltc: { supported: ltcSupported, time: ltcLast.time, receiving: ltcLast.receiving },
ltc: composeLtc(),
};
if (!streams.size) return;
let frame;
@@ -271,9 +299,20 @@ module.exports = {
pollTimer = setTimeout(pollTick, latest.reachable ? POLL_MS : RETRY_MS);
}
let stageClient = null;
if (enabled) {
pollTick();
log(`polling timers on ${host}:${port}`);
stageClient = createStageLtcClient({
host,
port,
password: String(config.stagePassword || ''),
log,
onUpdate(update) {
stageLtc = update;
broadcast();
},
});
} else {
log('no ProPresenter host configured — set one in /admin');
}
@@ -296,6 +335,7 @@ module.exports = {
stopped = true;
clearTimeout(pollTimer);
clearInterval(heartbeat);
stageClient?.stop();
for (const res of streams) {
try { res.end(); } catch { /* already gone */ }
}
@@ -305,7 +345,10 @@ module.exports = {
health() {
if (!enabled) return { status: 'error', message: 'No ProPresenter host configured' };
if (latest.reachable) {
const ltcNote = latest.ltc.supported ? ' (with timecode)' : '';
const ltc = latest.ltc;
const ltcNote = ltc.supported
? (ltc.source === 'stage' ? ', LTC via stage display' : ', LTC via API')
: (ltc.note ? ` (${ltc.note})` : '');
return { status: 'ok', message: `Polling ${host}:${port}, ${latest.timers.length} timer(s)${ltcNote}` };
}
return {
+347
View File
@@ -0,0 +1,347 @@
'use strict';
/**
* ProPresenter stage-display websocket client — the LTC timecode source.
*
* ProPresenter's HTTP openAPI exposes no timecode route (see server.js), but
* its classic stage-display websocket (ws://host:port/stagedisplay — the
* Pro6-era protocol, still answered by ProPresenter 21; verified live: it
* responds `{"acn":"ath","ath":…,"majorVersion":7,"minorVersion":21}`) streams
* the text of stage-layout fields. So: the operator puts a field labeled
* "LTC" on a stage layout, and this client reads that field's live text.
*
* Protocol (community-documented, github.com/jeffmikels/ProPresenter-API):
* → {"pwd":"<stage password>","ptl":610,"acn":"ath"}
* ← {"acn":"ath","ath":true|false,"err":"…"}
* → {"acn":"psl"} ← {"acn":"psl","uid":"<layout uid>"}
* → {"acn":"asl"} ← {"acn":"asl","ary":[{acn:"sl",uid,nme,fme:[…]},…]}
* ← {"acn":"sys","txt":" 11:17 AM"} every second — our liveness signal
* ← {"acn":"tmr","uid":"…","txt":"…"} live text for a layout field's uid
*
* A layout's `fme` frames carry `nme` (the label) and, for linked fields, a
* `uid`. We bind to the first frame labeled "LTC" (case-insensitive), then
* treat any message carrying that uid as the timecode text — matching by uid
* rather than acn on purpose, since how ProPresenter 21 tags timecode
* updates is undocumented. "Receiving" is a staleness heuristic: LTC text
* that hasn't advanced for STALE_MS is a frozen/no-signal feed.
*
* Zero-dependency by design (like the rest of ProdDash): a minimal RFC6455
* client — masked client frames, text + ping/pong + close, fragmented text
* reassembly. TLS is not needed (ProPresenter's server is plain ws://).
*/
const net = require('net');
const crypto = require('crypto');
const RECONNECT_MS = 3000;
/** Auth rejections retry slowly — a wrong password never fixes itself fast. */
const BAD_AUTH_RETRY_MS = 30000;
/** ProPresenter sends a clock tick every second; silence this long = dead link. */
const LIVENESS_MS = 10000;
/** LTC text that has not advanced for this long counts as no-signal. */
const STALE_MS = 2500;
const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
/**
* @param {{host:string, port:number, password:string, log:Function,
* onUpdate:(ltc:{bound:boolean,time:string,receiving:boolean,note:string})=>void}} opts
* @returns {{stop:()=>void}}
*/
function createStageLtcClient({ host, port, password, log, onUpdate }) {
let sock = null;
let stopped = false;
let reconnectTimer = null;
let livenessTimer = null;
let staleTimer = null;
let ltcUid = ''; // uid of the frame labeled LTC, once bound
let lastText = '';
let lastAdvance = 0;
// Known-but-unused message types; anything else is logged once so a new
// ProPresenter's timecode tag shows up in the server log for discovery.
const loggedUnknownAcn = new Set(['fv', 'msg', 'vid', 'tmr', 'cs', 'ns', 'csn', 'nsn']);
function emit(partial) {
onUpdate({
bound: Boolean(ltcUid),
time: lastText,
receiving: false,
note: '',
...partial,
});
}
/* ── outgoing frames (client → server must be masked) ───────────── */
function sendFrame(opcode, payload) {
if (!sock || sock.destroyed) return;
const mask = crypto.randomBytes(4);
const len = payload.length;
let header;
if (len < 126) {
header = Buffer.from([0x80 | opcode, 0x80 | len]);
} else if (len < 65536) {
header = Buffer.alloc(4);
header[0] = 0x80 | opcode;
header[1] = 0x80 | 126;
header.writeUInt16BE(len, 2);
} else {
header = Buffer.alloc(10);
header[0] = 0x80 | opcode;
header[1] = 0x80 | 127;
header.writeBigUInt64BE(BigInt(len), 2);
}
const masked = Buffer.from(payload);
for (let i = 0; i < masked.length; i += 1) masked[i] ^= mask[i % 4];
try {
sock.write(Buffer.concat([header, mask, masked]));
} catch { /* socket died mid-write; liveness/close handling reconnects */ }
}
function sendJson(obj) {
sendFrame(0x1, Buffer.from(JSON.stringify(obj)));
}
/* ── protocol: layouts → find the LTC-labeled frame ─────────────── */
let assignedLayoutUid = '';
function bindFromLayouts(layouts) {
const isLtcFrame = (f) => String(f?.nme || '').trim().toLowerCase() === 'ltc';
const pick = (layout) => (Array.isArray(layout?.fme) ? layout.fme.find(isLtcFrame) : null);
// Prefer the layout ProPresenter assigned to this client; fall back to
// any layout with an LTC-labeled frame.
const ordered = layouts.slice().sort((a, b) =>
(b.uid === assignedLayoutUid ? 1 : 0) - (a.uid === assignedLayoutUid ? 1 : 0));
for (const layout of ordered) {
const frame = pick(layout);
if (frame && frame.uid) {
if (ltcUid !== frame.uid) {
ltcUid = String(frame.uid);
log(`stage display: bound LTC to field "${frame.nme}" (${ltcUid}) in layout "${layout.nme || layout.uid}"`);
emit({ receiving: false });
}
return;
}
if (frame && !frame.uid) {
log(`stage display: layout "${layout.nme}" has an LTC field with no uid — it never streams; link it to a timecode/timer source`);
}
}
ltcUid = '';
emit({ bound: false, time: '', note: 'No stage layout field labeled "LTC"' });
}
function handleMessage(obj) {
const acn = String(obj.acn || '');
switch (acn) {
case 'ath':
if (obj.ath === true) {
log('stage display: authenticated');
sendJson({ acn: 'psl' }); // which layout are we assigned?
sendJson({ acn: 'asl' }); // all layouts, with their frames
} else {
const err = String(obj.err || 'authentication rejected');
log(`stage display: auth failed — ${err}`);
emit({ bound: false, time: '', note: 'Stage display password rejected — set it in Admin' });
scheduleReconnect(BAD_AUTH_RETRY_MS);
destroySocket();
}
return;
case 'psl':
assignedLayoutUid = String(obj.uid || '');
return;
case 'asl':
if (Array.isArray(obj.ary)) bindFromLayouts(obj.ary);
return;
case 'sl':
// A layout definition was pushed (assignment or edit) — it may not
// be ours, so re-resolve from the authoritative full list instead
// of rebinding blindly.
sendJson({ acn: 'psl' });
sendJson({ acn: 'asl' });
return;
case 'sys': // per-second clock — liveness only
return;
default:
break;
}
// Anything carrying our bound uid is the LTC text, whatever its acn —
// ProPresenter 21's tag for timecode fields is undocumented.
if (ltcUid && obj.uid === ltcUid && typeof obj.txt === 'string') {
const txt = obj.txt.trim();
const placeholder = !txt || /^[-–—:;.\s]*$/.test(txt);
if (placeholder) {
lastText = '';
emit({ receiving: false });
return;
}
if (txt !== lastText) {
lastText = txt;
lastAdvance = Date.now();
emit({ receiving: true });
clearTimeout(staleTimer);
staleTimer = setTimeout(() => {
// Frozen text = LTC stopped arriving at ProPresenter.
emit({ receiving: false });
}, STALE_MS);
staleTimer.unref?.();
}
return;
}
if (acn && !loggedUnknownAcn.has(acn) && loggedUnknownAcn.size < 30) {
loggedUnknownAcn.add(acn);
log(`stage display: unhandled message type "${acn}" — ${JSON.stringify(obj).slice(0, 160)}`);
}
}
/* ── incoming frames ────────────────────────────────────────────── */
function connect() {
if (stopped) return;
let buf = Buffer.alloc(0);
let upgraded = false;
let fragments = null;
const key = crypto.randomBytes(16).toString('base64');
sock = net.connect(port, host);
sock.setNoDelay(true);
const bumpLiveness = () => {
clearTimeout(livenessTimer);
livenessTimer = setTimeout(() => {
log('stage display: silent too long — reconnecting');
destroySocket();
scheduleReconnect(RECONNECT_MS);
}, LIVENESS_MS);
livenessTimer.unref?.();
};
sock.on('connect', () => {
sock.write(
`GET /stagedisplay HTTP/1.1\r\n` +
`Host: ${host}:${port}\r\n` +
`Upgrade: websocket\r\nConnection: Upgrade\r\n` +
`Sec-WebSocket-Key: ${key}\r\nSec-WebSocket-Version: 13\r\n\r\n`);
bumpLiveness();
});
sock.on('data', (chunk) => {
bumpLiveness();
buf = Buffer.concat([buf, chunk]);
if (!upgraded) {
const idx = buf.indexOf('\r\n\r\n');
if (idx === -1) return;
const head = buf.slice(0, idx).toString();
buf = buf.slice(idx + 4);
const statusLine = head.split('\r\n')[0] || '';
if (!/ 101 /.test(statusLine + ' ')) {
log(`stage display: no websocket upgrade (${statusLine.trim()}) — this ProPresenter may not serve /stagedisplay`);
emit({ bound: false, time: '', note: 'No stage display websocket on this ProPresenter' });
destroySocket();
scheduleReconnect(BAD_AUTH_RETRY_MS);
return;
}
const accept = crypto.createHash('sha1').update(key + WS_MAGIC).digest('base64');
const m = head.match(/sec-websocket-accept:\s*(\S+)/i);
if (m && m[1] !== accept) log('stage display: Sec-WebSocket-Accept mismatch (continuing)');
upgraded = true;
sendJson({ pwd: String(password || ''), ptl: 610, acn: 'ath' });
}
// decode server frames (unmasked; tolerate masked anyway)
while (buf.length >= 2) {
const fin = (buf[0] & 0x80) !== 0;
const opcode = buf[0] & 0x0f;
const maskBit = (buf[1] & 0x80) !== 0;
let len = buf[1] & 0x7f;
let off = 2;
if (len === 126) {
if (buf.length < 4) return;
len = buf.readUInt16BE(2);
off = 4;
} else if (len === 127) {
if (buf.length < 10) return;
len = Number(buf.readBigUInt64BE(2));
off = 10;
}
const maskLen = maskBit ? 4 : 0;
if (buf.length < off + maskLen + len) return;
let payload = buf.slice(off + maskLen, off + maskLen + len);
if (maskBit) {
const mask = buf.slice(off, off + 4);
payload = Buffer.from(payload);
for (let i = 0; i < payload.length; i += 1) payload[i] ^= mask[i % 4];
}
buf = buf.slice(off + maskLen + len);
if (opcode === 0x9) { // ping → pong
sendFrame(0xA, payload);
continue;
}
if (opcode === 0x8) { // close
destroySocket();
scheduleReconnect(RECONNECT_MS);
return;
}
if (opcode === 0x1 || (opcode === 0x0 && fragments)) {
if (!fin || opcode === 0x0) { // fragmented text
fragments = fragments ? Buffer.concat([fragments, payload]) : payload;
if (!fin) continue;
payload = fragments;
fragments = null;
}
let obj;
try {
obj = JSON.parse(payload.toString());
} catch {
continue;
}
if (obj && typeof obj === 'object') handleMessage(obj);
}
// binary frames (slide images) are ignored
}
});
sock.on('error', () => { /* close handler reconnects */ });
sock.on('close', () => {
clearTimeout(livenessTimer);
if (stopped) return;
if (!reconnectTimer) {
emit({ receiving: false });
scheduleReconnect(RECONNECT_MS);
}
});
}
function destroySocket() {
if (sock) {
try { sock.destroy(); } catch { /* already gone */ }
sock = null;
}
}
function scheduleReconnect(ms) {
if (stopped || reconnectTimer) return;
reconnectTimer = setTimeout(() => {
reconnectTimer = null;
connect();
}, ms);
reconnectTimer.unref?.();
}
connect();
return {
stop() {
stopped = true;
clearTimeout(reconnectTimer);
clearTimeout(livenessTimer);
clearTimeout(staleTimer);
destroySocket();
},
};
}
module.exports = { createStageLtcClient };