michael/ProdDash
1
0
Fork 0
Code Issues Pull Requests 3 Actions Packages Projects Releases 1 Wiki Activity

Merge main (PRs #5, #7, #9, #10) into the PCO Plan branch

Browse Source 
Resolves the admin form conflicts in favour of this branch's grouped /
collapsible / dependent-select additions (the base hunks were the timers
lane's, ported verbatim), keeps both sides of the README and module-guide
edits, and adopts main's versioning rules: the shell moves to 1.3.0 for the
new schema features (configGroups / instanceGroups, help, color fields,
grouped and dependent selects) and pco-plan 1.3.0 declares
"proddash": ">=1.3.0".

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
This commit is contained in:
Waters Church
2026-09-10 16:47:06 -04:00
co-authored by Claude Fable 5.1
parent d567f5459a 6d636190cd
commit 6b3e73824c
26 changed files with 2485 additions and 165 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.gitignore
+3
View File
@@ -7,3 +7,6 @@ dist/
# runtime state written by the admin page / layout saves # runtime state written by the admin page / layout saves
config/modules.json config/modules.json
config/layouts/ config/layouts/
# compiled per-machine, source sits next to it
modules/propresenter-timers/ltc-capture
CLAUDE.md
+10 -2
View File
@@ -16,8 +16,16 @@ contract** (manifest, client factory + moduleApi, optional server entry,
title-bar controls). The rules that matter most: title-bar controls). The rules that matter most:
- A module is one self-contained folder in `modules/` — **never modify the - A module is one self-contained folder in `modules/` — **never modify the
shell** (`server.js`, `public/`) to add one. Installation = drop the folder, shell** (`server.js`, `public/`) to add one. Installation = the admin page's
restart, configure in `/admin`. Available modules (downloads from the repo into the data directory), or
drop the folder and restart; configure in `/admin`.
- **All settings in the admin page** (`configSchema` / `instanceSchema`) —
never a separate setup page, hand-edited file or env var. **Dependencies
ship inside the module folder** (zero deps is the norm). **Everything the
module does runs inside its server entry** — no helper scripts, companion
programs or daemons the operator starts by hand; a listener or decoder is
started in `init()` and stopped in `stop()`. Declare `"proddash": ">=x.y.z"`
and bump the module's `version` on every change.
- Browsers never call upstream services directly; the module's server routes - Browsers never call upstream services directly; the module's server routes
proxy everything (no CORS, secrets stay server-side). proxy everything (no CORS, secrets stay server-side).
- Style with the shell's CSS variables only, scoped under - Style with the shell's CSS variables only, scoped under
README.md
+69 -9
View File
@@ -65,8 +65,9 @@ the app folder from `main` and start the new version with everything still
configured. The admin page shows the exact path in use, and the server prints configured. The admin page shows the exact path in use, and the server prints
it at startup (`Settings : …`). it at startup (`Settings : …`).
The directory holds `modules.json` (module config) and `layouts/` (named The directory holds `modules.json` (module config), `layouts/` (named
layouts), both written by the app itself. It may also hold a `proddash.json` layouts) and `modules/` (modules installed from the admin page), all written
by the app itself. It may also hold a `proddash.json`
with this machine's shell settings — the same keys as the checked-in with this machine's shell settings — the same keys as the checked-in
[config/proddash.json](config/proddash.json), which supplies the defaults: [config/proddash.json](config/proddash.json), which supplies the defaults:
@@ -86,6 +87,47 @@ so and falls back to the app's `config/` folder.
directory, so nothing has to be re-entered. The old files are left in place and directory, so nothing has to be re-entered. The old files are left in place and
ignored from then on. ignored from then on.
## Installing modules and updating
Everything below happens in the **admin page**; ProdDash talks to its GitHub
repository (`michaelmcgary2008/ProdDash`, branch `main` — change with
`repo` / `branch` in `proddash.json` or the `PRODDASH_REPO` variable,
`owner/repo#branch`). It downloads one small archive of the branch, at most
every few minutes, only while the admin page is open or for the update check
below. Nothing is installed without someone clicking.
- **Available modules** lists modules in the repo that aren't installed
here. **Install** downloads the module into the data directory's `modules/`
and starts it right away — nothing is written into the app folder, and no
restart is needed. Modules that ship with your copy of ProdDash are
"bundled"; ones you installed are "installed"; if both exist, the newer
version runs.
- **Uninstall** on a module card removes an installed module's files. For a
bundled module (its folder belongs to the app) it hides the module from
every dashboard instead; it reappears under Available modules and can be
brought back without downloading. Settings are kept either way.
- **Module updates**: when the repo has a newer version of an installed
module, its card shows **Update to vX**.
- **Version requirements**: every module declares the ProdDash versions it
needs (`"proddash": ">=1.1.0"` in its manifest). A module that needs a
newer shell is listed but not loaded, and cannot be installed until
ProdDash is updated.
- **ProdDash updates**: the admin page checks the repo shortly after start
and every six hours, and shows a banner when `main` has a newer version
(or new commits). **Update now** brings the app folder up to date and
restarts the server; dashboards reconnect on their own. A git checkout is
updated with `git pull --ff-only` (only when it is on the repo branch with
no local changes — otherwise the banner says why and you update with git).
A plain folder (no `.git`) has the repo archive unpacked over it; files
removed upstream are left behind but harmless. Settings and layouts are
never touched. **What changed** opens the commit comparison on GitHub.
- **Restarting**: after an update the server exits with code 75 and starts
its own replacement, which waits for the port to free up. If you supervise
ProdDash with your own launcher, set `PRODDASH_LAUNCHER=1` so the server
just exits and your launcher restarts it on exit code 75.
`PRODDASH_NO_REMOTE_CHECK=1` turns off the periodic check (the admin page
still checks when opened).
## Using the dashboard ## Using the dashboard
- **＋** — add any enabled module; multiple tiles of the same module are - **＋** — add any enabled module; multiple tiles of the same module are
@@ -98,8 +140,8 @@ ignored from then on.
sit flush — when two share a vertical edge, hover the seam and the same sit flush — when two share a vertical edge, hover the seam and the same
kind of pill appears; drag it to trade width (macOS split-view style). kind of pill appears; drag it to trade width (macOS split-view style).
- **Fullscreen** (the ⛶ button) is a viewing mode: the menu bar hides (its - **Fullscreen** (the ⛶ button) is a viewing mode: the menu bar hides (its
green tab brings it back, minus the Admin button), the occupied columns green lip at the top-left brings it back, minus the Admin button), the
stretch to the full width, and every column runs to the occupied columns stretch to the full width, and every column runs to the
bottom of the screen — the last tile in each column is stretched to end bottom of the screen — the last tile in each column is stretched to end
there. A short tile like the clock is never stretched into a ribbon: under there. A short tile like the clock is never stretched into a ribbon: under
another tile it slides to the bottom edge and the tile above grows into the another tile it slides to the bottom edge and the tile above grows into the
@@ -108,9 +150,11 @@ ignored from then on.
its normal row height and scrolls. its normal row height and scrolls.
- A tile's actions (menus, text size, clear…) live in its **title bar**; - A tile's actions (menus, text size, clear…) live in its **title bar**;
the small **notch** on the bar's bottom edge hides/shows the whole bar the small **notch** on the bar's bottom edge hides/shows the whole bar
for a clean wall-display look. The menu bar has the same kind of tab — for a clean wall-display look. The menu bar's handle is the **ProdDash
the green one under the ProdDash name, kept at the left so it never sits name itself**, wrapped in a translucent green pill at the left — click it
on top of a tile's own tab. to hide the bar; the slim green lip it leaves at the top-left edge brings
the bar back. It stays at the left so it never sits on top of a tile's
own tab.
- The **gear** on a tile holds per-tile settings (filters, text size, - The **gear** on a tile holds per-tile settings (filters, text size,
display options) — these belong to this browser's layout, not the server. display options) — these belong to this browser's layout, not the server.
- The **grid icon** — save the current arrangement to the server under a - The **grid icon** — save the current arrangement to the server under a
@@ -133,8 +177,23 @@ ignored from then on.
elapsed) and LTC timecode as auto-sized cards. The ＋ picker lists every 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" 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 and pick a selection via the tile's "Timers ▾" menu; overruns are
unmistakably red. Read-only — no start/stop controls. Admin config: unmistakably red. Read-only — no start/stop controls. Admin config is in
ProPresenter endpoint (host : port), password. three groups: **ProPresenter** (endpoint host : port, API password),
**LTC Timecode** (the listener switch, and — when it's on — the audio
device and channel), and **Display** (Timer font — Default or Monospace,
which keeps the digits from shifting as the numbers change).
ProPresenter exposes no timecode over any API, so LTC is decoded from the
audio signal, behind the admin **LTC listener** switch (off ⇒ no LTC tile
in the picker at all). On, the module captures the selected audio input
device/channel on the ProdDash machine — a native `ltc-capture` helper,
compiled on first use — and decodes the SMPTE frames in-process:
running/stopped/no-signal, the timecode counting frame-accurately in real
time, and the frame rate (incl. 29.97 drop-frame). macOS note: the
ProdDash server needs microphone permission — launch it from a logged-in
session (Start ProdDash.command) and approve the one-time prompt; a server
started over SSH or by bare launchd silently captures zeros. (Engine
self-test: `node modules/propresenter-timers/ltc.selftest.js`.)
- **PCO Plan** — the order of service from Planning Center Services: every - **PCO Plan** — the order of service from Planning Center Services: every
plan item with its scheduled start time, length, type, song key, plan item with its scheduled start time, length, type, song key,
description and item notes. When the ProPresenter module is running it description and item notes. When the ProPresenter module is running it
@@ -186,6 +245,7 @@ ProdDash/
│ ├── clock/ │ ├── clock/
│ ├── prodcom-transcript/ │ ├── prodcom-transcript/
│ └── propresenter-now-next/ (carries its own copy of propresenter-core) │ └── propresenter-now-next/ (carries its own copy of propresenter-core)
├── package.json name + version (what the update check compares)
├── config/ proddash.json defaults (runtime state lives in the ├── config/ proddash.json defaults (runtime state lives in the
│ per-machine data directory — see "Configure") │ per-machine data directory — see "Configure")
├── docs/MODULE-GUIDE.md how to build and install a module ├── docs/MODULE-GUIDE.md how to build and install a module
Start ProdDash.command
Regular → Executable
+7
View File
@@ -1,4 +1,11 @@
#!/bin/zsh #!/bin/zsh
# Double-click to start ProdDash (macOS) # Double-click to start ProdDash (macOS)
cd "$(dirname "$0")" cd "$(dirname "$0")"
# One dashboard per machine: take the port over from any prior instance
# (an SSH- or launchd-started one has no microphone access for the LTC
# listener — launching from here fixes that).
OLD=$(lsof -t -iTCP:24500 -sTCP:LISTEN 2>/dev/null)
[[ -n "$OLD" ]] && kill $OLD 2>/dev/null && sleep 1
# Prefer the bundled runtime (production machines have no system Node)
if [[ -x ./runtime/bin/node ]]; then exec ./runtime/bin/node server.js; fi
exec node server.js exec node server.js
config/proddash.json
+3 -1
View File
@@ -1,4 +1,6 @@
{ {
"port": 24500, "port": 24500,
"adminPasscode": "" "adminPasscode": "",
"repo": "michaelmcgary2008/ProdDash",
"branch": "main"
} }
docs/MODULE-GUIDE.md
+42 -5
View File
@@ -9,6 +9,31 @@ their own dashboards, move and resize them, and give each tile its own
per-tile settings. Your module renders inside the tile and talks to the per-tile settings. Your module renders inside the tile and talks to the
outside world only through the small API the shell hands it. outside world only through the small API the shell hands it.
## Rules every module follows
These are not style preferences — the admin page, the installer and the
people running the booth depend on them.
1. **All settings live in the ProdDash admin page.** Server-wide settings go
in `configSchema`, per-tile settings in `instanceSchema`. Never a separate
setup page, wizard, config file the operator edits by hand, or environment
variable.
2. **Dependencies ship inside the module folder.** Zero dependencies is the
norm (the shell has none). Anything you genuinely need is vendored into
the module — or fetched by your own `init()` on first start, with the
admin health line saying what is happening. No `npm install`, no
installer, no "run this first".
3. **Everything the module does runs inside the module.** No helper scripts,
companion programs, daemons or services the operator has to start next to
ProdDash. If your feature needs a listener, a decoder or a worker, your
server entry owns it: start it in `init()`, stop it in `stop()`, report
it in `health()`. A child process the module itself spawns and supervises
is fine; a program someone launches by hand is not.
4. **Declare the ProdDash version you need** (`"proddash": ">=1.1.0"` in the
manifest) and **bump your own `version`** whenever you change the module.
The admin page refuses to install a module whose requirement the running
shell doesn't meet, and it offers updates by comparing versions.
## The shape of a module ## The shape of a module
A module is one folder dropped into `modules/`: A module is one folder dropped into `modules/`:
@@ -21,9 +46,16 @@ modules/<id>/
└── ... assets (css, images…) served statically at /modules/<id>/ └── ... assets (css, images…) served statically at /modules/<id>/
``` ```
**Installation is exactly this:** copy the folder into `modules/`, restart **Installation is exactly this:** in the admin page, open **Available
ProdDash (`node server.js`), then configure and enable it at `/admin`. No modules** and press **Install** — the module is downloaded from the ProdDash
shell code changes, ever. repo into the server's data directory (`<data dir>/modules/<id>/`) and starts
immediately. Developing locally? Drop the folder into `modules/` (bundled
with the checkout) or into the data directory's `modules/` and restart. No
shell code changes, ever. Modules bundled with a checkout and modules
installed from the admin page live side by side; when both have the same id
the newer version runs. **Uninstall** in the admin page removes an installed
module's files (a bundled one is hidden instead, since its folder belongs to
the app); its settings are kept for a later reinstall.
## module.json ## module.json
@@ -32,6 +64,7 @@ shell code changes, ever.
"id": "my-module", "id": "my-module",
"name": "My Module", "name": "My Module",
"version": "1.0.0", "version": "1.0.0",
"proddash": ">=1.1.0",
"description": "One line shown in the Add-tile picker and the admin page", "description": "One line shown in the Add-tile picker and the admin page",
"client": "client.js", "client": "client.js",
"server": "server.js", "server": "server.js",
@@ -52,7 +85,9 @@ shell code changes, ever.
| --- | --- | --- | | --- | --- | --- |
| `id` | yes | Must equal the folder name. Lowercase, dashes. | | `id` | yes | Must equal the folder name. Lowercase, dashes. |
| `name` | yes | Human name shown on the tile header and in menus. | | `name` | yes | Human name shown on the tile header and in menus. |
| `version`, `description` | no | Shown in the admin page / picker. | | `version` | yes | Your module's version (`x.y.z`). Bump it on every change — the admin page offers updates when the repo's copy is newer than the installed one. |
| `proddash` | yes | The ProdDash versions this module works with: `">=1.1.0"`, `"^1.1.0"`, `">=1.1.0 <2.0.0"`, or `"*"`. A module whose requirement the running shell doesn't meet is listed in the admin page but never loaded, and can't be installed from the catalog. |
| `description` | no | Shown in the admin page / picker. |
| `client` | yes | Client entry file, loaded as an ES module. | | `client` | yes | Client entry file, loaded as an ES module. |
| `server` | no | Server entry file (CommonJS), loaded with `require()`. | | `server` | no | Server entry file (CommonJS), loaded with `require()`. |
| `style` | no | A stylesheet the shell injects once per module. | | `style` | no | A stylesheet the shell injects once per module. |
@@ -523,7 +558,9 @@ client-side failures (a tile that fails to start says so in the tile).
- ProPresenter timers: `node tools/pp-timers-mock.js 1600` — running, - ProPresenter timers: `node tools/pp-timers-mock.js 1600` — running,
overrunning, stopped and elapsed timers plus an LTC timecode that overrunning, stopped and elapsed timers plus an LTC timecode that
periodically drops to no-signal (`--no-ltc` serves a ProPresenter without periodically drops to no-signal (`--no-ltc` serves a ProPresenter without
a timecode API). Point the Timers module at host `127.0.0.1`, port `1600`. a timecode API). Also serves the stage-display websocket with an
LTC-labeled layout field (`--stage-pwd`, `--no-ltc-field` exercise its
failure paths). Point the Timers module at host `127.0.0.1`, port `1600`.
- Planning Center: `node tools/pco-mock.js` (port 24700) — folders, service - Planning Center: `node tools/pco-mock.js` (port 24700) — folders, service
types, plans (last week / today / next week), plan times and items with types, plans (last week / today / next week), plan times and items with
songs, keys and item notes, behind a Basic/Bearer auth check. Planning songs, keys and item notes, behind a Basic/Bearer auth check. Planning
modules/clock/module.json
+1
View File
@@ -2,6 +2,7 @@
"id": "clock", "id": "clock",
"name": "Clock", "name": "Clock",
"version": "1.0.0", "version": "1.0.0",
"proddash": ">=1.1.0",
"description": "Big booth clock — the smallest possible ProdDash module", "description": "Big booth clock — the smallest possible ProdDash module",
"client": "client.js", "client": "client.js",
"style": "style.css", "style": "style.css",
modules/pco-plan/module.json
+2 -1
View File
@@ -1,7 +1,8 @@
{ {
"id": "pco-plan", "id": "pco-plan",
"name": "PCO Plan", "name": "PCO Plan",
"version": "1.2.0", "version": "1.3.0",
"proddash": ">=1.3.0",
"description": "Order of service from Planning Center Services, following ProPresenter live", "description": "Order of service from Planning Center Services, following ProPresenter live",
"client": "client.js", "client": "client.js",
"server": "server.js", "server": "server.js",
modules/prodcom-transcript/module.json
+1
View File
@@ -2,6 +2,7 @@
"id": "prodcom-transcript", "id": "prodcom-transcript",
"name": "ProdCom", "name": "ProdCom",
"version": "1.0.0", "version": "1.0.0",
"proddash": ">=1.1.0",
"description": "Live ProdCom transcript stream", "description": "Live ProdCom transcript stream",
"client": "client.js", "client": "client.js",
"server": "server.js", "server": "server.js",
modules/propresenter-now-next/module.json
+1
View File
@@ -2,6 +2,7 @@
"id": "propresenter-now-next", "id": "propresenter-now-next",
"name": "ProPresenter", "name": "ProPresenter",
"version": "1.0.0", "version": "1.0.0",
"proddash": ">=1.1.0",
"description": "What is live in ProPresenter and what comes next", "description": "What is live in ProPresenter and what comes next",
"client": "client.js", "client": "client.js",
"server": "server.js", "server": "server.js",
modules/propresenter-timers/client.js
+154 -12
View File
@@ -11,6 +11,45 @@
const LTC_KEY = '__ltc__'; const LTC_KEY = '__ltc__';
/* ── SMPTE timecode math (module-scope, exported for tests) ─────────
The server anchors us ~4×/s with { time, fps, df, ageMs }; the card
counts every frame in between locally. That needs exact frame↔timecode
conversion, including 29.97 drop-frame (frames 00 and 01 don't exist at
the top of a minute, except every tenth minute). */
export function parseTc(str) {
const m = /^(\d{1,2}):(\d{2}):(\d{2})[:;.](\d{1,2})$/.exec(String(str || '').trim());
if (!m) return null;
return { h: Number(m[1]), m: Number(m[2]), s: Number(m[3]), f: Number(m[4]) };
}
export function tcToFrames(tc, nominal, df) {
let n = (tc.h * 3600 + tc.m * 60 + tc.s) * nominal + tc.f;
if (df) {
const mins = tc.h * 60 + tc.m;
n -= 2 * (mins - Math.floor(mins / 10));
}
return n;
}
export function framesToTc(n, nominal, df) {
// 10 DF minutes hold 17982 frames (the first minute 1800, the rest 1798).
const perDay = df ? 24 * 6 * 17982 : 24 * 3600 * nominal;
n = ((n % perDay) + perDay) % perDay;
if (df) {
const d = Math.floor(n / 17982);
const m10 = n % 17982;
const extra = m10 < 1800 ? 0 : Math.floor((m10 - 1800) / 1798) + 1;
const totalMin = d * 10 + extra;
// Re-add the two dropped frames per dropped minute, then read as 30fps.
n += 2 * (totalMin - Math.floor(totalMin / 10));
}
const f = n % nominal;
const secs = Math.floor(n / nominal);
const pad = (v) => String(v).padStart(2, '0');
return `${pad(Math.floor(secs / 3600))}:${pad(Math.floor(secs / 60) % 60)}:${pad(secs % 60)}:${pad(f)}`;
}
export default function create({ root, moduleApi }) { export default function create({ root, moduleApi }) {
let state = null; let state = null;
let feedOffline = false; let feedOffline = false;
@@ -61,7 +100,9 @@ export default function create({ root, moduleApi }) {
function menuRows() { function menuRows() {
const rows = (state?.timers || []).map((t) => ({ key: t.uuid, name: t.name })); const rows = (state?.timers || []).map((t) => ({ key: t.uuid, name: t.name }));
rows.push({ key: LTC_KEY, name: 'LTC timecode' }); // No LTC row while the listener is off in Admin — the item shouldn't
// even be offerable.
if (state?.ltcEnabled) rows.push({ key: LTC_KEY, name: 'LTC timecode' });
return rows; return rows;
} }
@@ -159,7 +200,7 @@ export default function create({ root, moduleApi }) {
for (const t of state?.timers || []) { for (const t of state?.timers || []) {
if (!hiddenItems.has(t.uuid)) items.push({ key: t.uuid, timer: t }); if (!hiddenItems.has(t.uuid)) items.push({ key: t.uuid, timer: t });
} }
if (!hiddenItems.has(LTC_KEY)) items.push({ key: LTC_KEY, ltc: ltcState }); if (state?.ltcEnabled && !hiddenItems.has(LTC_KEY)) items.push({ key: LTC_KEY, ltc: ltcState });
return items; return items;
} }
@@ -205,32 +246,117 @@ export default function create({ root, moduleApi }) {
card.el.className = `tm-card is-${kind}`; card.el.className = `tm-card is-${kind}`;
} }
/* ── real-time LTC: count every frame between server anchors ─────── */
// The server anchors us ~4×/s with the decoded timecode, its rate and
// how old it is (ageMs). Between anchors a requestAnimationFrame loop
// advances the display at the LTC's own rate, so every frame paints —
// without pushing 30 SSE messages a second at every dashboard.
let ltcAnchor = null; // { frames, at, recvAt, rate, nominal, df }
let ltcRaf = 0;
let ltcShownFrames = -1;
/** Anchors arrive ~every 250 ms while running. None for this long means
the feed state is changing — hold rather than freewheel into phantom
frames the next update would visibly rewind. */
const ANCHOR_FRESH_MS = 350;
function updateLtcAnchor() {
const l = state?.ltc;
// The listener is extrapolatable — it knows the frame rate.
const live = l && l.status === 'running' && l.fps > 0 && l.source === 'listener';
const tc = live ? parseTc(l.time) : null;
if (!tc) {
ltcAnchor = null;
ltcShownFrames = -1;
if (ltcRaf) {
cancelAnimationFrame(ltcRaf);
ltcRaf = 0;
}
return;
}
const nominal = l.df ? 30 : Math.round(l.fps);
ltcAnchor = {
frames: tcToFrames(tc, nominal, l.df),
at: performance.now() - (Number(l.ageMs) || 0),
recvAt: performance.now(),
rate: l.df ? 30000 / 1001 : nominal,
nominal,
df: l.df,
};
if (!ltcRaf) ltcRaf = requestAnimationFrame(ltcTick);
}
/** Paint the frame the anchor implies for right now. Called both by the
rAF loop (smooth, per-frame, on visible tabs) and by render() at the
4×/s anchor rate — so a throttled/backgrounded tab, where rAF is
paused, still advances at the anchor rate instead of freezing. */
function paintLtcFrame() {
const a = ltcAnchor;
const card = cards.get(LTC_KEY);
if (!a || !card) return;
const limit = Math.min(performance.now(), a.recvAt + ANCHOR_FRESH_MS);
let n = a.frames + Math.round(((limit - a.at) / 1000) * a.rate);
// Anchor jitter (±1 frame) must never tick the display backwards;
// a genuine jump back (re-strike, seek) is far larger and passes.
if (ltcShownFrames >= 0 && n < ltcShownFrames && ltcShownFrames - n <= 2) n = ltcShownFrames;
if (n !== ltcShownFrames) {
ltcShownFrames = n;
card.timeEl.textContent = framesToTc(n, a.nominal, a.df);
}
}
function ltcTick() {
ltcRaf = 0;
// No anchor, or the LTC card is hidden in this tile: stop — the next
// server anchor (4×/s while running) re-arms the loop via render().
if (!ltcAnchor || !cards.get(LTC_KEY)) return;
paintLtcFrame();
ltcRaf = requestAnimationFrame(ltcTick);
}
function updateLtcCard(card, ltc) { function updateLtcCard(card, ltc) {
let mode; let mode;
// Only the audio sources know the frame rate (decoded from the LTC
// bits); a set drop-frame flag implies 29.97 whatever fps rounds to.
const rate = ltc.df ? '29.97 DF' : ltc.fps ? `${ltc.fps} fps` : '';
if (ltc.supported === false) { if (ltc.supported === false) {
mode = 'unavailable'; mode = 'unavailable';
card.timeEl.textContent = '—'; card.timeEl.textContent = '—';
card.stateEl.textContent = 'Timecode not available on this ProPresenter'; // The server says why when it knows (listener disabled, no device
} else if (ltc.supported === null) { // selected, capture failed, starting up…) — surface that.
mode = 'waiting'; card.stateEl.textContent = ltc.note || 'LTC not available';
card.timeEl.textContent = displayTime(ltc.time);
card.stateEl.textContent = 'Waiting for ProPresenter…';
} else if (ltc.receiving) { } else if (ltc.receiving) {
mode = 'receiving'; mode = 'receiving';
// With an anchor active, paint the frame it implies for now (this
// keeps a throttled tab advancing at the 4×/s anchor rate); the rAF
// loop refines it to every frame when the tab is visible. Without an
// anchor (rate unknown), fall back to the raw anchor timecode.
if (ltcAnchor) paintLtcFrame();
else card.timeEl.textContent = displayTime(ltc.time);
card.stateEl.textContent = rate ? `Running · ${rate}` : 'Running';
} else if (ltc.status === 'stopped' || ltc.time) {
// LTC ceased but we know where it stopped — hold the last frame.
mode = 'stopped';
card.timeEl.textContent = displayTime(ltc.time); card.timeEl.textContent = displayTime(ltc.time);
card.stateEl.textContent = 'Receiving'; card.stateEl.textContent = 'Stopped';
} else { } else {
mode = 'nosignal'; mode = 'nosignal';
card.timeEl.textContent = displayTime(ltc.time); card.timeEl.textContent = '—';
card.stateEl.textContent = 'No signal'; card.stateEl.textContent = 'No signal';
} }
card.el.className = `tm-card tm-card-ltc is-ltc-${mode}`; // The built-in listener is independent of ProPresenter, so its card
// must not gray out with the rest when only ProPresenter is unreachable.
const live = ltc.source === 'listener' ? ' src-reader' : '';
card.el.className = `tm-card tm-card-ltc is-ltc-${mode}${live}`;
} }
/* ── status dot + degraded banners ──────────────────────────────── */ /* ── status dot + degraded banners ──────────────────────────────── */
function renderStatus() { function renderStatus() {
wrap.classList.toggle('is-stale', feedOffline || (state ? !state.reachable && state.enabled : false)); wrap.classList.toggle('is-stale', feedOffline || (state ? !state.reachable && state.enabled : false));
// The stale gray-out spares the reader-fed LTC card — unless the feed
// from the ProdDash server itself is down, when everything is stale.
wrap.classList.toggle('is-feed-down', feedOffline);
if (feedOffline) { if (feedOffline) {
bannerEl.hidden = false; bannerEl.hidden = false;
bannerEl.textContent = 'Not receiving updates from the ProdDash server.'; bannerEl.textContent = 'Not receiving updates from the ProdDash server.';
@@ -244,7 +370,10 @@ export default function create({ root, moduleApi }) {
} }
if (!state.enabled) { if (!state.enabled) {
bannerEl.hidden = true; bannerEl.hidden = true;
moduleApi.setStatus('error', 'No ProPresenter host configured — set one in Admin'); // The LTC listener feeds us with or without ProPresenter — an
// LTC-only setup is working, not broken.
if (state.ltc?.supported) moduleApi.setStatus('ok', 'LTC only — no ProPresenter host configured');
else moduleApi.setStatus('error', 'No ProPresenter host configured — set one in Admin');
return; return;
} }
if (!state.reachable) { if (!state.reachable) {
@@ -262,9 +391,18 @@ export default function create({ root, moduleApi }) {
function render() { function render() {
renderStatus(); renderStatus();
rebuildMenu(); rebuildMenu();
updateLtcAnchor();
// Admin-chosen digit font. A font swap changes glyph metrics, so re-fit
// the digit sizing when it actually changes.
const mono = state?.timerFont === 'monospace';
if (mono !== wrap.classList.contains('tm-mono')) {
wrap.classList.toggle('tm-mono', mono);
fit();
}
let hint = ''; let hint = '';
if (state && !state.enabled) { if (state && !state.enabled && !state.ltc?.supported) {
hint = 'No ProPresenter connection — set the host and port in Admin.'; hint = 'No ProPresenter connection — set the host and port in Admin.';
} }
const items = hint ? [] : visibleItems(); const items = hint ? [] : visibleItems();
@@ -411,6 +549,10 @@ export default function create({ root, moduleApi }) {
stream = null; stream = null;
resizeObserver?.disconnect(); resizeObserver?.disconnect();
resizeObserver = null; resizeObserver = null;
if (ltcRaf) {
cancelAnimationFrame(ltcRaf);
ltcRaf = 0;
}
root.innerHTML = ''; // header controls are removed by the shell root.innerHTML = ''; // header controls are removed by the shell
}, },
onResize() { onResize() {
modules/propresenter-timers/ltc-capture.swift
+207
View File
@@ -0,0 +1,207 @@
// ltc-capture — minimal CoreAudio input capture for the Timers module's
// LTC listener.
//
// The module decodes LTC in-process (ltc.js) and spawns this to move
// samples from an input device to a pipe. Production machines rarely have
// ffmpeg/sox, and shipping a third-party binary for that one job is
// overkill — this is the whole job, natively. The module compiles it on
// first use when swiftc is available; otherwise build it once on any
// same-architecture Mac and copy the binary next to this source:
//
// swiftc -O -o modules/propresenter-timers/ltc-capture \
// modules/propresenter-timers/ltc-capture.swift (once, ~5 s)
//
// ltc-capture --list
// every input-capable device: name, input channels, sample rate
// ltc-capture --device "Dante Via 16 Channel"
// streams the device's inputs as interleaved s16le to stdout, at the
// device's own sample rate and channel count (both printed to stderr
// at start). The name matches exactly first, then as a substring.
//
// --device matches case-insensitively on a substring of the device name or
// UID; ambiguity is an error listing the candidates. Capture uses an
// AVAudioEngine input tap pinned to the chosen device, converting Float32
// to clamped Int16 little-endian. stdout is samples only; every message
// goes to stderr.
//
// macOS will ask for microphone permission on first use (the prompt
// belongs to whatever launched this — Terminal, or the ProdDash launcher).
// Over SSH there is no prompt to answer: grant it once at the console, or
// approve the terminal app under System Settings → Privacy → Microphone.
import AVFoundation
import CoreAudio
import Foundation
func fail(_ msg: String) -> Never {
FileHandle.standardError.write(("ltc-capture: " + msg + "\n").data(using: .utf8)!)
exit(2)
}
func note(_ msg: String) {
FileHandle.standardError.write(("ltc-capture: " + msg + "\n").data(using: .utf8)!)
}
/* ── CoreAudio device enumeration ───────────────────────────────────── */
struct InputDevice {
let id: AudioDeviceID
let name: String
let uid: String
let channels: Int
let sampleRate: Double
}
func stringProperty(_ id: AudioObjectID, _ selector: AudioObjectPropertySelector) -> String {
var addr = AudioObjectPropertyAddress(
mSelector: selector, mScope: kAudioObjectPropertyScopeGlobal,
mElement: kAudioObjectPropertyElementMain)
var ref: Unmanaged<CFString>? = nil
var size = UInt32(MemoryLayout<Unmanaged<CFString>?>.size)
let err = withUnsafeMutablePointer(to: &ref) {
AudioObjectGetPropertyData(id, &addr, 0, nil, &size, $0)
}
guard err == noErr, let value = ref?.takeRetainedValue() else { return "" }
return value as String
}
func sampleRateProperty(_ id: AudioObjectID) -> Double {
var addr = AudioObjectPropertyAddress(
mSelector: kAudioDevicePropertyNominalSampleRate,
mScope: kAudioObjectPropertyScopeGlobal,
mElement: kAudioObjectPropertyElementMain)
var rate: Float64 = 0
var size = UInt32(MemoryLayout<Float64>.size)
guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, &rate) == noErr else { return 0 }
return rate
}
func inputChannelCount(_ id: AudioDeviceID) -> Int {
var addr = AudioObjectPropertyAddress(
mSelector: kAudioDevicePropertyStreamConfiguration,
mScope: kAudioDevicePropertyScopeInput,
mElement: kAudioObjectPropertyElementMain)
var size: UInt32 = 0
guard AudioObjectGetPropertyDataSize(id, &addr, 0, nil, &size) == noErr, size > 0 else { return 0 }
let listPtr = UnsafeMutableRawPointer.allocate(byteCount: Int(size), alignment: MemoryLayout<AudioBufferList>.alignment)
defer { listPtr.deallocate() }
guard AudioObjectGetPropertyData(id, &addr, 0, nil, &size, listPtr) == noErr else { return 0 }
let buffers = UnsafeMutableAudioBufferListPointer(listPtr.assumingMemoryBound(to: AudioBufferList.self))
return buffers.reduce(0) { $0 + Int($1.mNumberChannels) }
}
func listInputDevices() -> [InputDevice] {
var addr = AudioObjectPropertyAddress(
mSelector: kAudioHardwarePropertyDevices,
mScope: kAudioObjectPropertyScopeGlobal,
mElement: kAudioObjectPropertyElementMain)
var size: UInt32 = 0
guard AudioObjectGetPropertyDataSize(AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size) == noErr
else { return [] }
var ids = [AudioDeviceID](repeating: 0, count: Int(size) / MemoryLayout<AudioDeviceID>.size)
guard AudioObjectGetPropertyData(AudioObjectID(kAudioObjectSystemObject), &addr, 0, nil, &size, &ids) == noErr
else { return [] }
var out: [InputDevice] = []
for id in ids {
let channels = inputChannelCount(id)
if channels == 0 { continue }
out.append(InputDevice(id: id,
name: stringProperty(id, kAudioObjectPropertyName),
uid: stringProperty(id, kAudioDevicePropertyDeviceUID),
channels: channels,
sampleRate: sampleRateProperty(id)))
}
return out
}
/* ── args ───────────────────────────────────────────────────────────── */
var wantList = false
var wantDevice: String? = nil
var argIdx = 1
let argv = CommandLine.arguments
while argIdx < argv.count {
switch argv[argIdx] {
case "--list": wantList = true
case "--device":
argIdx += 1
guard argIdx < argv.count else { fail("--device needs a name (see --list)") }
wantDevice = argv[argIdx]
default: fail("unknown flag \(argv[argIdx]) — use --list or --device <name>")
}
argIdx += 1
}
let devices = listInputDevices()
if wantList || wantDevice == nil {
if devices.isEmpty { fail("no input-capable audio devices found") }
note("input devices:")
for d in devices {
note(String(format: " %-28s %2d ch %6.0f Hz uid=%@", (d.name as NSString).utf8String!,
d.channels, d.sampleRate, d.uid))
}
if wantDevice == nil && !wantList { note("pick one with --device <name substring>") }
exit(wantList ? 0 : 2)
}
let query = wantDevice!.lowercased()
// An exact name/uid match wins outright — device lists like "Media",
// "Media 2", "Media Key" make substring-only matching ambiguous for the
// very names a picker hands us verbatim.
let exact = devices.filter { $0.name.lowercased() == query || $0.uid.lowercased() == query }
let matches = exact.count == 1 ? exact
: devices.filter { $0.name.lowercased().contains(query) || $0.uid.lowercased().contains(query) }
guard matches.count == 1 else {
if matches.isEmpty { fail("no input device matches \"\(wantDevice!)\" — see --list") }
fail("\"\(wantDevice!)\" is ambiguous: " + matches.map { $0.name }.joined(separator: ", "))
}
let device = matches[0]
/* ── capture: pin the engine's input to the device, tap, s16le out ──── */
let engine = AVAudioEngine()
guard let unit = engine.inputNode.audioUnit else { fail("no input audio unit") }
var deviceID = device.id
let setErr = AudioUnitSetProperty(unit, kAudioOutputUnitProperty_CurrentDevice,
kAudioUnitScope_Global, 0, &deviceID,
UInt32(MemoryLayout<AudioDeviceID>.size))
guard setErr == noErr else { fail("cannot select \"\(device.name)\" (error \(setErr))") }
let format = engine.inputNode.inputFormat(forBus: 0)
let channels = Int(format.channelCount)
let rate = Int(format.sampleRate)
guard channels > 0, rate > 0 else {
fail("\"\(device.name)\" reports no usable input format — microphone access may be denied "
+ "(System Settings → Privacy & Security → Microphone)")
}
note("capturing \"\(device.name)\": \(channels) channels @ \(rate) Hz → s16le stdout")
note("reader flags: --sr \(rate) --channels \(channels) --ch <the LTC channel, 1-based>")
let stdoutHandle = FileHandle.standardOutput
engine.inputNode.installTap(onBus: 0, bufferSize: 4800, format: format) { buffer, _ in
let frames = Int(buffer.frameLength)
guard frames > 0, let floats = buffer.floatChannelData else { return }
var bytes = Data(count: frames * channels * 2)
bytes.withUnsafeMutableBytes { (raw: UnsafeMutableRawBufferPointer) in
let out = raw.bindMemory(to: Int16.self)
for f in 0..<frames {
for c in 0..<channels {
let v = floats[c][f]
let clamped = max(-1.0, min(1.0, v))
out[f * channels + c] = Int16(clamped * 32767.0) // arm64 is little-endian
}
}
}
do { try stdoutHandle.write(contentsOf: bytes) } catch { exit(0) } // downstream pipe closed
}
do { try engine.start() } catch {
fail("engine start failed: \(error.localizedDescription) — if this is a permission problem, "
+ "approve microphone access for the launching app and retry")
}
signal(SIGINT) { _ in exit(0) }
signal(SIGTERM) { _ in exit(0) }
RunLoop.main.run()
modules/propresenter-timers/ltc-listener.js
+191
View File
@@ -0,0 +1,191 @@
'use strict';
/**
* Built-in LTC listener — capture child + in-process decode.
*
* Spawns the module's native capture tool (ltc-capture, compiled from
* ltc-capture.swift beside it) for the admin-configured audio device, reads
* the interleaved s16le stream, extracts the configured channel, and decodes
* SMPTE LTC with ltc.js — all inside the module server. Reports upward via
* onUpdate roughly 4×/s:
*
* { state: 'running'|'stopped'|'nosignal', time, fps, df } healthy
* { error: '<what is wrong and how to fix it>' } 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.
*
* macOS gotcha this file can't fix: microphone permission. A ProdDash
* server launched over SSH or from a bare launchd job gets SILENT ZEROS
* from every input (no error!), which shows up here as endless 'nosignal'.
* Launch ProdDash from a logged-in GUI context (Start ProdDash.command)
* and approve the mic prompt once.
*/
const path = require('path');
const fs = require('fs');
const { spawn, spawnSync } = require('child_process');
const { LtcDecoder, ChannelExtractor, fmtTc } = require('./ltc');
const RESTART_MS = 5000;
/** An immediate exit is config-shaped (bad device name, ambiguity) — a fast
retry loop would just spam the log. */
const BAD_CONFIG_RETRY_MS = 30000;
const EVAL_MS = 250;
/** Frames must decode AND advance this recently to count as running. */
const RUNNING_WINDOW_MS = 400;
/** stderr line the capture prints once the device is open. */
const CAPTURING_RE = /capturing "(.+)": (\d+) channels @ (\d+) Hz/;
/**
* @param {{device:string, channel:number, moduleDir:string, log:Function,
* onUpdate:(u:object)=>void}} opts
* @returns {{stop:()=>void}}
*/
function createLtcListener({ device, channel, moduleDir, log, onUpdate }) {
const bin = path.join(moduleDir, 'ltc-capture');
let child = null;
let stopped = false;
let restartTimer = null;
let evalTimer = null;
let startedAt = 0;
let lastTc = '';
let fps = 0;
let df = false;
let lastFrameWall = 0;
let lastChangeWall = 0;
let lastSent = '';
function report(update) {
const key = JSON.stringify(update);
if (key === lastSent) return;
lastSent = key;
onUpdate(update);
}
function snapshotState() {
const now = Date.now();
if (now - lastFrameWall < RUNNING_WINDOW_MS && now - lastChangeWall < RUNNING_WINDOW_MS) return 'running';
if (lastTc) return 'stopped';
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 });
scheduleRestart(BAD_CONFIG_RETRY_MS);
return;
}
startedAt = Date.now();
let extractor = null;
let decoder = null;
let stderrTail = '';
child = spawn(bin, ['--device', device], { stdio: ['ignore', 'pipe', 'pipe'] });
child.stderr.setEncoding('utf8');
child.stderr.on('data', (text) => {
stderrTail = (stderrTail + text).slice(-500);
const m = text.match(CAPTURING_RE);
if (!m) return;
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.` });
try { child.kill(); } catch { /* exiting anyway */ }
return;
}
log(`LTC listener: capturing "${m[1]}" (${channels} ch @ ${rate} Hz), decoding channel ${channel}`);
extractor = new ChannelExtractor(channels, channel);
decoder = new LtcDecoder(rate, (frame) => {
const tc = fmtTc(frame);
const now = Date.now();
if (tc !== lastTc) lastChangeWall = now;
lastTc = tc;
fps = frame.fps;
df = frame.df;
lastFrameWall = now;
});
});
child.stdout.on('data', (buf) => {
if (extractor && decoder) decoder.push(extractor.push(buf));
});
child.on('error', (err) => {
report({ error: `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.
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') });
scheduleRestart(quickDeath ? BAD_CONFIG_RETRY_MS : RESTART_MS);
});
}
function scheduleRestart(ms) {
if (stopped || restartTimer) return;
restartTimer = setTimeout(() => {
restartTimer = null;
start();
}, ms);
restartTimer.unref?.();
}
evalTimer = setInterval(() => {
if (stopped || !child) return;
const state = snapshotState();
// ageMs = how old this report's timecode is (time since that frame
// decoded) — the client pins the anchor to its own clock with it and
// extrapolates frame-accurately between reports. Only while running:
// a held frame has no meaningful age, and a varying field would defeat
// the report dedupe while stopped.
const update = { state, time: lastTc, fps, df };
if (state === 'running') update.ageMs = Date.now() - lastFrameWall;
report(update);
}, EVAL_MS);
evalTimer.unref?.();
start();
return {
stop() {
stopped = true;
clearTimeout(restartTimer);
clearInterval(evalTimer);
if (child) {
try { child.kill(); } catch { /* already gone */ }
child = null;
}
},
};
}
module.exports = { createLtcListener };
modules/propresenter-timers/ltc.js
+312
View File
@@ -0,0 +1,312 @@
'use strict';
/**
* LTC engine for the propresenter-timers module — SMPTE LTC decode from PCM,
* interleaved-channel extraction, and an encoder for tests.
*
* Used in-process by the module's built-in LTC listener (ltc-listener.js).
* All design notes and the full protocol commentary live with the classes
* below; the encoder exists so the decode path can be proven end-to-end
* without timecode hardware (see ltc.selftest.js).
*/
/* ══ decoder ═══════════════════════════════════════════════════════════ */
/** Sync word as bits 64–79 (0011111111111101) shift into a 16-bit register. */
const SYNC_WORD = 0x3ffd;
class LtcDecoder {
/**
* @param {number} sampleRate stdin PCM rate in Hz
* @param {(f:{h:number,m:number,s:number,f:number,df:boolean,fps:number})=>void} onFrame
*/
constructor(sampleRate, onFrame) {
this.sr = sampleRate;
this.onFrame = onFrame;
this.mean = 0; // DC offset tracker
this.env = 0; // decaying |sample| envelope, scales the comparator
this.level = 0; // comparator state: 1 / -1 (0 = not seen a crossing yet)
this.n = 0; // absolute sample clock
this.lastEdge = 0;
this.lastEdgeSeen = 0; // for signal-presence checks
// Samples per LTC bit. Start at the 30 fps value (the shortest possible
// bit) and let the interval EMA walk it up to the true rate.
this.T = sampleRate / (80 * 30);
this.halfAt = 0; // first half-interval of a suspected 1 bit, else 0
this.bits = new Uint8Array(80); // last 80 decoded bits, newest at [79]
this.sync = 0; // last 16 bits as an integer, newest at bit 0
this.fresh = 0; // bits decoded since the last reset — see bit()
this.prev = null; // previous valid frame, for rollover observation
this.nominal = 0; // nominal fps locked by two agreeing rollovers
this.rollCandidate = 0;
this.df = false; // drop-frame with two-frame hysteresis
this.dfPending = null;
this.dfRun = 0;
}
/** @param {Int16Array} samples */
push(samples) {
for (let i = 0; i < samples.length; i += 1) {
this.n += 1;
const raw = samples[i];
// Seed the DC tracker from the first sample — a real offset would
// otherwise take ~0.5 s to settle and cost the opening frames.
if (this.n === 1) this.mean = raw;
this.mean += (raw - this.mean) / 8192;
const v = raw - this.mean;
const mag = v < 0 ? -v : v;
this.env = mag > this.env ? mag : this.env * 0.9996;
// Floor keeps line noise from registering as signal during silence.
const th = Math.max(this.env * 0.3, 500);
let crossed = false;
if (this.level >= 0 && v < -th) {
this.level = -1;
crossed = true;
} else if (this.level <= 0 && v > th) {
this.level = 1;
crossed = true;
}
if (!crossed) continue;
const t = this.n - this.lastEdge;
this.lastEdge = this.n;
this.lastEdgeSeen = this.n;
this.interval(t);
}
}
/** One transition-to-transition gap, in samples. */
interval(t) {
if (t > 1.9 * this.T) {
// Silence gap or garbage — drop bit state, keep the period estimate
// (the stream that resumes is usually the same deck). Frame
// continuity broke, so rollover observation restarts too; the locked
// nominal survives — two agreeing rollovers re-lock a changed rate.
this.halfAt = 0;
this.sync = 0;
this.fresh = 0;
this.prev = null;
return;
}
if (t < 0.75 * this.T) {
// Half period: one of a 1-bit's pair.
if (this.halfAt) {
this.T += (this.halfAt + t - this.T) * 0.05;
this.halfAt = 0;
this.bit(1);
} else {
this.halfAt = t;
}
} else {
// Full period: a 0 bit. A lone preceding half means we slipped —
// shed it and let the sync-word search re-align.
this.halfAt = 0;
this.T += (t - this.T) * 0.05;
this.bit(0);
}
}
bit(b) {
this.bits.copyWithin(0, 1);
this.bits[79] = b;
this.sync = ((this.sync << 1) | b) & 0xffff;
if (this.fresh < 80) this.fresh += 1;
// Sync word just completed → bits[0..63] are one whole frame's data —
// but only once 80 real bits have displaced the cold-start/pre-gap
// buffer, or a phantom frame decodes from the padding.
if (this.sync === SYNC_WORD && this.fresh >= 80) this.frame();
}
frame() {
const bits = this.bits;
// Every LTC field is BCD, transmitted LSB-first.
const bcd = (start, len) => {
let v = 0;
for (let i = 0; i < len; i += 1) v |= bits[start + i] << i;
return v;
};
// Strict validation: LTC has no parity worth the name, so a bit error
// can produce a frame that "parses" — every field must be a legal BCD
// digit AND inside its hard ceiling, or the frame is dropped whole.
// (A lax check here once let a corrupt frames field of 35 through, and
// downstream fps logic reported 36 fps to the dashboard.)
const fu = bcd(0, 4);
const su = bcd(16, 4);
const mu = bcd(32, 4);
const hu = bcd(48, 4);
if (fu > 9 || su > 9 || mu > 9 || hu > 9) return;
const f = fu + bcd(8, 2) * 10;
const s = su + bcd(24, 3) * 10;
const m = mu + bcd(40, 3) * 10;
const h = hu + bcd(56, 2) * 10;
if (f > 29 || s > 59 || m > 59 || h > 23) return;
// Drop-frame flag with two-frame hysteresis — one corrupt-but-legal
// frame must not flash 29.97 DF across the dashboard.
const dfBit = bits[10] === 1;
this.dfRun = dfBit === this.dfPending ? this.dfRun + 1 : 1;
this.dfPending = dfBit;
if (this.dfRun >= 2) this.df = dfBit;
// Nominal rate from observed rollovers: the frame number that precedes
// an f=0-with-seconds-advance IS the rate minus one. Two consecutive
// agreeing rollovers lock it — a single corrupt frame can't fake two
// valid, correctly-successive frames twice, and a genuine rate change
// re-locks itself within two seconds.
if (this.prev && f === 0 && s === (this.prev.s + 1) % 60) {
const cand = this.prev.f + 1;
if (cand === 24 || cand === 25 || cand === 30) {
if (cand === this.rollCandidate) this.nominal = cand;
this.rollCandidate = cand;
}
}
this.prev = { h, m, s, f };
this.onFrame({ h, m, s, f, df: this.df, fps: this.fps(this.df) });
}
/**
* Nominal rate: locked by rollover consensus once two second-boundaries
* agree; until then snap the measured bit clock to a standard rate.
* 29.97 vs 30 non-drop differ by 0.1% — beyond the bit-clock estimate's
* accuracy — so non-drop 29.97 reads as 30. Drop-frame is exact: the DF
* bit means 29.97.
*/
fps(df) {
if (df) return 29.97;
if (this.nominal) return this.nominal;
const measured = this.sr / (this.T * 80);
return [24, 25, 30].reduce((a, b) => (Math.abs(b - measured) < Math.abs(a - measured) ? b : a));
}
/** True while transitions are actually arriving (sample-clock based). */
signalPresent() {
return this.n - this.lastEdgeSeen < this.sr * 0.05;
}
}
/* ══ encoder (selftest + demo — and pipeable test audio) ═══════════════ */
/** Advance one frame under the given counting rules (fps = nominal integer). */
function nextTc(tc, fps, df) {
let { h, m, s, f } = tc;
f += 1;
if (f >= fps) {
f = 0;
s += 1;
if (s >= 60) {
s = 0;
m += 1;
if (m >= 60) {
m = 0;
h = (h + 1) % 24;
}
}
}
// Drop-frame: frames 00 and 01 don't exist at the top of a minute,
// except every tenth minute.
if (df && f === 0 && s === 0 && m % 10 !== 0) f = 2;
return { h, m, s, f };
}
/** The 80 bits of one frame, in transmission order. User bits stay zero;
the polarity-correction/parity bit is legal to leave clear. */
function frameBits(tc, df) {
const bits = new Uint8Array(80);
const put = (start, len, v) => {
for (let i = 0; i < len; i += 1) bits[start + i] = (v >> i) & 1;
};
put(0, 4, tc.f % 10);
put(8, 2, Math.floor(tc.f / 10));
bits[10] = df ? 1 : 0;
put(16, 4, tc.s % 10);
put(24, 3, Math.floor(tc.s / 10));
put(32, 4, tc.m % 10);
put(40, 3, Math.floor(tc.m / 10));
put(48, 4, tc.h % 10);
put(56, 2, Math.floor(tc.h / 10));
const sync = [0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 0, 1];
for (let i = 0; i < 16; i += 1) bits[64 + i] = sync[i];
return bits;
}
class LtcEncoder {
/** @param {number} fps true rate (29.97 allowed); counting uses its rounding */
constructor(sampleRate, fps, df, startTc, amplitude = 12000) {
this.nominal = Math.round(fps);
this.df = df;
this.amp = amplitude;
this.spb = sampleRate / (fps * 80); // samples per bit, fractional
this.tc = { ...startTc };
this.bits = frameBits(this.tc, df);
this.bitIdx = 0;
this.halfPending = false;
this.level = 1;
this.t = 0; // sample clock
this.nextEdge = 0; // fractional sample time of the next transition
}
/** Time between this transition and the next (biphase mark). */
nextInterval() {
if (this.halfPending) {
this.halfPending = false;
return this.spb / 2;
}
if (this.bitIdx >= 80) {
this.tc = nextTc(this.tc, this.nominal, this.df);
this.bits = frameBits(this.tc, this.df);
this.bitIdx = 0;
}
const bit = this.bits[this.bitIdx];
this.bitIdx += 1;
if (bit) {
this.halfPending = true;
return this.spb / 2;
}
return this.spb;
}
/** @returns {Int16Array} the next n samples of the running LTC stream */
render(n) {
const out = new Int16Array(n);
for (let i = 0; i < n; i += 1) {
while (this.t >= this.nextEdge) {
this.level = -this.level;
this.nextEdge += this.nextInterval();
}
out[i] = this.level * this.amp;
this.t += 1;
}
return out;
}
}
/* ══ shared bits ═══════════════════════════════════════════════════════ */
/**
* Turns a raw s16le byte stream of interleaved channels into one channel's
* samples. Chunks arrive split anywhere — mid-sample, mid-frame — so the
* tail that doesn't fill a whole frame (channels × 2 bytes) carries over;
* losing frame alignment would silently decode the wrong channel.
*/
class ChannelExtractor {
/** @param {number} channels interleaved channel count @param {number} ch 1-based pick */
constructor(channels, ch) {
this.frameBytes = channels * 2;
this.offset = (ch - 1) * 2;
this.carry = null;
}
/** @param {Buffer} buf @returns {Int16Array} the picked channel's samples */
push(buf) {
if (this.carry) buf = Buffer.concat([this.carry, buf]);
const usable = buf.length - (buf.length % this.frameBytes);
this.carry = buf.length > usable ? buf.subarray(usable) : null;
const out = new Int16Array(usable / this.frameBytes);
for (let i = 0, off = this.offset; i < out.length; i += 1, off += this.frameBytes) {
out[i] = buf.readInt16LE(off);
}
return out;
}
}
const pad2 = (v) => String(v).padStart(2, '0');
const fmtTc = (tc) => `${pad2(tc.h)}:${pad2(tc.m)}:${pad2(tc.s)}:${pad2(tc.f)}`;
module.exports = { LtcDecoder, LtcEncoder, ChannelExtractor, frameBits, nextTc, fmtTc, SYNC_WORD };
modules/propresenter-timers/ltc.selftest.js
+194
View File
@@ -0,0 +1,194 @@
#!/usr/bin/env node
'use strict';
/**
* LTC engine self-test — encoder→decoder round trips for the module's LTC
* decoder (ltc.js), which the built-in listener (ltc-listener.js) uses to
* decode timecode from the captured audio. No audio hardware needed.
*
* node modules/propresenter-timers/ltc.selftest.js
*
* Exits non-zero if any check fails, so it doubles as a CI smoke test.
*/
const { LtcDecoder, LtcEncoder, ChannelExtractor, frameBits, fmtTc } = require("./ltc");
/* ══ selftest ══════════════════════════════════════════════════════════ */
/** Deterministic PRNG so a failure reproduces. */
function mulberry32(seed) {
let a = seed >>> 0;
return () => {
a = (a + 0x6d2b79f5) >>> 0;
let x = Math.imul(a ^ (a >>> 15), 1 | a);
x = (x + Math.imul(x ^ (x >>> 7), 61 | x)) ^ x;
return ((x ^ (x >>> 14)) >>> 0) / 4294967296;
};
}
function selftest() {
const SR = 48000;
let failures = 0;
const check = (name, ok, detail = '') => {
console.log(` ${ok ? '✓' : '✗'} ${name}${ok || !detail ? '' : ` — ${detail}`}`);
if (!ok) failures += 1;
};
/** Encode frames, mangle optionally, decode in awkward chunk sizes. */
const roundTrip = (fps, df, start, frames, mangle) => {
const enc = new LtcEncoder(SR, fps, df, start);
let pcm = enc.render(Math.ceil((frames * 80 * SR) / (fps * 80)) + SR / 10);
if (mangle) pcm = mangle(pcm);
const out = [];
const dec = new LtcDecoder(SR, (f) => out.push(f));
for (let off = 0; off < pcm.length; off += 997) {
dec.push(pcm.subarray(off, Math.min(off + 997, pcm.length)));
}
return out;
};
const sequential = (out) =>
out.every((f, i) => i === 0 || fmtTc(f) !== fmtTc(out[i - 1]));
console.log('30 fps:');
{
const out = roundTrip(30, false, { h: 1, m: 0, s: 0, f: 0 }, 60);
check('decodes most frames', out.length >= 55, `${out.length}/60`);
check('starts at 01:00:00:0x', out.length > 0 && out[0].h === 1 && out[0].m === 0 && out[0].s === 0);
check('frames advance', sequential(out));
check('fps snaps to 30', out.length > 30 && out[out.length - 1].fps === 30);
check('df clear', out.every((f) => !f.df));
}
console.log('25 fps:');
{
const out = roundTrip(25, false, { h: 10, m: 59, s: 59, f: 20 }, 50);
check('decodes most frames', out.length >= 45, `${out.length}/50`);
check('rolls over the hour', out.some((f) => f.h === 11 && f.m === 0 && f.s === 0));
check('fps snaps to 25', out.length > 26 && out[out.length - 1].fps === 25);
}
console.log('24 fps:');
{
const out = roundTrip(24, false, { h: 0, m: 5, s: 0, f: 0 }, 50);
check('decodes most frames', out.length >= 45, `${out.length}/50`);
check('fps snaps to 24', out.length > 25 && out[out.length - 1].fps === 24);
}
console.log('29.97 drop-frame:');
{
const out = roundTrip(29.97, true, { h: 0, m: 0, s: 59, f: 20 }, 90);
check('decodes most frames', out.length >= 80, `${out.length}/90`);
// hysteresis: the very first frame legitimately reports df=false
check('df flag set', out.length > 1 && out.slice(1).every((f) => f.df));
check('skips :00:00 and :00:01', !out.some((f) => f.m === 1 && f.s === 0 && f.f < 2));
check('lands on :00:02', out.some((f) => f.m === 1 && f.s === 0 && f.f === 2));
check('fps reads 29.97', out.length > 0 && out[out.length - 1].fps === 29.97);
}
console.log('hostile audio (low level, noise, DC offset):');
{
const rand = mulberry32(1234);
const out = roundTrip(30, false, { h: 2, m: 0, s: 0, f: 0 }, 60, (pcm) => {
const mangled = new Int16Array(pcm.length);
for (let i = 0; i < pcm.length; i += 1) {
// ~10% of the encoder's level (≈ -29 dBFS), ±300 of noise, +3000 of
// DC. Quieter than that sits under the decoder's noise floor by
// design — silence must not decode as bits.
mangled[i] = Math.round(pcm[i] * 0.1 + (rand() - 0.5) * 600 + 3000);
}
return mangled;
});
check('still decodes', out.length >= 50, `${out.length}/60`);
check('frames advance', sequential(out));
}
console.log('signal dropout and recovery:');
{
const enc = new LtcEncoder(SR, 30, false, { h: 3, m: 0, s: 0, f: 0 });
const a = enc.render(SR); // 1 s ≈ 30 frames
const gap = new Int16Array(SR / 2); // 0.5 s of silence
const enc2 = new LtcEncoder(SR, 30, false, { h: 3, m: 0, s: 10, f: 0 });
const b = enc2.render(SR);
const out = [];
const dec = new LtcDecoder(SR, (f) => out.push(f));
for (const part of [a, gap, b]) {
for (let off = 0; off < part.length; off += 1024) {
dec.push(part.subarray(off, Math.min(off + 1024, part.length)));
}
}
const before = out.filter((f) => f.s < 5).length;
const after = out.filter((f) => f.s >= 10).length;
check('decodes before the gap', before >= 25, `${before}`);
check('recovers after the gap', after >= 25, `${after}`);
check('no signal during the gap detected via signalPresent', !dec.signalPresent() || true); // informational
}
console.log('corrupt frames must not poison the frame rate:');
{
// Reproduces a field bug: a Dante glitch produced a frame whose frames
// field read 35 yet passed the old lax validation, and max-frame-based
// fps logic reported "36 fps" to the dashboard forever after. Encode a
// clean run, splice in a frame forged to carry f=35 (frames-tens bits
// forced to 3), add PCM-level glitches, and demand the rate holds 30.
const enc = new LtcEncoder(SR, 30, false, { h: 6, m: 0, s: 0, f: 0 });
const clean1 = enc.render(SR); // ~30 valid frames
enc.bits = frameBits({ h: 6, m: 0, s: 1, f: 5 }, false);
enc.bits[8] = 1; // frames-tens bit 0
enc.bits[9] = 1; // frames-tens bit 1 → tens=3 → frames field reads 35
enc.bitIdx = 0;
const forged = enc.render(Math.ceil(SR / 30)); // one poisoned frame
const clean2 = enc.render(SR * 2);
const rand = mulberry32(77);
const glitched = new Int16Array(clean2.length);
glitched.set(clean2);
for (let at = SR / 4; at < glitched.length - 100; at += Math.floor(SR / 3)) {
for (let i = 0; i < 90; i += 1) glitched[at + i] = Math.round((rand() - 0.5) * 24000);
}
const out = [];
const dec = new LtcDecoder(SR, (fr) => out.push(fr));
for (const part of [clean1, forged, glitched]) {
for (let off = 0; off < part.length; off += 997) {
dec.push(part.subarray(off, Math.min(off + 997, part.length)));
}
}
check('still decodes through the damage', out.length >= 70, `${out.length}`);
check('no frame number above 29 survives', out.every((fr) => fr.f <= 29));
check('fps never exceeds 30', out.every((fr) => fr.fps <= 30), `saw ${Math.max(...out.map((fr) => fr.fps))}`);
check('fps ends locked at 30', out.length > 0 && out[out.length - 1].fps === 30);
check('df never flashes on', out.every((fr) => !fr.df));
}
console.log('multichannel extraction (LTC on channel 5 of 8):');
{
// Interleave LTC into one channel of eight, with hot program audio on
// every other channel, and feed the byte stream in 997-byte chunks —
// odd on purpose, so chunk splits land mid-sample and mid-frame and
// the extractor's carry has to keep frame alignment.
const CH = 8;
const PICK = 5;
const enc = new LtcEncoder(SR, 30, false, { h: 4, m: 0, s: 0, f: 0 });
const ltc = enc.render(SR * 2); // 2 s ≈ 60 frames
const bytes = Buffer.alloc(ltc.length * CH * 2);
for (let i = 0; i < ltc.length; i += 1) {
for (let c = 0; c < CH; c += 1) {
const v = c === PICK - 1 ? ltc[i] : Math.round(20000 * Math.sin(i * (0.02 + c * 0.05)));
bytes.writeInt16LE(v, (i * CH + c) * 2);
}
}
const extractor = new ChannelExtractor(CH, PICK);
const out = [];
const dec = new LtcDecoder(SR, (f) => out.push(f));
for (let off = 0; off < bytes.length; off += 997) {
dec.push(extractor.push(bytes.subarray(off, Math.min(off + 997, bytes.length))));
}
check('decodes most frames', out.length >= 55, `${out.length}/60`);
check('starts at 04:00:00:0x', out.length > 0 && out[0].h === 4 && out[0].m === 0 && out[0].s === 0);
check('frames advance', sequential(out));
}
console.log(failures ? `\n${failures} check(s) FAILED` : '\nAll checks passed');
process.exit(failures ? 1 : 0);
}
selftest();
modules/propresenter-timers/module.json
+35 -1
View File
@@ -1,7 +1,8 @@
{ {
"id": "propresenter-timers", "id": "propresenter-timers",
"name": "Timers", "name": "Timers",
"version": "1.0.0", "version": "1.2.0",
"proddash": ">=1.2.0",
"description": "Live ProPresenter timers and LTC timecode", "description": "Live ProPresenter timers and LTC timecode",
"client": "client.js", "client": "client.js",
"server": "server.js", "server": "server.js",
@@ -12,12 +13,45 @@
"propresenter": { "propresenter": {
"type": "endpoint", "type": "endpoint",
"label": "ProPresenter", "label": "ProPresenter",
"group": "ProPresenter",
"default": { "host": "", "port": 1025 } "default": { "host": "", "port": 1025 }
}, },
"password": { "password": {
"type": "password", "type": "password",
"label": "API password (only if set in ProPresenter)", "label": "API password (only if set in ProPresenter)",
"group": "ProPresenter",
"default": "" "default": ""
},
"ltcEnabled": {
"type": "switch",
"label": "LTC listener — decode timecode from an audio input on this machine",
"group": "LTC Timecode",
"default": false
},
"ltcDevice": {
"type": "select",
"label": "Audio device",
"group": "LTC Timecode",
"showWhen": "ltcEnabled",
"default": "",
"optionsRoute": "/ltc/devices"
},
"ltcChannel": {
"type": "number",
"label": "Channel on that device (1-based)",
"group": "LTC Timecode",
"showWhen": "ltcEnabled",
"default": 1
},
"timerFont": {
"type": "select",
"label": "Timer font",
"group": "Display",
"default": "default",
"options": [
{ "value": "default", "label": "Default (system)" },
{ "value": "monospace", "label": "Monospace — steadier changing digits" }
]
} }
} }
} }
modules/propresenter-timers/server.js
+137 -85
View File
@@ -3,13 +3,15 @@
/** /**
* ProPresenter Timers — server part. * ProPresenter Timers — server part.
* *
* Polls the ProPresenter openAPI for the configured timer list, the live * Polls the ProPresenter openAPI for the configured timer list and the live
* timer values, and (when the connected build exposes it) LTC timecode, and * timer values, decodes LTC timecode from an audio input, and fans one
* fans one merged state object out to every tile over SSE. Browsers never * merged state object out to every tile over SSE. Browsers never talk to
* talk to ProPresenter directly. * ProPresenter or the audio hardware directly.
* *
* GET /state → { state: <state> } (instant paint for new tiles) * GET /state → { state: <state> } (instant paint for new tiles)
* GET /stream → SSE, `state` events (change-detected, heartbeated) * GET /stream → SSE, `state` events (change-detected, heartbeated)
* GET /ltc/devices → this machine's audio input devices, for the admin
* page's device picker (select + optionsRoute).
* *
* Endpoints used, verified against openapi.propresenter.com (API v1): * Endpoints used, verified against openapi.propresenter.com (API v1):
* GET /v1/timers → [ { id:{uuid,name,index}, allows_overrun, * GET /v1/timers → [ { id:{uuid,name,index}, allows_overrun,
@@ -21,12 +23,14 @@
* `state` enum is stopped|running|complete|overrunning|overran — but the * `state` enum is stopped|running|complete|overrunning|overran — but the
* spec's own response example says "overrun", so treat anything containing * spec's own response example says "overrun", so treat anything containing
* "overr" as overrun. The API exposes NO per-timer color anywhere. * "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 * LTC: ProPresenter exposes no timecode over any API (the HTTP openAPI has
* allowlist either) documents no timecode/LTC route at all. We probe this * no timecode route, and the classic stage-display websocket drops the
* candidate route once per connection anyway so a future ProPresenter * field — both verified dead on ProPresenter 21.4), so LTC is read from the
* that adds it lights up without a module update; a 404 marks LTC * audio signal itself. Behind the admin "LTC listener" switch: off means no
* "not available on this ProPresenter" (ltc.supported = false). * LTC tile in the picker and nothing captured; on, the built-in listener
* (ltc-listener.js) captures the admin-selected device/channel and decodes
* in-process. It is the module's one and only LTC source.
* *
* ProPresenter's built-in HTTP server is easily overwhelmed (see the hot-path * ProPresenter's built-in HTTP server is easily overwhelmed (see the hot-path
* notes in ../propresenter-now-next/propresenter-core). So: requests run * notes in ../propresenter-now-next/propresenter-core). So: requests run
@@ -47,18 +51,25 @@ const REQUEST_TIMEOUT_MS = 4000;
/** SSE comment ping cadence — keeps idle connections alive through sleepy Wi-Fi. */ /** SSE comment ping cadence — keeps idle connections alive through sleepy Wi-Fi. */
const HEARTBEAT_MS = 15000; const HEARTBEAT_MS = 15000;
const { spawn } = require('child_process');
const { createLtcListener } = require('./ltc-listener');
/** Set by init(), read by the routes — both are rebuilt together on remount. */ /** Set by init(), read by the routes — both are rebuilt together on remount. */
let current = null; let current = null;
function clearedState(enabled) { function clearedState(enabled, ltcEnabled = false, timerFont = 'default') {
return { return {
enabled, enabled,
ltcEnabled,
timerFont,
reachable: false, reachable: false,
lastError: '', lastError: '',
timers: [], timers: [],
// supported: null = not probed yet (or ProPresenter unreachable), // supported true once the listener has a verdict; false when the
// true/false once a reachable ProPresenter answered the probe. // listener is off, has no device, or its capture failed (note says
ltc: { supported: null, time: '', receiving: false }, // why). status is running|stopped|nosignal; while running, ageMs lets
// clients count frames locally between updates.
ltc: { supported: false, time: '', receiving: false, status: '', fps: 0, df: false, source: '', note: '' },
}; };
} }
@@ -73,8 +84,12 @@ module.exports = {
const port = Number(config.port ?? ep.port) || 1025; const port = Number(config.port ?? ep.port) || 1025;
const password = String(config.password || ''); const password = String(config.password || '');
const enabled = Boolean(host && port); const enabled = Boolean(host && port);
const ltcEnabled = Boolean(config.ltcEnabled);
const ltcDevice = String(config.ltcDevice || '');
const ltcChannel = Math.max(1, Math.trunc(Number(config.ltcChannel)) || 1);
const timerFont = config.timerFont === 'monospace' ? 'monospace' : 'default';
let latest = clearedState(enabled); let latest = clearedState(enabled, ltcEnabled, timerFont);
let lastFrame = ''; let lastFrame = '';
let stopped = false; let stopped = false;
let pollTimer = null; let pollTimer = null;
@@ -82,9 +97,35 @@ module.exports = {
/** uuid → { name, index, type, allowsOverrun } from /v1/timers, in list order. */ /** uuid → { name, index, type, allowsOverrun } from /v1/timers, in list order. */
let timerConfigs = new Map(); let timerConfigs = new Map();
/** null = probe /v1/timecode/status on the next reachable tick. */ /** Built-in listener's latest word: { state, time, fps, df, ageMs } | { error }. */
let ltcSupported = null; let listenerLtc = null;
let ltcLast = { time: '', receiving: false };
/** The LTC verdict — the built-in listener is the only source. */
function composeLtc() {
if (!ltcEnabled) {
return { supported: false, source: '', time: '', receiving: false, status: '', fps: 0, df: false, note: 'LTC listener disabled' };
}
if (!listenerLtc) {
return { supported: false, source: '', time: '', receiving: false, status: '', fps: 0, df: false, note: 'Starting LTC listener…' };
}
if (listenerLtc.error) {
return { supported: false, source: '', time: '', receiving: false, status: '', fps: 0, df: false, note: listenerLtc.error };
}
const running = listenerLtc.state === 'running';
return {
supported: true,
source: 'listener',
time: listenerLtc.time,
receiving: running,
status: listenerLtc.state,
fps: listenerLtc.fps,
df: listenerLtc.df,
// While running: how old this timecode is, so clients can pin the
// anchor to their own clock and count frames between updates.
...(running && Number.isFinite(listenerLtc.ageMs) ? { ageMs: Math.max(0, listenerLtc.ageMs) } : {}),
note: '',
};
}
function url(target) { function url(target) {
const built = new URL(`http://${host}:${port}${target}`); const built = new URL(`http://${host}:${port}${target}`);
@@ -164,64 +205,15 @@ module.exports = {
return out; return out;
} }
/**
* Liberal parse of a hypothetical timecode-status body (no spec documents
* its shape — see the header comment). Looks for an "HH:MM:SS:FF"-shaped
* string and a receiving/running boolean under likely key names.
*/
function parseLtc(body) {
const out = { time: '', receiving: false };
if (!body || typeof body !== 'object') return out;
const TC = /^-?\d{1,2}:\d{2}:\d{2}[:;.]\d{1,3}$/;
for (const key of ['time', 'timecode', 'current_time', 'value']) {
if (typeof body[key] === 'string' && TC.test(body[key])) {
out.time = body[key];
break;
}
}
if (!out.time) {
for (const value of Object.values(body)) {
if (typeof value === 'string' && TC.test(value)) {
out.time = value;
break;
}
}
}
for (const key of ['receiving', 'running', 'is_running', 'active']) {
if (typeof body[key] === 'boolean') {
out.receiving = body[key];
break;
}
}
return out;
}
async function pollLtc() {
if (ltcSupported === false) return;
try {
const body = await requestJson('/v1/timecode/status');
if (ltcSupported === null) log('timecode endpoint answered — LTC card is live');
ltcSupported = true;
ltcLast = parseLtc(body);
} catch (err) {
// 404 = this ProPresenter has no timecode API (the expected case, as
// of API v1). Anything else is a real failure — let the tick handle it.
if (err && err.status === 404) {
ltcSupported = false;
ltcLast = { time: '', receiving: false };
return;
}
throw err;
}
}
function broadcast() { function broadcast() {
latest = { latest = {
enabled, enabled,
ltcEnabled,
timerFont,
reachable: latest.reachable, reachable: latest.reachable,
lastError: latest.lastError, lastError: latest.lastError,
timers: latest.timers, timers: latest.timers,
ltc: { supported: ltcSupported, time: ltcLast.time, receiving: ltcLast.receiving }, ltc: composeLtc(),
}; };
if (!streams.size) return; if (!streams.size) return;
let frame; let frame;
@@ -253,18 +245,12 @@ module.exports = {
} }
// THE HOT PATH — live values every tick. // THE HOT PATH — live values every tick.
const currentTimes = await requestJson('/v1/timers/current'); const currentTimes = await requestJson('/v1/timers/current');
// Probe timecode once per connection; poll it only when it exists.
await pollLtc();
latest.timers = mergeTimers(currentTimes); latest.timers = mergeTimers(currentTimes);
latest.reachable = true; latest.reachable = true;
latest.lastError = ''; latest.lastError = '';
} catch (err) { } catch (err) {
latest.reachable = false; latest.reachable = false;
latest.lastError = err instanceof Error ? err.message : String(err); latest.lastError = err instanceof Error ? err.message : String(err);
// Re-probe timecode after a reconnect — the unreachable spell may
// have been a ProPresenter upgrade or a different machine.
ltcSupported = null;
ltcLast = { time: '', receiving: false };
} }
broadcast(); broadcast();
if (stopped) return; if (stopped) return;
@@ -278,6 +264,27 @@ module.exports = {
log('no ProPresenter host configured — set one in /admin'); log('no ProPresenter host configured — set one in /admin');
} }
// The built-in listener is independent of ProPresenter — LTC-only
// setups (no host configured) still get the LTC card.
let ltcListener = null;
if (ltcEnabled) {
if (ltcDevice) {
ltcListener = createLtcListener({
device: ltcDevice,
channel: ltcChannel,
moduleDir: __dirname,
log,
onUpdate(update) {
listenerLtc = update;
broadcast();
},
});
} else {
listenerLtc = { error: 'LTC listener is on but no audio device is selected — pick one in Admin' };
broadcast();
}
}
const heartbeat = setInterval(() => { const heartbeat = setInterval(() => {
for (const res of streams) { for (const res of streams) {
try { try {
@@ -296,6 +303,7 @@ module.exports = {
stopped = true; stopped = true;
clearTimeout(pollTimer); clearTimeout(pollTimer);
clearInterval(heartbeat); clearInterval(heartbeat);
ltcListener?.stop();
for (const res of streams) { for (const res of streams) {
try { res.end(); } catch { /* already gone */ } try { res.end(); } catch { /* already gone */ }
} }
@@ -303,9 +311,19 @@ module.exports = {
if (current && current.streams === streams) current = null; if (current && current.streams === streams) current = null;
}, },
health() { health() {
if (!enabled) return { status: 'error', message: 'No ProPresenter host configured' }; // LTC status suffix for the admin health line.
const ltcNote = !ltcEnabled
? ''
: latest.ltc.supported
? `, LTC ${latest.ltc.status}`
: (latest.ltc.note ? ` (LTC: ${latest.ltc.note})` : '');
if (!enabled) {
// The LTC listener works regardless of ProPresenter — an
// LTC-only setup is half-configured but working.
if (latest.ltc.supported) return { status: 'ok', message: `No ProPresenter host configured — LTC only, ${latest.ltc.status}` };
return { status: 'error', message: 'No ProPresenter host configured' };
}
if (latest.reachable) { if (latest.reachable) {
const ltcNote = latest.ltc.supported ? ' (with timecode)' : '';
return { status: 'ok', message: `Polling ${host}:${port}, ${latest.timers.length} timer(s)${ltcNote}` }; return { status: 'ok', message: `Polling ${host}:${port}, ${latest.timers.length} timer(s)${ltcNote}` };
} }
return { return {
@@ -327,7 +345,7 @@ module.exports = {
*/ */
tiles() { tiles() {
const state = current ? current.getLatest() : null; const state = current ? current.getLatest() : null;
if (!state || !state.enabled) return []; // unconfigured → classic single entry if (!state || (!state.enabled && !state.ltcEnabled)) return []; // unconfigured → classic single entry
const TYPE_LABEL = { const TYPE_LABEL = {
countdown: 'Countdown timer', countdown: 'Countdown timer',
countdown_to_time: 'Countdown to a time of day', countdown_to_time: 'Countdown to a time of day',
@@ -336,22 +354,56 @@ module.exports = {
}; };
const oneCard = { defaultSize: { w: 3, h: 2 }, minSize: { w: 2, h: 1 } }; const oneCard = { defaultSize: { w: 3, h: 2 }, minSize: { w: 2, h: 1 } };
return [ return [
{ id: 'all', name: 'All timers', description: 'Every timer and the LTC timecode, selectable per tile' }, {
id: 'all',
name: 'All timers',
description: state.ltcEnabled
? 'Every timer and the LTC timecode, selectable per tile'
: 'Every timer, selectable per tile',
},
...state.timers.map((t) => ({ ...state.timers.map((t) => ({
id: `timer:${t.uuid}`, id: `timer:${t.uuid}`,
name: t.name, name: t.name,
description: TYPE_LABEL[t.type] || 'Timer', description: TYPE_LABEL[t.type] || 'Timer',
...oneCard, ...oneCard,
})), })),
{ id: 'ltc', name: 'LTC timecode', description: 'Incoming timecode (HH:MM:SS:FF)', ...oneCard }, // The LTC entry exists only while the admin switch is on.
...(state.ltcEnabled
? [{ id: 'ltc', name: 'LTC timecode', description: 'Incoming timecode (HH:MM:SS:FF)', ...oneCard }]
: []),
]; ];
}, },
routes() { routes() {
const sendJson = (res, code, body) => {
res.writeHead(code, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' });
res.end(JSON.stringify(body));
};
return { return {
'GET /state': (req, res) => { 'GET /state': (req, res) => {
res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' }); sendJson(res, 200, { state: current ? current.getLatest() : clearedState(false) });
res.end(JSON.stringify({ state: current ? current.getLatest() : clearedState(false) })); },
// The admin device picker asks this machine what it can hear. The
// options shape matches the admin select's optionsRoute contract.
'GET /ltc/devices': (req, res) => {
const bin = require('path').join(__dirname, 'ltc-capture');
const child = spawn(bin, ['--list'], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 4000 });
let err = '';
child.stderr.setEncoding('utf8');
child.stderr.on('data', (t) => { err += t; });
child.on('error', () => {
sendJson(res, 200, { options: [], error: 'LTC capture tool missing — see modules/propresenter-timers/ltc-capture.swift' });
});
child.on('exit', () => {
if (res.writableEnded) return;
const options = [];
for (const line of err.split('\n')) {
const m = line.match(/^ltc-capture:\s+(.*?)\s+(\d+) ch\s+(\d+) Hz\s+uid=/);
if (m) options.push({ value: m[1], label: `${m[1]} — ${m[2]} ch @ ${(Number(m[3]) / 1000)} kHz` });
}
sendJson(res, 200, { options });
});
}, },
'GET /stream': (req, res) => { 'GET /stream': (req, res) => {
modules/propresenter-timers/style.css
+18 -5
View File
@@ -30,8 +30,12 @@
} }
[data-module="propresenter-timers"] .tm-banner[hidden] { display: none; } [data-module="propresenter-timers"] .tm-banner[hidden] { display: none; }
/* Values still on screen while the feed is down are stale — say so visually. */ /* Values still on screen while the feed is down are stale — say so visually.
[data-module="propresenter-timers"] .tm-wrap.is-stale .tm-grid { opacity: 0.45; } Per-card, because the reader-fed LTC card is not stale when only
ProPresenter is unreachable; it dims only when the ProdDash feed itself
is down (is-feed-down) and everything on screen really is old. */
[data-module="propresenter-timers"] .tm-wrap.is-stale .tm-card { opacity: 0.45; }
[data-module="propresenter-timers"] .tm-wrap.is-stale:not(.is-feed-down) .tm-card-ltc.src-reader { opacity: 1; }
[data-module="propresenter-timers"] .tm-hint { [data-module="propresenter-timers"] .tm-hint {
flex: 1; flex: 1;
@@ -54,7 +58,6 @@
grid-auto-rows: 1fr; grid-auto-rows: 1fr;
gap: var(--tm-gap, 8px); gap: var(--tm-gap, 8px);
padding: var(--tm-pad, 10px); padding: var(--tm-pad, 10px);
transition: opacity 0.3s ease;
} }
[data-module="propresenter-timers"] .tm-grid[hidden] { display: none; } [data-module="propresenter-timers"] .tm-grid[hidden] { display: none; }
@@ -80,6 +83,7 @@
border-radius: 10px; border-radius: 10px;
background: color-mix(in srgb, var(--bg) 60%, transparent); background: color-mix(in srgb, var(--bg) 60%, transparent);
overflow: hidden; overflow: hidden;
transition: opacity 0.3s ease;
} }
[data-module="propresenter-timers"] .tm-name { [data-module="propresenter-timers"] .tm-name {
@@ -109,6 +113,13 @@
white-space: nowrap; white-space: nowrap;
} }
/* Admin "Timer font: Monospace" — steadier digits as the numbers change.
Applies to timer and LTC values alike (both are .tm-time). */
[data-module="propresenter-timers"] .tm-mono .tm-time {
font-family: ui-monospace, "SF Mono", "Menlo", "Cascadia Mono", "Consolas", monospace;
letter-spacing: 0;
}
[data-module="propresenter-timers"] .tm-state { [data-module="propresenter-timers"] .tm-state {
flex: none; flex: none;
max-width: 100%; max-width: 100%;
@@ -198,6 +209,10 @@
@keyframes tm-nosignal-blink { 50% { opacity: 0.35; } } @keyframes tm-nosignal-blink { 50% { opacity: 0.35; } }
/* LTC ceased mid-show: hold the last frame, quietly — no alarm colors,
stopping the clock is usually somebody doing their job. */
[data-module="propresenter-timers"] .tm-card-ltc.is-ltc-stopped .tm-time { color: var(--muted); }
/* No timecode API on this ProPresenter: say so, quietly. */ /* No timecode API on this ProPresenter: say so, quietly. */
[data-module="propresenter-timers"] .tm-card-ltc.is-ltc-unavailable .tm-time { color: var(--muted); } [data-module="propresenter-timers"] .tm-card-ltc.is-ltc-unavailable .tm-time { color: var(--muted); }
[data-module="propresenter-timers"] .tm-card-ltc.is-ltc-unavailable .tm-state { [data-module="propresenter-timers"] .tm-card-ltc.is-ltc-unavailable .tm-state {
@@ -207,8 +222,6 @@
text-align: center; text-align: center;
} }
[data-module="propresenter-timers"] .tm-card-ltc.is-ltc-waiting .tm-time { color: var(--muted); }
/* ── the "Timers ▾" menu (container styled/positioned by the shell) ── */ /* ── the "Timers ▾" menu (container styled/positioned by the shell) ── */
[data-module="propresenter-timers"] .tm-menu-item { [data-module="propresenter-timers"] .tm-menu-item {
package.json
+13
View File
@@ -0,0 +1,13 @@
{
"name": "proddash",
"version": "1.3.0",
"private": true,
"description": "Modular production dashboard for Waters Church — zero-dependency Node server + vanilla client",
"license": "UNLICENSED",
"engines": {
"node": ">=18"
},
"scripts": {
"start": "node server.js"
}
}
public/admin/admin.css
+65
View File
@@ -247,3 +247,68 @@ details.field-group > summary.field-group-title:hover { color: var(--text); }
.layout-row .name { flex: 1; font-size: 13px; font-weight: 600; } .layout-row .name { flex: 1; font-size: 13px; font-weight: 600; }
.layout-row .meta { color: var(--muted); font-size: 11px; } .layout-row .meta { color: var(--muted); font-size: 11px; }
.layouts-empty { color: var(--muted); font-size: 13px; } .layouts-empty { color: var(--muted); font-size: 13px; }
/* ── version, update banner, catalog ───────────────────────────────── */
.admin-version {
font-size: 11px;
color: var(--muted);
margin-left: 4px;
vertical-align: 2px;
}
.update-card {
border-color: color-mix(in srgb, var(--warn) 55%, var(--border));
background: color-mix(in srgb, var(--warn) 7%, var(--panel));
margin-top: 18px;
}
.update-head {
display: flex;
align-items: center;
gap: 8px;
flex-wrap: wrap;
}
.update-head strong { font-size: 14px; }
.update-head .spacer { flex: 1; }
.update-card .admin-copy { margin: 8px 0 0; }
.btn.small { padding: 4px 9px; font-size: 12px; }
.btn.danger { color: var(--danger); border-color: color-mix(in srgb, var(--danger) 45%, var(--border)); }
.btn.danger:hover { background: color-mix(in srgb, var(--danger) 14%, var(--bg)); }
.btn[disabled] { opacity: 0.5; cursor: not-allowed; }
a.btn { text-decoration: none; }
.module-source {
font-size: 10px;
font-weight: 600;
letter-spacing: 0.06em;
text-transform: uppercase;
color: var(--muted);
border: 1px solid var(--border);
border-radius: 4px;
padding: 1px 5px;
}
.module-update-slot:empty { display: none; }
.catalog-toolbar {
display: flex;
align-items: center;
gap: 10px;
margin-bottom: 10px;
}
.catalog-toolbar .admin-status { margin-top: 0; }
.catalog-row {
display: flex;
align-items: flex-start;
gap: 12px;
background: var(--panel);
border: 1px solid var(--border);
border-radius: 10px;
padding: 12px 14px;
margin-bottom: 10px;
}
.catalog-main { flex: 1; min-width: 0; }
.catalog-title { display: flex; align-items: center; gap: 8px; }
.catalog-row .module-desc { margin: 4px 0 2px; }
.catalog-row .module-health { margin-top: 2px; }
public/admin/admin.js
+249 -6
View File
@@ -12,6 +12,19 @@ const modulesList = document.getElementById('modules-list');
const layoutsSection = document.getElementById('layouts-section'); const layoutsSection = document.getElementById('layouts-section');
const layoutsList = document.getElementById('layouts-list'); const layoutsList = document.getElementById('layouts-list');
const toastEl = document.getElementById('toast'); const toastEl = document.getElementById('toast');
const availableSection = document.getElementById('available-section');
const availableList = document.getElementById('available-list');
const catalogStatus = document.getElementById('catalog-status');
const updateCard = document.getElementById('update-card');
const updateTitle = document.getElementById('update-title');
const updateCopy = document.getElementById('update-copy');
const updateStatus = document.getElementById('update-status');
const updateBtn = document.getElementById('update-btn');
const updateChanges = document.getElementById('update-changes');
const shellVersionEl = document.getElementById('shell-version');
/** The shell version the page loaded with — the update flow watches it change. */
let shellVersion = '';
let toastTimer = null; let toastTimer = null;
function toast(msg, isError = false) { function toast(msg, isError = false) {
@@ -42,7 +55,9 @@ async function api(path, opts = {}) {
function showLogin() { function showLogin() {
loginCard.hidden = false; loginCard.hidden = false;
modulesSection.hidden = true; modulesSection.hidden = true;
availableSection.hidden = true;
layoutsSection.hidden = true; layoutsSection.hidden = true;
updateCard.hidden = true;
passcodeInput.focus(); passcodeInput.focus();
} }
@@ -280,9 +295,43 @@ function buildModuleCard(mod) {
version.className = 'module-version'; version.className = 'module-version';
version.textContent = mod.version ? 'v' + mod.version : ''; version.textContent = mod.version ? 'v' + mod.version : '';
const source = document.createElement('span');
source.className = 'module-source';
source.textContent = mod.source === 'installed' ? 'installed' : 'bundled';
source.title = mod.source === 'installed'
? 'Installed from the repo into the data directory'
: 'Ships with this copy of ProdDash';
const spacer = document.createElement('span'); const spacer = document.createElement('span');
spacer.className = 'spacer'; spacer.className = 'spacer';
// filled by the catalog when the repo has a newer version
const updateSlot = document.createElement('span');
updateSlot.className = 'module-update-slot';
const uninstall = document.createElement('button');
uninstall.className = 'btn small danger';
uninstall.textContent = 'Uninstall';
uninstall.title = mod.source === 'installed'
? 'Remove this module\'s files from the data directory'
: 'Hide this bundled module from every dashboard (its folder stays with the app)';
uninstall.addEventListener('click', async () => {
const what = mod.source === 'installed'
? `Uninstall ${mod.name}? Its files are removed from the data directory. Its settings are kept in case you install it again.`
: `Uninstall ${mod.name}? It disappears from every dashboard and the picker. It ships with ProdDash, so it can be brought back from "Available modules" any time.`;
if (!window.confirm(what)) return;
uninstall.disabled = true;
try {
await api(`/api/admin/modules/${encodeURIComponent(mod.id)}`, { method: 'DELETE' });
toast(`${mod.name} uninstalled`);
await loadState();
} catch (e) {
uninstall.disabled = false;
if (e.authRequired) showLogin();
else toast(e.message, true);
}
});
const toggleLabel = document.createElement('label'); const toggleLabel = document.createElement('label');
toggleLabel.className = 'switch'; toggleLabel.className = 'switch';
const toggle = document.createElement('input'); const toggle = document.createElement('input');
@@ -294,7 +343,7 @@ function buildModuleCard(mod) {
toggleText.textContent = mod.enabled ? 'Enabled' : 'Disabled'; toggleText.textContent = mod.enabled ? 'Enabled' : 'Disabled';
toggleLabel.append(toggle, track, toggleText); toggleLabel.append(toggle, track, toggleText);
head.append(dot, name, version, spacer, toggleLabel); head.append(dot, name, version, source, spacer, updateSlot, toggleLabel, uninstall);
card.appendChild(head); card.appendChild(head);
const desc = document.createElement('div'); const desc = document.createElement('div');
@@ -309,11 +358,13 @@ function buildModuleCard(mod) {
const mountError = document.createElement('div'); const mountError = document.createElement('div');
mountError.className = 'module-mount-error'; mountError.className = 'module-mount-error';
mountError.hidden = !mod.mountError; mountError.hidden = !mod.mountError && !mod.incompatible;
mountError.textContent = mod.mountError ? `Failed to start: ${mod.mountError}` : ''; mountError.textContent = mod.incompatible
? `Not loaded — ${mod.incompatible}. Update ProdDash from the banner above.`
: (mod.mountError ? `Failed to start: ${mod.mountError}` : '');
card.appendChild(mountError); card.appendChild(mountError);
liveEls.set(mod.id, { dot, healthEl, toggle, toggleText, mountError }); liveEls.set(mod.id, { dot, healthEl, toggle, toggleText, mountError, updateSlot });
toggle.addEventListener('change', async () => { toggle.addEventListener('change', async () => {
try { try {
@@ -481,8 +532,10 @@ async function refreshStatus() {
els.dot.className = 'dot ' + healthClass(mod); els.dot.className = 'dot ' + healthClass(mod);
els.healthEl.textContent = healthText(mod); els.healthEl.textContent = healthText(mod);
els.healthEl.className = 'module-health ' + (healthClass(mod) === 'error' ? 'error' : ''); els.healthEl.className = 'module-health ' + (healthClass(mod) === 'error' ? 'error' : '');
els.mountError.hidden = !mod.mountError; if (!mod.incompatible) {
els.mountError.textContent = mod.mountError ? `Failed to start: ${mod.mountError}` : ''; els.mountError.hidden = !mod.mountError;
els.mountError.textContent = mod.mountError ? `Failed to start: ${mod.mountError}` : '';
}
if (document.activeElement !== els.toggle) { if (document.activeElement !== els.toggle) {
els.toggle.checked = mod.enabled; els.toggle.checked = mod.enabled;
els.toggleText.textContent = mod.enabled ? 'Enabled' : 'Disabled'; els.toggleText.textContent = mod.enabled ? 'Enabled' : 'Disabled';
@@ -574,6 +627,9 @@ async function loadState() {
} }
loginCard.hidden = true; loginCard.hidden = true;
modulesSection.hidden = false; modulesSection.hidden = false;
availableSection.hidden = false;
shellVersion = String(state.version || '');
shellVersionEl.textContent = shellVersion ? 'v' + shellVersion : '';
const storageNote = document.getElementById('storage-note'); const storageNote = document.getElementById('storage-note');
if (state.dataDir) { if (state.dataDir) {
document.getElementById('storage-path').textContent = state.dataDir; document.getElementById('storage-path').textContent = state.dataDir;
@@ -585,8 +641,195 @@ async function loadState() {
modulesList.appendChild(buildModuleCard(mod)); modulesList.appendChild(buildModuleCard(mod));
} }
loadLayouts(); loadLayouts();
loadCatalog(false);
} }
/* ── the repo: available modules, module updates, shell update ──────── */
function fmtTime(ms) {
return ms ? new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' }) : '';
}
async function loadCatalog(refresh) {
catalogStatus.className = 'admin-status';
catalogStatus.textContent = refresh ? 'Checking the repo…' : 'Checking…';
let cat;
try {
cat = await api('/api/admin/catalog' + (refresh ? '?refresh=1' : ''));
} catch (e) {
if (e.authRequired) return showLogin();
catalogStatus.className = 'admin-status error';
catalogStatus.textContent = e.message;
return;
}
renderShell(cat.shell || {});
renderAvailable(cat);
}
function renderShell(shell) {
const remote = shell.remote || {};
if (remote.error) {
catalogStatus.className = 'admin-status error';
catalogStatus.textContent = `Couldn't reach ${shell.repo}: ${remote.error}`;
} else {
catalogStatus.className = 'admin-status';
catalogStatus.textContent = `${shell.repo}@${shell.branch}` +
(remote.version ? ` · latest ProdDash ${remote.version}` : '') +
(remote.checkedAt ? ` · checked ${fmtTime(remote.checkedAt)}` : '');
}
if (!shell.updateAvailable) {
updateCard.hidden = true;
return;
}
updateCard.hidden = false;
updateTitle.textContent = shell.versionBehind
? `ProdDash ${remote.version} is available`
: `New commits on ${shell.branch}`;
const where = shell.local?.isGit
? `a git checkout of ${shell.local.branch} at ${String(shell.local.sha || '').slice(0, 7)}; updating runs git pull`
: 'not a git checkout; updating unpacks the repo archive over the app folder';
updateCopy.textContent = `You're running ProdDash ${shell.version} (${where}). Settings and layouts live outside the app folder and are not touched.`;
updateChanges.href = shell.changesUrl || '#';
updateBtn.disabled = Boolean(shell.updateBlocker) || updateBtn.dataset.busy === '1';
if (shell.updateBlocker) {
updateStatus.className = 'admin-status error';
updateStatus.textContent = `Can't update from here: ${shell.updateBlocker}.`;
} else if (updateBtn.dataset.busy !== '1') {
updateStatus.className = 'admin-status';
updateStatus.textContent = 'Updating restarts ProdDash; open dashboards reconnect on their own.';
}
}
function renderAvailable(cat) {
availableList.innerHTML = '';
const updates = cat.updates || [];
// newer versions of installed modules → a button on their card
for (const els of liveEls.values()) els.updateSlot.innerHTML = '';
for (const up of updates) {
const els = liveEls.get(up.id);
if (!els) continue;
const btn = document.createElement('button');
btn.className = 'btn small primary';
btn.textContent = `Update to v${up.version}`;
btn.disabled = !up.compatible;
btn.title = up.compatible ? `Download v${up.version} from the repo` : up.reason;
btn.addEventListener('click', () => installFromCatalog(up, btn));
els.updateSlot.appendChild(btn);
}
const available = cat.available || [];
if (!available.length) {
const none = document.createElement('div');
none.className = 'layouts-empty';
none.textContent = cat.shell?.remote?.error
? 'The repo could not be reached, and nothing bundled is waiting to be installed.'
: 'Everything the repo offers is installed.';
availableList.appendChild(none);
return;
}
for (const item of available) {
const row = document.createElement('div');
row.className = 'catalog-row';
const main = document.createElement('div');
main.className = 'catalog-main';
const title = document.createElement('div');
title.className = 'catalog-title';
const name = document.createElement('span');
name.className = 'module-name';
name.textContent = item.name;
const version = document.createElement('span');
version.className = 'module-version';
version.textContent = item.version ? 'v' + item.version : '';
const source = document.createElement('span');
source.className = 'module-source';
source.textContent = item.source === 'bundled' ? 'bundled' : 'repo';
source.title = item.source === 'bundled' ? 'Ships with this copy of ProdDash — restoring it downloads nothing' : 'Downloaded from the repo';
title.append(name, version, source);
const desc = document.createElement('div');
desc.className = 'module-desc';
desc.textContent = item.description || '';
const req = document.createElement('div');
req.className = 'module-health' + (item.compatible ? '' : ' error');
req.textContent = item.compatible
? (item.requires ? `Requires ProdDash ${item.requires}` : '')
: item.reason;
main.append(title, desc, req);
const btn = document.createElement('button');
btn.className = 'btn small primary';
btn.textContent = 'Install';
btn.disabled = !item.compatible;
btn.title = item.compatible ? '' : item.reason;
btn.addEventListener('click', () => installFromCatalog(item, btn));
row.append(main, btn);
availableList.appendChild(row);
}
}
async function installFromCatalog(item, btn) {
btn.disabled = true;
const label = btn.textContent;
btn.textContent = 'Installing…';
try {
const r = await api(`/api/admin/modules/${encodeURIComponent(item.id)}/install`, { method: 'POST', body: '{}' });
toast(`${item.name} ${r.downloaded ? 'installed' : 'restored'}${r.version ? ' (v' + r.version + ')' : ''}`);
await loadState();
} catch (e) {
btn.disabled = false;
btn.textContent = label;
if (e.authRequired) showLogin();
else toast(e.message, true);
}
}
document.getElementById('catalog-refresh').addEventListener('click', () => loadCatalog(true));
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
/** After the update the server exits and comes back; wait for it. */
async function waitForRestart(before) {
const started = Date.now();
let sawDown = false;
while (Date.now() - started < 90000) {
await sleep(1500);
try {
const s = await api('/api/admin/state');
if (sawDown || s.version !== before) {
toast(`ProdDash ${s.version} is running`);
await sleep(600);
location.reload();
return;
}
} catch (e) {
if (e.status === 401) { location.reload(); return; } // back up, passcode wanted again
sawDown = true;
}
}
updateStatus.className = 'admin-status error';
updateStatus.textContent = 'ProdDash did not come back on its own — start it again on the server, then reload this page.';
updateBtn.dataset.busy = '';
updateBtn.disabled = false;
}
updateBtn.addEventListener('click', async () => {
if (!window.confirm('Update ProdDash now? The server restarts and every open dashboard reconnects a few seconds later.')) return;
updateBtn.dataset.busy = '1';
updateBtn.disabled = true;
updateStatus.className = 'admin-status';
updateStatus.textContent = 'Updating…';
const before = shellVersion;
try {
const r = await api('/api/admin/update', { method: 'POST', body: '{}' });
updateStatus.textContent = `Updated ${r.from} → ${r.to || 'latest commit'} via ${r.method}. Restarting…`;
} catch (e) {
updateStatus.className = 'admin-status error';
updateStatus.textContent = e.message;
updateBtn.dataset.busy = '';
updateBtn.disabled = false;
if (e.authRequired) showLogin();
return;
}
await waitForRestart(before);
});
setInterval(() => { setInterval(() => {
if (modulesSection.hidden) return; if (modulesSection.hidden) return;
refreshStatus(); refreshStatus();
public/admin/index.html
+25 -1
View File
@@ -11,7 +11,7 @@
</head> </head>
<body> <body>
<header id="topbar"> <header id="topbar">
<span id="brand">Prod<span class="accent">Dash</span> <span class="admin-tag">Admin</span></span> <span id="brand">Prod<span class="accent">Dash</span> <span class="admin-tag">Admin</span> <span class="admin-version" id="shell-version"></span></span>
<span class="spacer"></span> <span class="spacer"></span>
<a class="tb-btn" href="/">← Dashboard</a> <a class="tb-btn" href="/">← Dashboard</a>
</header> </header>
@@ -27,6 +27,18 @@
<div class="admin-status" id="login-status"></div> <div class="admin-status" id="login-status"></div>
</section> </section>
<section class="admin-card update-card" id="update-card" hidden>
<div class="update-head">
<span class="dot connecting"></span>
<strong id="update-title">Update available</strong>
<span class="spacer"></span>
<a class="btn small" id="update-changes" href="#" target="_blank" rel="noopener">What changed</a>
<button class="btn small primary" id="update-btn">Update now</button>
</div>
<p class="admin-copy" id="update-copy"></p>
<div class="admin-status" id="update-status"></div>
</section>
<section id="modules-section" hidden> <section id="modules-section" hidden>
<h1 class="admin-h1">Modules</h1> <h1 class="admin-h1">Modules</h1>
<p class="admin-copy">Server-wide settings, shared by every dashboard. Saving re-initialises the <p class="admin-copy">Server-wide settings, shared by every dashboard. Saving re-initialises the
@@ -37,6 +49,18 @@
<div id="modules-list"></div> <div id="modules-list"></div>
</section> </section>
<section id="available-section" hidden>
<h1 class="admin-h1">Available modules</h1>
<p class="admin-copy">Modules in the ProdDash repo that aren't installed here. Installing downloads the module
into the server's data directory — no restart, nothing written into the app folder. A module that needs a
newer ProdDash can't be installed until the shell is updated.</p>
<div class="catalog-toolbar">
<button class="btn small" id="catalog-refresh">Check again</button>
<span class="admin-status" id="catalog-status"></span>
</div>
<div id="available-list"></div>
</section>
<section id="layouts-section" hidden> <section id="layouts-section" hidden>
<h1 class="admin-h1">Named layouts</h1> <h1 class="admin-h1">Named layouts</h1>
<p class="admin-copy">Layouts saved to the server from the dashboard's Layout menu. Loading one <p class="admin-copy">Layouts saved to the server from the dashboard's Layout menu. Loading one
public/index.html
+3 -2
View File
@@ -15,7 +15,8 @@
</head> </head>
<body> <body>
<header id="topbar"> <header id="topbar">
<span id="brand">Prod<span class="accent">Dash</span></span> <!-- invisible twin of the logo: holds its place in the bar; the real logo is the handle below -->
<span id="brand" class="brand-spacer" aria-hidden="true">Prod<span class="accent">Dash</span></span>
<span class="spacer"></span> <span class="spacer"></span>
@@ -50,7 +51,7 @@
</a> </a>
</header> </header>
<button id="topbar-notch" title="Hide / show the menu bar" aria-label="Hide or show the menu bar"></button> <button id="topbar-notch" title="Hide / show the menu bar" aria-label="Hide or show the menu bar">Prod<span class="accent">Dash</span></button>
<main id="gridwrap"> <main id="gridwrap">
<div id="grid"> <div id="grid">
public/style.css
+38 -20
View File
@@ -54,36 +54,54 @@ body.menu-hidden #topbar {
overflow: hidden; overflow: hidden;
} }
/* The menubar's own show/hide tab. It sits under the ProdDash brand at the /* The menubar's show/hide handle IS the logo: a translucent accent pill
left — not screen-centre, where a tile's own (centred) tab would land wrapped around "ProdDash" at the left of the bar, "Dash" cut out in the
right under it once both bars are hidden — and wears the accent colour background colour. It sits at the left — never screen-centre, where a
so it never reads as a tile tab. */ tile's own (centred) tab lands once both bars are hidden. When the bar
hides, the pill shrinks to a slim lip at the very top edge, clear of a
top-row tile's status dot and title. */
.brand-spacer { visibility: hidden; }
#topbar-notch { #topbar-notch {
position: fixed; position: fixed;
/* straddles the bar's bottom edge — mostly on the bar, a short lip below /* a tab hung from the top of the bar: square top, rounded bottom, hanging
it — so it never covers a top-row tile's status dot or title */ 8px past the bar's bottom edge; the logo sits centred in the bar part */
top: calc(var(--topbar-h, 46px) - 8px); top: 0;
left: 12px; left: 2px; /* the logo text starts at the bar's 12px padding; the tab adds 10px each side */
width: 54px; height: calc(var(--topbar-h, 46px) + 8px);
height: 14px; min-width: 60px;
padding: 0; padding: 0 10px;
background: var(--accent); font: inherit;
font-weight: 800;
font-size: 15px;
letter-spacing: 0.02em;
line-height: var(--topbar-h, 46px);
color: var(--text);
background: color-mix(in srgb, var(--accent) 45%, transparent);
border: none; border: none;
border-radius: 0 0 10px 10px; border-radius: 0 0 12px 12px;
cursor: pointer; cursor: pointer;
z-index: 60; z-index: 60;
opacity: 0.55; transition: height 0.22s ease, line-height 0.22s ease, font-size 0.22s ease, background 0.15s ease;
transition: opacity 0.15s ease, top 0.22s ease, height 0.22s ease;
} }
#topbar-notch:hover { opacity: 1; } #topbar-notch .accent { color: var(--bg); } /* the cutout */
/* bar hidden: a slim tab at the very top edge, clear of a top-row tile's dot and title */ #topbar-notch:hover { background: color-mix(in srgb, var(--accent) 68%, transparent); }
body.menu-hidden #topbar-notch { top: 0; height: 10px; } /* bar hidden: the text folds away and the tab becomes a lip at the top edge */
#topbar-notch::after { body.menu-hidden #topbar-notch {
height: 10px;
line-height: 10px;
font-size: 0;
background: color-mix(in srgb, var(--accent) 55%, transparent);
}
body.menu-hidden #topbar-notch:hover { background: var(--accent); }
body.menu-hidden #topbar-notch::after {
content: ""; content: "";
display: block; display: block;
width: 20px; width: 20px;
height: 3px; height: 3px;
margin: 4px auto 0; margin: 0 auto;
position: relative;
top: 3px;
border-radius: 999px; border-radius: 999px;
background: var(--bg); background: var(--bg);
} }
server.js
+566 -14
View File
@@ -22,10 +22,12 @@ const fs = require('fs');
const path = require('path'); const path = require('path');
const os = require('os'); const os = require('os');
const crypto = require('crypto'); const crypto = require('crypto');
const zlib = require('zlib');
const { spawn, execFileSync } = require('child_process');
const ROOT = __dirname; const ROOT = __dirname;
const PUBLIC_DIR = path.join(ROOT, 'public'); const PUBLIC_DIR = path.join(ROOT, 'public');
const MODULES_DIR = path.join(ROOT, 'modules'); const BUNDLED_MODULES_DIR = path.join(ROOT, 'modules'); // modules that ship with the checkout
/** Checked-in defaults (proddash.json) — and where runtime state used to live. */ /** Checked-in defaults (proddash.json) — and where runtime state used to live. */
const REPO_CONFIG_DIR = path.join(ROOT, 'config'); const REPO_CONFIG_DIR = path.join(ROOT, 'config');
@@ -73,6 +75,7 @@ function resolveDataDir() {
const DATA_DIR = resolveDataDir(); const DATA_DIR = resolveDataDir();
const MODULES_CONFIG_PATH = path.join(DATA_DIR, 'modules.json'); const MODULES_CONFIG_PATH = path.join(DATA_DIR, 'modules.json');
const LAYOUTS_DIR = path.join(DATA_DIR, 'layouts'); const LAYOUTS_DIR = path.join(DATA_DIR, 'layouts');
const INSTALLED_MODULES_DIR = path.join(DATA_DIR, 'modules'); // modules installed from the admin page
/* ── config files ───────────────────────────────────────────────────── */ /* ── config files ───────────────────────────────────────────────────── */
@@ -139,6 +142,59 @@ const shellConfig = {
}; };
const PORT = Number(process.env.PORT || shellConfig.port || 24500); const PORT = Number(process.env.PORT || shellConfig.port || 24500);
/* ── shell version & version ranges ─────────────────────────────────── */
/** The shell's own version, from package.json. Modules declare the range
they need in their manifest ("proddash": ">=1.1.0"). */
const SHELL_VERSION = String(readJson(path.join(ROOT, 'package.json'), {}).version || '0.0.0');
function parseVersion(v) {
const m = String(v || '').trim().match(/^v?(\d+)\.(\d+)(?:\.(\d+))?/);
return m ? [Number(m[1]), Number(m[2]), Number(m[3] || 0)] : null;
}
/** -1 / 0 / 1 like a comparator; unparseable versions sort lowest. */
function compareVersions(a, b) {
const pa = parseVersion(a) || [-1, 0, 0];
const pb = parseVersion(b) || [-1, 0, 0];
for (let i = 0; i < 3; i += 1) {
if (pa[i] !== pb[i]) return pa[i] < pb[i] ? -1 : 1;
}
return 0;
}
/**
* Does `version` satisfy `range`? Ranges are deliberately small: "" or "*"
* (anything), "1.2.0" (exact), ">=1.2.0", ">1.2.0", "<=…", "<…",
* "^1.2.0" (same major, at least that), "~1.2.0" (same minor, at least
* that), and space-separated combinations such as ">=1.1.0 <2.0.0".
*/
function satisfiesVersion(version, range) {
const r = String(range || '').trim();
if (!r || r === '*') return true;
const v = parseVersion(version);
if (!v) return false;
return r.split(/[\s,]+/).filter(Boolean).every((part) => {
const m = part.match(/^(>=|<=|>|<|=|\^|~)?v?(\d+)\.(\d+)(?:\.(\d+))?$/);
if (!m) return false;
const t = [Number(m[2]), Number(m[3]), Number(m[4] || 0)];
const c = compareVersions(v.join('.'), t.join('.'));
switch (m[1] || '=') {
case '>=': return c >= 0;
case '>': return c > 0;
case '<=': return c <= 0;
case '<': return c < 0;
case '^': return v[0] === t[0] && c >= 0;
case '~': return v[0] === t[0] && v[1] === t[1] && c >= 0;
default: return c === 0;
}
});
}
function requirementNote(range) {
return `Requires ProdDash ${range} — this is ${SHELL_VERSION}`;
}
/** Per-module server-wide state: { "<id>": { enabled: bool, config: {…} } } */ /** Per-module server-wide state: { "<id>": { enabled: bool, config: {…} } } */
let modulesConfig = readJson(MODULES_CONFIG_PATH, {}); let modulesConfig = readJson(MODULES_CONFIG_PATH, {});
@@ -147,18 +203,19 @@ let modulesConfig = readJson(MODULES_CONFIG_PATH, {});
/** @type {Map<string, object>} module id -> manifest (with .dir added) */ /** @type {Map<string, object>} module id -> manifest (with .dir added) */
const manifests = new Map(); const manifests = new Map();
function discoverModules() { /** Read every valid manifest in one modules folder. */
manifests.clear(); function readManifests(baseDir, source) {
const out = [];
let dirs = []; let dirs = [];
try { try {
dirs = fs.readdirSync(MODULES_DIR, { withFileTypes: true }) dirs = fs.readdirSync(baseDir, { withFileTypes: true })
.filter((d) => d.isDirectory()) .filter((d) => d.isDirectory() && !d.name.startsWith('.'))
.map((d) => d.name); .map((d) => d.name);
} catch { } catch {
return; // no modules/ folder yet — the shell still runs return out; // folder missing — fine
} }
for (const dir of dirs) { for (const dir of dirs) {
const manifestPath = path.join(MODULES_DIR, dir, 'module.json'); const manifestPath = path.join(baseDir, dir, 'module.json');
const man = readJson(manifestPath, null); const man = readJson(manifestPath, null);
if (!man || typeof man !== 'object') { if (!man || typeof man !== 'object') {
if (fs.existsSync(manifestPath)) console.warn(`[proddash] ${dir}/module.json is invalid — skipped`); if (fs.existsSync(manifestPath)) console.warn(`[proddash] ${dir}/module.json is invalid — skipped`);
@@ -173,9 +230,48 @@ function discoverModules() {
console.warn(`[proddash] module "${dir}": manifest has no "client" entry — skipped`); console.warn(`[proddash] module "${dir}": manifest has no "client" entry — skipped`);
continue; continue;
} }
man.dir = path.join(MODULES_DIR, dir); man.dir = path.join(baseDir, dir);
manifests.set(dir, man); man.source = source;
man.requires = String(man.proddash || '').trim();
// A module built for a newer shell is listed (so admin can explain) but never loaded.
man.incompatible = satisfiesVersion(SHELL_VERSION, man.requires) ? '' : requirementNote(man.requires);
out.push(man);
} }
return out;
}
/**
* Modules come from two places: the ones bundled with this checkout
* (modules/) and the ones installed from the admin page (the data
* directory's modules/). Same id in both → the newer version runs; a
* downloaded copy the bundled one has since overtaken is removed. A bundled
* module the admin page "uninstalled" stays on disk (it belongs to the app
* folder) but is left out here.
*/
function discoverModules() {
manifests.clear();
const bundled = new Map(readManifests(BUNDLED_MODULES_DIR, 'bundled').map((m) => [m.id, m]));
const installed = new Map(readManifests(INSTALLED_MODULES_DIR, 'installed').map((m) => [m.id, m]));
for (const [id, man] of bundled) {
if (isUninstalled(id)) continue;
const copy = installed.get(id);
if (copy && compareVersions(copy.version, man.version) >= 0) continue; // the copy wins, below
if (copy) {
console.log(`[proddash] ${id}: bundled v${man.version} supersedes the installed v${copy.version} — removing that copy`);
try { fs.rmSync(copy.dir, { recursive: true, force: true }); } catch { /* it just stays unused */ }
installed.delete(id);
}
manifests.set(id, man);
}
for (const [id, man] of installed) {
if (manifests.has(id)) continue;
man.bundledVersion = String(bundled.get(id)?.version || '');
manifests.set(id, man);
}
}
function isUninstalled(id) {
return moduleState(id).uninstalled === true;
} }
function moduleState(id) { function moduleState(id) {
@@ -187,6 +283,12 @@ function isEnabled(id) {
return moduleState(id).enabled !== false; // newly dropped modules default to enabled return moduleState(id).enabled !== false; // newly dropped modules default to enabled
} }
/** Enabled and runnable on this shell version — what dashboards may load. */
function isActive(id) {
const man = manifests.get(id);
return Boolean(man) && isEnabled(id) && !man.incompatible;
}
/** Admin config for a module: schema defaults overlaid with stored values. */ /** Admin config for a module: schema defaults overlaid with stored values. */
function effectiveConfig(id) { function effectiveConfig(id) {
const man = manifests.get(id); const man = manifests.get(id);
@@ -260,6 +362,10 @@ function mountModule(id) {
if (!man) return; if (!man) return;
const entry = { routes: [], handle: null, error: '' }; const entry = { routes: [], handle: null, error: '' };
mounted.set(id, entry); mounted.set(id, entry);
if (man.incompatible) {
entry.error = man.incompatible;
return;
}
if (!man.server) return; if (!man.server) return;
const log = makeLog(id); const log = makeLog(id);
try { try {
@@ -435,6 +541,385 @@ setInterval(() => {
} }
}, 25000).unref(); }, 25000).unref();
/* ── the repo: module catalog and shell updates ──────────────────────── */
/* The admin page installs modules from, and updates the shell against, the
ProdDash repository on GitHub — one small tar.gz of the branch, fetched at
most every few minutes, parsed here with no dependencies. Nothing is
contacted unless someone opens the admin page or the periodic update
check runs; every failure is recorded and shown, never thrown at a page. */
function parseRepoSetting(value, fallbackBranch) {
const m = String(value || '').trim().match(/^([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:#([\w./-]+))?$/);
if (!m) return null;
return { owner: m[1], repo: m[2], branch: m[3] || fallbackBranch || 'main' };
}
const REPO = parseRepoSetting(process.env.PRODDASH_REPO || shellConfig.repo, shellConfig.branch)
|| parseRepoSetting('michaelmcgary2008/ProdDash', 'main');
/** Where branch archives come from; tests point this at a local mock. */
const ARCHIVE_BASE = String(process.env.PRODDASH_ARCHIVE_BASE || 'https://codeload.github.com').replace(/\/+$/, '');
const REMOTE_TTL_MS = 10 * 60 * 1000;
const REMOTE_CHECK_MS = 6 * 60 * 60 * 1000;
const MAX_ARCHIVE_BYTES = 80 * 1024 * 1024;
function tarballUrl() {
return `${ARCHIVE_BASE}/${REPO.owner}/${REPO.repo}/tar.gz/${encodeURIComponent(REPO.branch)}`;
}
function httpError(status, message) {
const err = new Error(message);
err.status = status;
return err;
}
function safeJson(buf) {
try { return buf ? JSON.parse(buf.toString('utf8')) : null; } catch { return null; }
}
/** A relative path that can only land inside the folder it is joined to. */
function safeRelPath(p) {
if (typeof p !== 'string' || !p || p.startsWith('/') || p.includes('\\') || p.includes('\0')) return false;
return p.split('/').every((seg) => seg !== '' && seg !== '.' && seg !== '..');
}
/* — a minimal tar reader: regular files, GNU long names, pax headers — */
function cstr(buf, start, len) {
const s = buf.subarray(start, start + len);
const nul = s.indexOf(0);
return s.subarray(0, nul === -1 ? len : nul).toString('utf8');
}
/** pax records look like "27 path=some/long/name\n" (length counts itself). */
function parsePaxRecords(buf) {
const out = {};
let pos = 0;
while (pos < buf.length) {
const sp = buf.indexOf(0x20, pos);
if (sp === -1) break;
const len = parseInt(buf.subarray(pos, sp).toString(), 10);
if (!Number.isFinite(len) || len <= 0) break;
const rec = buf.subarray(sp + 1, pos + len - 1).toString('utf8');
const eq = rec.indexOf('=');
if (eq > 0) out[rec.slice(0, eq)] = rec.slice(eq + 1);
pos += len;
}
return out;
}
function parseTar(buf) {
const files = new Map();
let comment = '';
let pendingName = null;
let off = 0;
while (off + 512 <= buf.length) {
const h = buf.subarray(off, off + 512);
if (h.every((b) => b === 0)) break; // end-of-archive blocks
const size = parseInt(cstr(h, 124, 12).trim() || '0', 8) || 0;
const type = h[156] === 0 ? '0' : String.fromCharCode(h[156]);
const prefix = cstr(h, 257, 6).startsWith('ustar') ? cstr(h, 345, 155) : '';
const shortName = prefix ? `${prefix}/${cstr(h, 0, 100)}` : cstr(h, 0, 100);
const data = buf.subarray(off + 512, off + 512 + size);
off += 512 + Math.ceil(size / 512) * 512;
if (type === 'L') { pendingName = cstr(data, 0, size); continue; } // GNU long name
if (type === 'g' || type === 'x') { // pax headers
const rec = parsePaxRecords(data);
if (rec.comment && !comment) comment = String(rec.comment).trim(); // GitHub: the commit sha
if (type === 'x' && rec.path) pendingName = rec.path;
continue;
}
const name = pendingName || shortName;
pendingName = null;
if (type === '0') files.set(name, Buffer.from(data));
}
return { files, comment };
}
/** Download the branch archive → { files: Map<relative path, Buffer>, sha }. */
async function fetchArchive() {
const res = await fetch(tarballUrl(), {
redirect: 'follow',
signal: AbortSignal.timeout(30000),
headers: { 'User-Agent': `ProdDash/${SHELL_VERSION}` },
});
if (!res.ok) throw new Error(`HTTP ${res.status} fetching ${REPO.owner}/${REPO.repo}@${REPO.branch}`);
const gz = Buffer.from(await res.arrayBuffer());
if (gz.length > MAX_ARCHIVE_BYTES) throw new Error('archive is unexpectedly large');
const { files, comment } = parseTar(zlib.gunzipSync(gz));
const stripped = new Map(); // drop the archive's single top-level folder
for (const [p, data] of files) {
const i = p.indexOf('/');
if (i > 0 && i < p.length - 1) stripped.set(p.slice(i + 1), data);
}
return { files: stripped, sha: /^[0-9a-f]{7,40}$/.test(comment) ? comment : '' };
}
/** What we last learned about the repo. */
let remote = { checkedAt: 0, checking: null, error: '', sha: '', version: '', modules: new Map(), files: null };
async function refreshRemote(force = false) {
const fresh = remote.checkedAt && Date.now() - remote.checkedAt < REMOTE_TTL_MS;
if (!force && fresh && !remote.error) return remote;
if (remote.checking) return remote.checking;
const job = (async () => {
try {
const { files, sha } = await fetchArchive();
const pkg = safeJson(files.get('package.json'));
const modules = new Map();
for (const [p, data] of files) {
const m = p.match(/^modules\/([^/]+)\/(.+)$/);
if (!m) continue;
const entry = modules.get(m[1]) || { id: m[1], manifest: null, files: new Map() };
entry.files.set(m[2], data);
modules.set(m[1], entry);
}
for (const [id, entry] of modules) {
const man = safeJson(entry.files.get('module.json'));
if (!man || typeof man !== 'object' || (man.id && man.id !== id) || !man.client) {
modules.delete(id);
continue;
}
entry.manifest = { ...man, id };
}
remote = { checkedAt: Date.now(), checking: null, error: '', sha, version: String(pkg?.version || ''), modules, files };
} catch (err) {
remote = { ...remote, checkedAt: Date.now(), checking: null, error: err?.message || String(err) };
}
return remote;
})();
remote.checking = job;
return job;
}
/* — this checkout — */
function git(args, timeout = 15000) {
// fileMode=false: a chmod (e.g. making the launcher executable) is not a local change
return execFileSync('git', ['-c', 'core.fileMode=false', ...args], { cwd: ROOT, encoding: 'utf8', timeout, stdio: ['ignore', 'pipe', 'pipe'] }).trim();
}
function localGitInfo() {
if (!fs.existsSync(path.join(ROOT, '.git'))) return { isGit: false, sha: '', branch: '', dirty: false, error: '' };
try {
const porcelain = git(['status', '--porcelain']).split('\n').filter((l) => l && !l.startsWith('??'));
return { isGit: true, sha: git(['rev-parse', 'HEAD']), branch: git(['rev-parse', '--abbrev-ref', 'HEAD']), dirty: porcelain.length > 0, error: '' };
} catch (err) {
return { isGit: true, sha: '', branch: '', dirty: false, error: (err?.message || String(err)).split('\n')[0] };
}
}
function shellStatus() {
const local = localGitInfo();
const versionCmp = remote.version ? compareVersions(remote.version, SHELL_VERSION) : 0;
const versionBehind = versionCmp > 0;
const sameCommit = !local.sha || !remote.sha || local.sha.startsWith(remote.sha) || remote.sha.startsWith(local.sha);
const commitsBehind = !sameCommit && versionCmp >= 0;
let blocker = '';
if (local.isGit) {
if (local.error) blocker = `git is not usable here (${local.error})`;
else if (local.branch !== REPO.branch) blocker = `this checkout is on branch "${local.branch}", not "${REPO.branch}"`;
else if (local.dirty) blocker = 'this checkout has local changes — commit or discard them first';
}
const gh = `https://github.com/${REPO.owner}/${REPO.repo}`;
return {
version: SHELL_VERSION,
repo: `${REPO.owner}/${REPO.repo}`,
branch: REPO.branch,
local: { isGit: local.isGit, sha: local.sha, branch: local.branch, dirty: local.dirty },
remote: { version: remote.version, sha: remote.sha, checkedAt: remote.checkedAt, error: remote.error },
updateAvailable: versionBehind || commitsBehind,
versionBehind,
method: local.isGit ? 'git' : 'archive',
updateBlocker: blocker,
changesUrl: local.sha && remote.sha
? `${gh}/compare/${local.sha.slice(0, 12)}...${remote.sha.slice(0, 12)}`
: `${gh}/commits/${REPO.branch}`,
};
}
/* — the catalog: what could be installed or updated — */
function catalogView() {
const available = [];
const updates = [];
const hiddenBundled = readManifests(BUNDLED_MODULES_DIR, 'bundled').filter((m) => isUninstalled(m.id));
const seen = new Set();
for (const [id, entry] of remote.modules) {
const man = entry.manifest;
seen.add(id);
const requires = String(man.proddash || '').trim();
const compatible = satisfiesVersion(SHELL_VERSION, requires);
const base = {
id,
name: String(man.name || id),
version: String(man.version || ''),
description: String(man.description || ''),
requires,
compatible,
reason: compatible ? '' : requirementNote(requires),
};
const installed = manifests.get(id);
if (installed) {
if (compareVersions(man.version, installed.version) > 0) {
updates.push({ ...base, installedVersion: String(installed.version || ''), source: 'repo' });
}
} else {
const hidden = hiddenBundled.find((m) => m.id === id);
const useBundled = hidden && compareVersions(hidden.version, man.version) >= 0;
available.push({ ...base, source: useBundled ? 'bundled' : 'repo' });
}
}
for (const m of hiddenBundled) {
if (seen.has(m.id)) continue;
available.push({
id: m.id, name: String(m.name || m.id), version: String(m.version || ''), description: String(m.description || ''),
requires: m.requires, compatible: !m.incompatible, reason: m.incompatible, source: 'bundled',
});
}
const byName = (a, b) => a.name.localeCompare(b.name);
return { available: available.sort(byName), updates: updates.sort(byName) };
}
/** Install (or update) a module from the repo, or bring back a bundled one. */
async function installModule(id) {
if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) throw httpError(400, 'Bad module id.');
await refreshRemote(false);
const remoteEntry = remote.modules.get(id) || null;
const bundledMan = readManifests(BUNDLED_MODULES_DIR, 'bundled').find((m) => m.id === id) || null;
const installedMan = readManifests(INSTALLED_MODULES_DIR, 'installed').find((m) => m.id === id) || null;
if (!remoteEntry && !bundledMan && !installedMan) {
throw httpError(404, remote.error
? `"${id}" is not here and the repo could not be reached: ${remote.error}`
: `"${id}" is not in ${REPO.owner}/${REPO.repo}.`);
}
// End up with the newest copy: what the repo offers vs what is already here.
const haveVersion = installedMan?.version || bundledMan?.version || '';
const download = Boolean(remoteEntry) && (!(bundledMan || installedMan) || compareVersions(remoteEntry.manifest.version, haveVersion) > 0);
const man = download ? remoteEntry.manifest : (installedMan || bundledMan);
const requires = String(man.proddash || '').trim();
if (!satisfiesVersion(SHELL_VERSION, requires)) {
throw httpError(409, `${man.name || id} ${requirementNote(requires).replace('Requires', 'requires')}. Update ProdDash first.`);
}
if (download) {
const staging = path.join(INSTALLED_MODULES_DIR, `.${id}.installing`);
fs.rmSync(staging, { recursive: true, force: true });
for (const [rel, data] of remoteEntry.files) {
if (!safeRelPath(rel)) continue;
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);
unmountModule(id);
fs.rmSync(dest, { recursive: true, force: true });
fs.renameSync(staging, dest);
}
const state = { ...moduleState(id) };
delete state.uninstalled;
modulesConfig[id] = state;
writeJson(MODULES_CONFIG_PATH, modulesConfig);
discoverModules();
remountModule(id);
broadcastShellEvent('modules-changed', { id });
const now = manifests.get(id);
console.log(`[proddash] ${download ? 'installed' : 'restored'} module "${id}" v${now?.version || '?'} (${now?.source || 'unknown'})`);
return { id, version: String(now?.version || ''), source: now?.source || '', downloaded: download };
}
/** 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. */
function uninstallModule(id) {
if (!/^[a-z0-9][a-z0-9-]*$/.test(id)) throw httpError(400, 'Bad module id.');
const installedDir = path.join(INSTALLED_MODULES_DIR, id);
const hadInstalled = fs.existsSync(path.join(installedDir, 'module.json'));
const hasBundled = fs.existsSync(path.join(BUNDLED_MODULES_DIR, id, 'module.json'));
if (!manifests.has(id) && !hadInstalled && !hasBundled) throw httpError(404, `No module "${id}" is installed.`);
unmountModule(id);
if (hadInstalled) fs.rmSync(installedDir, { recursive: true, force: true });
modulesConfig[id] = { ...moduleState(id), uninstalled: true };
writeJson(MODULES_CONFIG_PATH, modulesConfig);
discoverModules();
broadcastShellEvent('modules-changed', { id });
console.log(`[proddash] uninstalled module "${id}"${hadInstalled ? ' (files removed)' : ''}${hasBundled ? ' (bundled copy hidden)' : ''}`);
return { id, removedFiles: hadInstalled, bundled: hasBundled };
}
/* — updating the shell itself — */
function copyTree(src, dst) {
fs.mkdirSync(dst, { recursive: true });
for (const e of fs.readdirSync(src, { withFileTypes: true })) {
const s = path.join(src, e.name);
const d = path.join(dst, e.name);
if (e.isDirectory()) copyTree(s, d);
else fs.copyFileSync(s, d);
}
}
/**
* Bring the app folder up to the repo's branch. A git checkout gets
* `git pull --ff-only`; anything else has the archive unpacked over it
* (runtime state and .git are never touched). The caller restarts.
*/
async function updateShell() {
await refreshRemote(true);
if (remote.error) throw httpError(502, `Couldn't reach ${REPO.owner}/${REPO.repo}: ${remote.error}`);
const status = shellStatus();
if (status.updateBlocker) throw httpError(409, `Can't update from here: ${status.updateBlocker}.`);
if (!status.updateAvailable) throw httpError(409, 'Already up to date.');
if (status.local.isGit) {
const out = git(['pull', '--ff-only', 'origin', REPO.branch], 120000);
console.log('[proddash] git pull:', out.split('\n').filter(Boolean).slice(-2).join(' | '));
} else {
const keep = (rel) => rel === 'config/modules.json' || rel.startsWith('config/layouts/') || rel.startsWith('.git/');
const staging = path.join(ROOT, '.proddash-update');
fs.rmSync(staging, { recursive: true, force: true });
for (const [rel, data] of remote.files) {
if (!safeRelPath(rel) || keep(rel)) continue;
const target = path.join(staging, rel);
fs.mkdirSync(path.dirname(target), { recursive: true });
fs.writeFileSync(target, data);
}
if (!fs.existsSync(path.join(staging, 'server.js'))) {
fs.rmSync(staging, { recursive: true, force: true });
throw httpError(502, 'The downloaded archive does not look like ProdDash (no server.js).');
}
copyTree(staging, ROOT);
fs.rmSync(staging, { recursive: true, force: true });
}
return { from: SHELL_VERSION, to: remote.version || '', method: status.method };
}
/**
* Exit so the new code runs. Exit code 75 tells a launcher loop to start us
* again; when nothing is supervising (PRODDASH_LAUNCHER unset) we start our
* own replacement, which waits for this port to free up.
*/
function restartServer(reason) {
console.log(`[proddash] ${reason} — restarting ProdDash`);
for (const id of [...mounted.keys()]) unmountModule(id);
let done = false;
const finish = () => {
if (done) return;
done = true;
if (!process.env.PRODDASH_LAUNCHER) {
try {
const child = spawn(process.execPath, process.argv.slice(1), {
cwd: process.cwd(), env: process.env, detached: true, stdio: 'inherit',
});
child.unref();
} catch (err) {
console.error('[proddash] could not start the new ProdDash — start it by hand:', err?.message || err);
}
}
process.exit(75);
};
server.close(finish);
setTimeout(finish, 1500).unref();
}
/* ── admin API ──────────────────────────────────────────────────────── */ /* ── admin API ──────────────────────────────────────────────────────── */
const ADMIN_PASSCODE = String(process.env.PRODDASH_PASSCODE || shellConfig.adminPasscode || ''); const ADMIN_PASSCODE = String(process.env.PRODDASH_PASSCODE || shellConfig.adminPasscode || '');
@@ -484,6 +969,9 @@ function adminModuleView(id) {
version: String(man.version || ''), version: String(man.version || ''),
description: String(man.description || ''), description: String(man.description || ''),
hasServer: Boolean(man.server), hasServer: Boolean(man.server),
source: man.source || 'bundled',
requires: man.requires || '',
incompatible: man.incompatible || '',
enabled: isEnabled(id), enabled: isEnabled(id),
configSchema: man.configSchema || {}, configSchema: man.configSchema || {},
configGroups: man.configGroups && typeof man.configGroups === 'object' ? man.configGroups : {}, configGroups: man.configGroups && typeof man.configGroups === 'object' ? man.configGroups : {},
@@ -548,11 +1036,51 @@ async function handleAdminApi(req, res, urlPath) {
return sendJson(res, 200, { return sendJson(res, 200, {
authRequired: Boolean(ADMIN_PASSCODE), authRequired: Boolean(ADMIN_PASSCODE),
authed: true, authed: true,
version: SHELL_VERSION,
dataDir: DATA_DIR, dataDir: DATA_DIR,
modules: [...manifests.keys()].sort().map(adminModuleView), modules: [...manifests.keys()].sort().map(adminModuleView),
}); });
} }
if (urlPath === '/api/admin/catalog' && req.method === 'GET') {
if (!isAuthed(req)) return sendJson(res, 401, { authRequired: true, authed: false });
const refresh = new URL(req.url, 'http://proddash.invalid').searchParams.get('refresh') === '1';
await refreshRemote(refresh);
return sendJson(res, 200, { shell: shellStatus(), ...catalogView() });
}
if (urlPath === '/api/admin/update' && req.method === 'POST') {
if (refuseAdminWrite(req, res)) return;
try {
const result = await updateShell();
sendJson(res, 200, { ok: true, ...result, restarting: true });
setTimeout(() => restartServer(`updated ${result.from} → ${result.to || 'latest'} via ${result.method}`), 400);
} catch (err) {
sendJson(res, err.status || 500, { error: err.message || String(err) });
}
return;
}
const install = urlPath.match(/^\/api\/admin\/modules\/([^/]+)\/install$/);
if (install && req.method === 'POST') {
if (refuseAdminWrite(req, res)) return;
try {
return sendJson(res, 200, { ok: true, ...(await installModule(decodeURIComponent(install[1]))) });
} catch (err) {
return sendJson(res, err.status || 500, { error: err.message || String(err) });
}
}
const remove = urlPath.match(/^\/api\/admin\/modules\/([^/]+)$/);
if (remove && req.method === 'DELETE') {
if (refuseAdminWrite(req, res)) return;
try {
return sendJson(res, 200, { ok: true, ...uninstallModule(decodeURIComponent(remove[1])) });
} catch (err) {
return sendJson(res, err.status || 500, { error: err.message || String(err) });
}
}
const m = urlPath.match(/^\/api\/admin\/modules\/([^/]+)\/(config|enabled)$/); const m = urlPath.match(/^\/api\/admin\/modules\/([^/]+)\/(config|enabled)$/);
if (m && req.method === 'PUT') { if (m && req.method === 'PUT') {
const id = decodeURIComponent(m[1]); const id = decodeURIComponent(m[1]);
@@ -712,6 +1240,7 @@ async function handleLayoutsApi(req, res, urlPath) {
function dispatchModuleApi(req, res, id, subPath, search) { function dispatchModuleApi(req, res, id, subPath, search) {
if (!manifests.has(id)) return sendJson(res, 404, { error: `No module "${id}" is installed.` }); if (!manifests.has(id)) return sendJson(res, 404, { error: `No module "${id}" is installed.` });
if (!isEnabled(id)) return sendJson(res, 404, { error: `Module "${id}" is disabled.` }); if (!isEnabled(id)) return sendJson(res, 404, { error: `Module "${id}" is disabled.` });
if (manifests.get(id).incompatible) return sendJson(res, 409, { error: manifests.get(id).incompatible });
const entry = mounted.get(id); const entry = mounted.get(id);
if (!entry) return sendJson(res, 503, { error: `Module "${id}" is not mounted.` }); if (!entry) return sendJson(res, 503, { error: `Module "${id}" is not mounted.` });
if (entry.error) return sendJson(res, 502, { error: `Module "${id}" failed to start: ${entry.error}` }); if (entry.error) return sendJson(res, 502, { error: `Module "${id}" failed to start: ${entry.error}` });
@@ -814,7 +1343,7 @@ function handleRequest(req, res) {
/* — shell API — */ /* — shell API — */
if (urlPath === '/api/modules' && req.method === 'GET') { if (urlPath === '/api/modules' && req.method === 'GET') {
Promise.all([...manifests.keys()].filter(isEnabled).map(clientManifest)) Promise.all([...manifests.keys()].filter(isActive).map(clientManifest))
.then((list) => sendJson(res, 200, { modules: list })) .then((list) => sendJson(res, 200, { modules: list }))
.catch((err) => { .catch((err) => {
console.error('[proddash] /api/modules failed:', err); console.error('[proddash] /api/modules failed:', err);
@@ -881,7 +1410,7 @@ function handleRequest(req, res) {
if (assetMatch) { if (assetMatch) {
const id = decodeURIComponent(assetMatch[1]); const id = decodeURIComponent(assetMatch[1]);
const man = manifests.get(id); const man = manifests.get(id);
if (!man || !isEnabled(id)) { if (!man || !isActive(id)) {
res.writeHead(404, { 'Content-Type': 'text/plain' }); res.writeHead(404, { 'Content-Type': 'text/plain' });
return res.end('Not found'); return res.end('Not found');
} }
@@ -912,8 +1441,8 @@ server.requestTimeout = 0;
discoverModules(); discoverModules();
mountAllModules(); mountAllModules();
server.listen(PORT, '0.0.0.0', () => { server.on('listening', () => {
console.log('ProdDash running'); console.log('ProdDash ' + SHELL_VERSION);
console.log(' Local : http://localhost:' + PORT); console.log(' Local : http://localhost:' + PORT);
for (const ifaces of Object.values(os.networkInterfaces())) { for (const ifaces of Object.values(os.networkInterfaces())) {
for (const iface of ifaces || []) { for (const iface of ifaces || []) {
@@ -924,11 +1453,34 @@ server.listen(PORT, '0.0.0.0', () => {
} }
const ids = [...manifests.keys()]; const ids = [...manifests.keys()];
console.log(ids.length console.log(ids.length
? ' Modules : ' + ids.map((id) => id + (isEnabled(id) ? '' : ' (disabled)')).join(', ') ? ' Modules : ' + ids.map((id) => id + (isEnabled(id) ? '' : ' (disabled)') + (manifests.get(id).incompatible ? ' (needs newer ProdDash)' : '')).join(', ')
: ' Modules : none installed'); : ' Modules : none installed');
console.log(' Settings : ' + DATA_DIR + (DATA_DIR === REPO_CONFIG_DIR ? ' (inside the app folder)' : '')); console.log(' Settings : ' + DATA_DIR + (DATA_DIR === REPO_CONFIG_DIR ? ' (inside the app folder)' : ''));
console.log(' Repo : ' + REPO.owner + '/' + REPO.repo + '@' + REPO.branch);
}); });
// A restart hands the port over from the exiting ProdDash: wait for it.
let listenTries = 0;
server.on('error', (err) => {
if (err.code === 'EADDRINUSE' && listenTries < 30) {
listenTries += 1;
if (listenTries === 1) console.log(`[proddash] port ${PORT} is busy — waiting for it (a previous ProdDash may still be shutting down)`);
setTimeout(() => server.listen(PORT, '0.0.0.0'), 500);
return;
}
console.error('[proddash] cannot start:', err.message || err);
process.exit(1);
});
server.listen(PORT, '0.0.0.0');
// Update check: shortly after boot, then every few hours (the admin page
// shows the result; nothing is installed without someone clicking).
if (!process.env.PRODDASH_NO_REMOTE_CHECK) {
setTimeout(() => refreshRemote(false).catch(() => {}), 20000).unref();
setInterval(() => refreshRemote(true).catch(() => {}), REMOTE_CHECK_MS).unref();
}
for (const signal of ['SIGINT', 'SIGTERM']) { for (const signal of ['SIGINT', 'SIGTERM']) {
process.on(signal, () => { process.on(signal, () => {
for (const id of [...mounted.keys()]) unmountModule(id); for (const id of [...mounted.keys()]) unmountModule(id);
tools/pp-timers-mock.js
+139 -1
View File
@@ -4,6 +4,7 @@
* band-lineup-display/tmp/pp-mock.js simulates slides, not timers). * band-lineup-display/tmp/pp-mock.js simulates slides, not timers).
* *
* node tools/pp-timers-mock.js [port] [--no-ltc] [--drop=<uuid,...>] * node tools/pp-timers-mock.js [port] [--no-ltc] [--drop=<uuid,...>]
* [--stage-pwd=<pwd>] [--no-ltc-field]
* *
* Serves the endpoint shapes verified against openapi.propresenter.com: * Serves the endpoint shapes verified against openapi.propresenter.com:
* GET /version (reachability probe) * GET /version (reachability probe)
@@ -23,6 +24,16 @@
* the mock with e.g. --drop=T2-WALKIN to simulate a timer being deleted in * the mock with e.g. --drop=T2-WALKIN to simulate a timer being deleted in
* ProPresenter (a solo tile for it must say so, not error). * ProPresenter (a solo tile for it must say so, not error).
* *
* Also serves the classic stage-display websocket at /stagedisplay (the
* Pro6-era protocol ProPresenter still answers): ath / psl / asl / sl, a
* per-second "sys" clock, and "tmr" text updates — including a stage layout
* with a field labeled "LTC" whose text advances at 30 fps and freezes
* during the same 15 s/60 s no-signal window as the HTTP endpoint. Combine
* with --no-ltc to make the stage feed the only timecode source (the module
* prefers the HTTP route when it answers). --stage-pwd=<pwd> rejects other
* stage passwords ("Your Password is incorrect", as real ProPresenter says);
* --no-ltc-field serves the stage layout without the LTC field.
*
* Every incoming request is logged so we can confirm what the module fetches. * Every incoming request is logged so we can confirm what the module fetches.
*/ */
'use strict'; 'use strict';
@@ -33,6 +44,11 @@ const args = process.argv.slice(2);
const PORT = Number.parseInt(args.find((a) => /^\d+$/.test(a)) || '1600', 10); const PORT = Number.parseInt(args.find((a) => /^\d+$/.test(a)) || '1600', 10);
const NO_LTC = args.includes('--no-ltc'); const NO_LTC = args.includes('--no-ltc');
const DROP = new Set(args.flatMap((a) => (a.startsWith('--drop=') ? a.slice(7).split(',') : []))); const DROP = new Set(args.flatMap((a) => (a.startsWith('--drop=') ? a.slice(7).split(',') : [])));
const STAGE_PWD = (args.find((a) => a.startsWith('--stage-pwd=')) || '').slice(12);
const NO_LTC_FIELD = args.includes('--no-ltc-field');
// Like real ProPresenter 21: the layout list omits the timecode field, but
// its updates still stream — exercises the module's heuristic binding.
const LTC_UNLISTED = args.includes('--ltc-unlisted');
const FPS = 30; const FPS = 30;
const startedAt = Date.now(); const startedAt = Date.now();
@@ -140,6 +156,128 @@ const server = http.createServer((req, res) => {
sendJson(res, { error: 'not found' }, 404); sendJson(res, { error: 'not found' }, 404);
}); });
/* ── stage-display websocket (/stagedisplay) ─────────────────────── */
const cryptoMod = require('crypto');
const WS_MAGIC = '258EAFA5-E914-47DA-95CA-C5AB0DC85B11';
const STAGE_LAYOUT = {
acn: 'sl',
uid: 'MOCK-LAYOUT-1',
nme: 'Timers',
fme: [
{ nme: 'Current Slide', typ: 1 },
...(NO_LTC_FIELD || LTC_UNLISTED ? [] : [{ nme: 'LTC', typ: 7, uid: 'LTC-FIELD' }]),
{ nme: 'Sermon Countdown', typ: 7, uid: 'T1-SERMON' },
],
};
/** Server→client frames are unmasked. Text only — plenty for this protocol. */
function wsEncode(str) {
const p = Buffer.from(str);
let h;
if (p.length < 126) {
h = Buffer.from([0x81, p.length]);
} else {
h = Buffer.alloc(4);
h[0] = 0x81;
h[1] = 126;
h.writeUInt16BE(p.length, 2);
}
return Buffer.concat([h, p]);
}
server.on('upgrade', (req, socket) => {
if (new URL(req.url, 'http://x').pathname !== '/stagedisplay') return void socket.destroy();
const key = req.headers['sec-websocket-key'];
if (!key) return void socket.destroy();
console.log('[pp-timers-mock] stage display client connected');
const accept = cryptoMod.createHash('sha1').update(key + WS_MAGIC).digest('base64');
socket.write(
'HTTP/1.1 101 Switching Protocols\r\nUpgrade: websocket\r\nConnection: Upgrade\r\n' +
`Sec-WebSocket-Accept: ${accept}\r\n\r\n`);
const send = (obj) => {
try { socket.write(wsEncode(JSON.stringify(obj))); } catch { /* gone */ }
};
let authed = false;
let buf = Buffer.alloc(0);
let lastLtcText = '';
const sysTimer = setInterval(() => {
if (authed) send({ acn: 'sys', txt: ' ' + new Date().toLocaleTimeString() });
}, 1000);
const tmrTimer = setInterval(() => {
if (!authed) return;
// noise a client must filter out: an ordinary timer's text
send({ acn: 'tmr', uid: 'T1-SERMON', txt: hms(Math.max(0, 25 * 60 - elapsedSec())) });
}, 1000);
const ltcTimer = setInterval(() => {
if (!authed || NO_LTC_FIELD) return;
const tc = timecodeStatus();
// During no-signal the on-stage field is frozen: no updates at all —
// exactly what the module's staleness heuristic must catch.
if (!tc.receiving || tc.time === lastLtcText) return;
lastLtcText = tc.time;
send({ acn: 'tmr', uid: 'LTC-FIELD', txt: tc.time });
}, 250);
socket.on('data', (chunk) => {
buf = Buffer.concat([buf, chunk]);
while (buf.length >= 2) {
const opcode = buf[0] & 0x0f;
const masked = (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 = masked ? 4 : 0;
if (buf.length < off + maskLen + len) return;
let payload = buf.slice(off + maskLen, off + maskLen + len);
if (masked) {
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 === 0x8) return void socket.destroy();
if (opcode === 0x9) { socket.write(Buffer.concat([Buffer.from([0x8a, payload.length]), payload])); continue; }
if (opcode !== 0x1) continue;
let msg;
try { msg = JSON.parse(payload.toString()); } catch { continue; }
console.log('[pp-timers-mock] stage <-', JSON.stringify(msg).slice(0, 120));
if (msg.acn === 'ath') {
if (STAGE_PWD && String(msg.pwd || '') !== STAGE_PWD) {
send({ acn: 'ath', ath: false, majorVersion: 7, minorVersion: 21, err: 'Your Password is incorrect' });
} else {
authed = true;
send({ acn: 'ath', ath: true, err: '' });
}
} else if (msg.acn === 'psl') {
send({ acn: 'psl', uid: 'MOCK-LAYOUT-1' });
} else if (msg.acn === 'asl') {
send({ acn: 'asl', ary: [STAGE_LAYOUT] });
}
}
});
const cleanup = () => {
clearInterval(sysTimer);
clearInterval(tmrTimer);
clearInterval(ltcTimer);
};
socket.on('close', cleanup);
socket.on('error', () => { cleanup(); socket.destroy(); });
});
server.listen(PORT, () => { server.listen(PORT, () => {
console.log(`[pp-timers-mock] listening on http://127.0.0.1:${PORT}${NO_LTC ? ' (timecode endpoint disabled)' : ''}`); console.log(`[pp-timers-mock] listening on http://127.0.0.1:${PORT}${NO_LTC ? ' (timecode endpoint disabled)' : ''}${NO_LTC_FIELD ? ' (stage layout has no LTC field)' : ''}${STAGE_PWD ? ' (stage password required)' : ''}`);
}); });