merging-ravenna 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Robbetts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# merging-ravenna
+
+A small, standalone Node.js client for **Merging Technologies** RAVENNA devices
+(Hapi, Horus, Anubis) that speaks their web-UI control protocol — CometD/Bayeux
+over WebSocket — directly. No Node-RED, no browser, no extra services.
+
+> **Unofficial.** This library was built by observing the device's own web
+> interface traffic. It is **not affiliated with or endorsed by Merging
+> Technologies**, and the protocol is undocumented and may change between
+> firmware versions. Use at your own risk; always keep a way to restore settings.
+
+## Install
+
+```sh
+npm install merging-ravenna
+```
+
+## Quick start
+
+```js
+const { RavennaEngine } = require('merging-ravenna');
+
+const eng = new RavennaEngine({ host: '192.168.0.146' });
+
+eng.on('online',  () => console.log('device up; catalog:', eng.catalog.length, 'params'));
+eng.on('offline', (reason) => console.log('device down:', reason));
+eng.on('param',   (p) => console.log('changed', p.moduleId, p.key, '=', p.value));
+
+eng.connect();
+
+// Set D/A (module 60) output gain to -20 dB. Value is dB; clamped to device range.
+eng.setParam(60, 'attenuation', -20);
+```
+
+## Why it is resilient
+
+The engine handles two failure modes differently:
+
+- **Socket drop / device powered off** → exponential-backoff reconnect
+  (`2s, 5s, 15s, 30s` capped), retrying forever.
+- **Device wedged but socket still open** → a **data-liveness watchdog**: the
+  device emits `/ravenna/status` about every 2s, so if no frame arrives within
+  `livenessMs` (default 7s) the connection is declared stale, torn down, and
+  re-established.
+
+`online` / `offline` are **edge-triggered** (emitted once per transition), and
+every successful (re)connect re-runs the handshake and full state fetch — so
+after a power-cycle (which rotates the device's `clientId`), state is always
+re-read from the device rather than assumed.
+
+## Discovery
+
+On every full state update the engine builds a flat **catalog** of settable
+parameters by reading the device's own capability metadata — so it enumerates
+whatever modules/cards a given Hapi/Horus/Anubis actually has:
+
+```js
+eng.on('catalog', (cat) => {
+  // [{ moduleId, moduleName, section, key, value, unit, min, max, step, enum, settable, confidence }, ...]
+});
+```
+
+`confidence` is `confirmed` (set-frame verified on a real device), `inferred`
+(derived from the state shape; very likely correct), or `unknown`.
+
+## API (summary)
+
+- `new RavennaEngine({ host, path?, livenessMs?, backoff? })`
+- `.connect()`, `.close()`
+- `.setParam(moduleId, key, value, { channelIndex? })` — high-level, unit-aware, clamped
+- `.setModuleOuts(moduleId, valueObj)` — mid-level
+- `.publishSettings(path, value)` — raw escape hatch
+- `.catalog`, `.tree`, `.capabilities`, `.online`
+- events: `online, offline, status, settings, statusmsg, errors, tree, catalog, param, error`
+
+## Testing
+
+```sh
+npm test            # hermetic: catalog + watchdog + meter + feedback logic, no device needed
+MERGING_HOST=192.168.0.150 npm run validate                       # read-only: discover catalog + write a JSON report
+MERGING_HOST=192.168.0.150 MERGING_I_UNDERSTAND=1 npm run validate # write-validate (audio OFF): set->re-read every param, restore
+```
+
+The hermetic suite includes a fake-clock watchdog test that simulates a power
+cycle and asserts the backoff schedule and the single online/offline transitions.
+`npm run validate` (`scripts/validate-device.js`) discovers every settable parameter,
+and — with `MERGING_I_UNDERSTAND=1`, audio off — validates each by SET→RE-READ: it
+sets the value, re-reads the device to confirm it applied, restores the original, and
+writes a JSON report (device fingerprint, per-param verdicts, unmodeled leaves) you can
+share. A meter pre-flight gate aborts if any output is passing audio.
+
+## Extending to new parameters / devices
+
+Confirmed and inferred set-frame shapes live in `src/paths.js`. To add a parameter
+(or support an Anubis monitor control), capture one set frame from the device web UI
+and add a descriptor there — no engine changes needed.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,14 @@
+'use strict';
+
+const { RavennaEngine } = require('./src/engine');
+const { buildCatalog, groupByModule } = require('./src/catalog');
+const { KNOWN, checkCompat, describeCompat } = require('./src/compat');
+const paths = require('./src/paths');
+
+module.exports = {
+  RavennaEngine,
+  buildCatalog,
+  groupByModule,
+  paths,
+  compat: { KNOWN, checkCompat, describeCompat }
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "merging-ravenna",
+  "version": "0.1.0",
+  "description": "Standalone client for Merging Technologies RAVENNA devices (Hapi / Horus / Anubis) over their CometD/WebSocket control protocol. Unofficial; not affiliated with Merging Technologies.",
+  "keywords": [
+    "merging",
+    "ravenna",
+    "aes67",
+    "hapi",
+    "horus",
+    "anubis",
+    "cometd",
+    "bayeux"
+  ],
+  "license": "MIT",
+  "author": "Matthew Robbetts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrobbetts/merging_ravenna.git"
+  },
+  "main": "index.js",
+  "type": "commonjs",
+  "files": [
+    "index.js",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "validate": "node scripts/validate-device.js"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,137 @@
+'use strict';
+
+const { moduleOutsPath, moduleInsPath, PARAMS, tenthsToDb } = require('./paths');
+
+/**
+ * buildCatalog(tree)
+ * ------------------
+ * Walk a full device state tree (the value of a path:"$" update) and produce a
+ * FLAT array of parameter entries, each carrying enough metadata to group back
+ * into a tree, drive a dropdown, or feed a Stream Deck.
+ *
+ * This is intentionally GENERIC: it reads whatever modules exist and whatever
+ * capabilities they advertise, so it enumerates a Hapi's D/A and mic-pre cards,
+ * a Horus's banks, or an Anubis's monitor section without hardcoded knowledge.
+ *
+ * Entry shape:
+ * {
+ *   moduleId, moduleName, moduleType, moduleSubType,
+ *   section: 'outs'|'ins',
+ *   key,                // e.g. 'attenuation', 'mute', 'roll_off_filter'
+ *   path,               // device JSONPath to the section object
+ *   value,              // current value (dB for tenths-db params, else raw)
+ *   raw,                // raw stored value (tenths for db params)
+ *   unit,               // 'dB'|'bool'|'enum'|'int'
+ *   min, max, step,     // numeric range where advertised (in display units)
+ *   enum,               // { label: intValue } for enum params, else null
+ *   channelCount,       // for per-channel params
+ *   settable,           // true only where we have a confirmed/inferred setter
+ *   confidence          // 'confirmed'|'inferred'|'unknown'
+ * }
+ */
+function buildCatalog(tree) {
+  const out = [];
+  const mods = tree && tree._modules;
+  if (!Array.isArray(mods)) return out;
+
+  for (const m of mods) {
+    const custom = m && m.custom;
+    if (!custom) continue;
+
+    for (const section of ['outs', 'ins']) {
+      const sec = custom[section];
+      if (!sec) continue;
+      const caps = sec.capabilities || {};
+      const path = section === 'outs' ? moduleOutsPath(m.id) : moduleInsPath(m.id);
+      const channelCount = Array.isArray(sec.channels) ? sec.channels.length : undefined;
+
+      const base = {
+        moduleId: m.id,
+        moduleName: m.name || null,
+        moduleType: m.type,
+        moduleSubType: m.sub_type,
+        section,
+        path,
+        channelCount
+      };
+
+      // attenuation (gain/volume)
+      if (typeof sec.attenuation === 'number' && caps.attenuation) {
+        const info = caps.attenuation_info || {};
+        out.push(Object.assign({}, base, {
+          key: 'attenuation',
+          raw: sec.attenuation,
+          value: tenthsToDb(sec.attenuation),
+          unit: 'dB',
+          min: info.min != null ? tenthsToDb(info.min) : null,
+          max: info.max != null ? tenthsToDb(info.max) : null,
+          step: info.step != null ? tenthsToDb(info.step) : null,
+          enum: null,
+          settable: true,
+          confidence: PARAMS.attenuation.confidence
+        }));
+      }
+
+      // mute
+      if (typeof sec.mute === 'boolean' && caps.mute) {
+        out.push(Object.assign({}, base, {
+          key: 'mute', raw: sec.mute, value: sec.mute, unit: 'bool',
+          min: null, max: null, step: null, enum: null,
+          settable: true, confidence: PARAMS.mute.confidence
+        }));
+      }
+
+      // roll-off filter (enum)
+      if (typeof sec.roll_off_filter === 'number' && caps.roll_off_filter) {
+        out.push(Object.assign({}, base, {
+          key: 'roll_off_filter', raw: sec.roll_off_filter, value: sec.roll_off_filter,
+          unit: 'enum', min: null, max: null, step: null,
+          enum: caps.roll_off_filters || null,
+          settable: true, confidence: PARAMS.roll_off_filter.confidence
+        }));
+      }
+
+      // out max level
+      if (typeof sec.out_max_level === 'number' && caps.out_max_level) {
+        out.push(Object.assign({}, base, {
+          key: 'out_max_level', raw: sec.out_max_level, value: sec.out_max_level,
+          unit: 'int', min: null, max: null, step: null, enum: null,
+          settable: true, confidence: PARAMS.out_max_level.confidence
+        }));
+      }
+
+      // per-channel trim
+      if (Array.isArray(sec.channels) && caps.channel && caps.channel.trim) {
+        const info = (caps.channel && caps.channel.trim_info) || {};
+        sec.channels.forEach((ch, idx) => {
+          if (ch && typeof ch.trim === 'number') {
+            out.push(Object.assign({}, base, {
+              key: 'channel_trim', channelIndex: idx,
+              raw: ch.trim, value: tenthsToDb(ch.trim), unit: 'dB',
+              min: info.min != null ? tenthsToDb(info.min) : null,
+              max: info.max != null ? tenthsToDb(info.max) : null,
+              step: info.step != null ? tenthsToDb(info.step) : null,
+              enum: null,
+              settable: true, confidence: PARAMS.channel_trim.confidence
+            }));
+          }
+        });
+      }
+    }
+  }
+  return out;
+}
+
+/** Convenience: catalog grouped by module, for tree-style display. */
+function groupByModule(catalog) {
+  const map = new Map();
+  for (const e of catalog) {
+    if (!map.has(e.moduleId)) {
+      map.set(e.moduleId, { moduleId: e.moduleId, moduleName: e.moduleName, moduleType: e.moduleType, params: [] });
+    }
+    map.get(e.moduleId).params.push(e);
+  }
+  return Array.from(map.values());
+}
+
+module.exports = { buildCatalog, groupByModule };

package/src/compat.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * compat.js
+ * ---------
+ * Known-good device/firmware fingerprints. The control protocol is undocumented
+ * and could change between firmware releases, so we record which combinations
+ * have actually been validated and warn when we see something we haven't.
+ *
+ * Matching is GENERATION-AWARE on purpose: Merging ships frequent point builds,
+ * and we don't want a scary warning on every new b-number within a firmware
+ * generation whose protocol we've already confirmed. A new *generation* or a new
+ * *product*, on the other hand, is a real "be careful" signal.
+ *
+ * Levels returned by checkCompat():
+ *   'known-good'        exact product + generation + firmware version validated
+ *   'known-generation'  product + generation match; different point release (likely fine)
+ *   'unknown-generation' product matches but generation not seen (caution)
+ *   'unknown'           product never seen (high caution)
+ *
+ * `confirmedShapes` documents which parameter SET shapes we have actually verified
+ * on this fingerprint (vs. merely inferred), so tools can be honest about it.
+ */
+
+const KNOWN = [
+  {
+    product: 'HAPI_MkII',
+    firmwareGeneration: 2,
+    firmwareVersions: ['1.9.0b62872'],
+    status: 'verified',
+    // serial recorded only as provenance of where validation happened
+    validatedOn: 'maintainer unit (serial H96149, D/A card sub_type 218, hw run 14)',
+    confirmedShapes: ['attenuation', 'mute', 'roll_off_filter', 'out_max_level', 'channel_trim'],
+    inferredShapes: [],
+    notes: 'All five out-param set-shapes confirmed on hardware: attenuation from captured web-UI frames; mute/roll_off_filter/out_max_level/channel_trim via active set->re-read (scripts/set-probe.js, 2026-06-05). Note the device echoes non-attenuation changes at the module-root path, not .custom.outs.'
+  }
+];
+
+function checkCompat(tree) {
+  const product = (tree && tree.identity && tree.identity.product) || null;
+  const fw = (tree && tree._firmware_version) || null;
+  const gen = (tree && tree._firmware_generation != null) ? tree._firmware_generation : null;
+
+  const result = { level: 'unknown', product, firmware: fw, generation: gen, entry: null };
+
+  const genMatch = KNOWN.find((k) => k.product === product && k.firmwareGeneration === gen);
+  if (genMatch) {
+    result.entry = genMatch;
+    result.level = genMatch.firmwareVersions.includes(fw) ? 'known-good' : 'known-generation';
+    return result;
+  }
+  const productMatch = KNOWN.find((k) => k.product === product);
+  if (productMatch) {
+    result.entry = productMatch;
+    result.level = 'unknown-generation';
+    return result;
+  }
+  return result;
+}
+
+/** Human-readable one-liner for logs / status tooltips. */
+function describeCompat(c) {
+  const base = `${c.product || 'unknown product'} fw ${c.firmware || '?'} (gen ${c.generation == null ? '?' : c.generation})`;
+  switch (c.level) {
+    case 'known-good': return `KNOWN-GOOD: ${base} — validated.`;
+    case 'known-generation': return `KNOWN-GENERATION: ${base} — same generation as a validated build; protocol almost certainly identical.`;
+    case 'unknown-generation': return `UNKNOWN-GENERATION: ${base} — product known but this firmware generation has not been validated. Proceed with caution.`;
+    default: return `UNKNOWN: ${base} — this device/firmware has never been validated with this tool. Shapes are unverified.`;
+  }
+}
+
+module.exports = { KNOWN, checkCompat, describeCompat };

package/src/engine.js

@@ -0,0 +1,499 @@
+'use strict';
+
+const EventEmitter = require('events');
+const WebSocket = require('ws');
+const { buildCatalog } = require('./catalog');
+const { checkCompat } = require('./compat');
+const { moduleOutsPath, PARAMS, dbToTenths } = require('./paths');
+
+/**
+ * RavennaEngine
+ * -------------
+ * One resilient CometD (Bayeux) session to a Merging RAVENNA device over WebSocket.
+ *
+ * Resilience model (two distinct failure modes, handled differently):
+ *  - socket drop / device power-off  -> exponential backoff reconnect, forever
+ *  - device wedged but socket "open" -> data-liveness watchdog: if no frame
+ *    arrives within `livenessMs`, declare stale, tear down, fall into backoff.
+ *
+ * The device emits /ravenna/status roughly every 2 s, so silence beyond ~7 s
+ * is a reliable "gone" signal.
+ *
+ * online/offline are emitted ONCE PER TRANSITION (edge-triggered), so consumers
+ * (e.g. a Stream Deck display) can react without being spammed.
+ *
+ * Events:
+ *   'online'   ()          device reachable AND full state received
+ *   'offline'  (reason)    device unreachable/stale; reason: 'timeout'|'closed'|'connect-failed'
+ *   'status'   (str)       fine-grained: 'starting'|'open'|'handshaking'|'connected'|'stale'|'reconnecting'
+ *   'settings' (data)      a /ravenna/settings broadcast { path, value }
+ *   'statusmsg'(data)      a /ravenna/status broadcast { path, value }
+ *   'errors'   (data)      a /ravenna/errors broadcast
+ *   'tree'     (tree)      full state tree (path:"$")
+ *   'catalog'  (array)     flattened parameter catalog (rebuilt on every tree)
+ *   'param'    (entry)     a single changed parameter we could resolve from a settings echo
+ *   'error'    (Error)
+ */
+class RavennaEngine extends EventEmitter {
+  constructor(opts = {}) {
+    super();
+    const host = opts.host || '127.0.0.1';
+    const path = opts.path || '/cometd/handshake';
+    this.url = opts.url || `ws://${host}${path}`;
+    this.origin = opts.origin || `http://${host}`;
+    this.host = host;
+
+    this.livenessMs = opts.livenessMs || 7000;          // staleness window
+    this.backoff = opts.backoff || [2000, 5000, 15000, 30000]; // capped schedule
+    this._backoffIdx = 0;
+
+    // Meter calibration. The level integers are CONFIRMED linear amplitude
+    // (see meterLevelsFor / dbFromLevel). `meterFullScale` is the integer that
+    // maps to 0 dBFS: CONFIRMED 65535 (2^16-1, 16-bit unsigned) by feeding a 0 dBFS
+    // tone to a RAVENNA input (meter read 65534). Overridable for other hardware.
+    this.meterFullScale = opts.meterFullScale || 65535;
+
+    // injectable for tests
+    this._WebSocket = opts.WebSocket || WebSocket;
+    this._setTimeout = opts.setTimeout || setTimeout;
+    this._clearTimeout = opts.clearTimeout || clearTimeout;
+
+    this.ws = null;
+    this.clientId = null;
+    this.msgId = 0;
+    this.online = false;          // public: device reachable + state known
+    this._closing = false;
+    this._reconnectTimer = null;
+    this._livenessTimer = null;
+
+    this.tree = null;
+    this.catalog = [];
+    this.capabilities = {};
+    this.compat = null;
+  }
+
+  // ---- lifecycle ----------------------------------------------------------
+
+  connect() {
+    this._closing = false;
+    this._backoffIdx = 0;
+    this.emit('status', 'starting');
+    this._open();
+  }
+
+  close() {
+    this._closing = true;
+    this._clearReconnect();
+    this._clearLiveness();
+    try { if (this.ws) this.ws.close(); } catch (e) { /* ignore */ }
+    this._goOffline('closed');
+  }
+
+  // ---- low-level send -----------------------------------------------------
+
+  _nextId() { return String(++this.msgId); }
+
+  _send(arr) {
+    try {
+      if (this.ws && this.ws.readyState === this._WebSocket.OPEN) {
+        this.ws.send(JSON.stringify(arr));
+      }
+    } catch (e) { this.emit('error', e); }
+  }
+
+  // ---- CometD steps -------------------------------------------------------
+
+  _handshake() {
+    this.emit('status', 'handshaking');
+    this._send([{
+      version: '1.0', minimumVersion: '0.9', channel: '/meta/handshake',
+      supportedConnectionTypes: ['websocket', 'long-polling', 'callback-polling'],
+      advice: { timeout: 60000, interval: 0 }, id: this._nextId()
+    }]);
+  }
+
+  _connectLoop() {
+    if (!this.clientId) return;
+    this._send([{ channel: '/meta/connect', connectionType: 'websocket', id: this._nextId(), clientId: this.clientId }]);
+  }
+
+  _subscribeAndSync() {
+    this._send([
+      { channel: '/meta/subscribe', subscription: '/ravenna/settings', id: this._nextId(), clientId: this.clientId },
+      { channel: '/meta/subscribe', subscription: '/ravenna/status', id: this._nextId(), clientId: this.clientId },
+      { channel: '/meta/subscribe', subscription: '/ravenna/errors', id: this._nextId(), clientId: this.clientId },
+      { channel: '/service/ravenna/commands', data: { command: 'update' }, id: this._nextId(), clientId: this.clientId }
+    ]);
+  }
+
+  // ---- public control -----------------------------------------------------
+
+  /** Publish a raw { path, value } settings change. */
+  publishSettings(path, value) {
+    if (!this.clientId) return false;
+    this._send([{ channel: '/service/ravenna/settings', data: { path, value }, id: this._nextId(), clientId: this.clientId }]);
+    return true;
+  }
+
+  /** Publish a value object to a module's outs. */
+  setModuleOuts(moduleId, valueObj) {
+    return this.publishSettings(moduleOutsPath(moduleId), valueObj);
+  }
+
+  /** Ask the device to re-send the full state tree (fires a 'tree' event when it arrives). */
+  requestUpdate() {
+    if (!this.clientId) return false;
+    this._send([{ channel: '/service/ravenna/commands', data: { command: 'update' }, id: this._nextId(), clientId: this.clientId }]);
+    return true;
+  }
+
+  /**
+   * Pull the per-channel level array for one module out of a /ravenna/meter frame.
+   * Frame shape (confirmed from capture): data.value.state._modules is an array of
+   * { id, type, meters: { ins?: {levels,levels_hold}, outs?: {levels,levels_hold} } }.
+   * `levels` are non-negative integers; 0 == digital black.
+   *
+   * The integers are CONFIRMED to be LINEAR amplitude (not dB, not power). This was
+   * proven from a live capture: the D/A (id 60, attenuation -40.0 dB) output meter
+   * reads exactly floor(StreamInput * 0.01) channel-by-channel and frame-by-frame
+   * (e.g. holds [19538,7074,18158,7086] -> [195,70,181,70]). The -40 dB attenuation
+   * is a built-in known reference that fixes the slope: dB = 20*log10(level/fullScale).
+   *
+   * @param field 'levels' (instantaneous, default) or 'levels_hold' (latched peak).
+   */
+  static meterLevelsFor(frame, moduleId, section = 'outs', field = 'levels') {
+    const mods = frame && frame.data && frame.data.value && frame.data.value.state
+      && frame.data.value.state._modules;
+    if (!Array.isArray(mods)) return null;
+    const mod = mods.find((m) => m && m.id === moduleId);
+    const sec = mod && mod.meters && mod.meters[section];
+    return (sec && Array.isArray(sec[field])) ? sec[field] : null;
+  }
+
+  /**
+   * Convert a linear meter level integer to dBFS.
+   * Slope/linearity and the 0 dBFS reference are both CONFIRMED: a 0 dBFS tone read
+   * 65534, so `fullScale` defaults to 65535 (2^16-1, 16-bit unsigned). Override for
+   * other hardware. Returns -Infinity for level <= 0 (digital black).
+   */
+  static dbFromLevel(level, fullScale = 65535) {
+    if (!(level > 0)) return -Infinity;
+    return 20 * Math.log10(level / fullScale);
+  }
+
+  /**
+   * Best-effort metering sample, used as a pre-write safety gate.
+   *
+   * Subscribes to the confirmed /ravenna/meter channel (auto-publishes ~every 100ms)
+   * and watches instantaneous `levels` for the gated module across the window. The
+   * go/no-go is based on instantaneous levels (currently-flowing audio), NOT
+   * `levels_hold`, which is a latched peak that can reflect audio from before the
+   * sample and would cause false aborts. The latched hold IS surfaced as `maxRawHold`
+   * for operator context ("a peak was here recently").
+   *
+   * Resolves: { confirmed, silent, maxRaw, maxRawHold, maxRawAnywhere, maxDb, fullScale, raw }
+   *   confirmed false -> no meter frame arrived; silent is null (callers MUST fail-safe)
+   *   confirmed true  -> silent === (maxRaw === 0); maxDb is the gated module peak in dBFS
+   */
+
+  sampleMeters(windowMs = 1500, { moduleId = 60, section = 'outs' } = {}) {
+    return new Promise((resolve) => {
+      const raw = [];
+      let maxForModule = 0;          // peak instantaneous integer for the gated module
+      let maxHoldForModule = 0;      // peak latched-hold integer for the gated module
+      let maxAnywhere = 0;           // peak instantaneous integer across ALL meters (informational)
+      let sawFrame = false;
+      const peakOf = (arr) => (Array.isArray(arr) ? arr.reduce((a, b) => (b > a ? b : a), 0) : 0);
+      const onRaw = (m) => {
+        if (!m || m.channel !== '/ravenna/meter') return;
+        sawFrame = true;
+        raw.push(m);
+        const mods = m.data && m.data.value && m.data.value.state && m.data.value.state._modules;
+        if (Array.isArray(mods)) {
+          for (const mod of mods) {
+            for (const sec of ['ins', 'outs']) {
+              const meters = mod && mod.meters && mod.meters[sec];
+              if (!meters) continue;
+              const peak = peakOf(meters.levels);
+              if (peak > maxAnywhere) maxAnywhere = peak;
+              if (mod.id === moduleId && sec === section) {
+                if (peak > maxForModule) maxForModule = peak;
+                const hold = peakOf(meters.levels_hold);
+                if (hold > maxHoldForModule) maxHoldForModule = hold;
+              }
+            }
+          }
+        }
+      };
+      this.on('raw', onRaw);
+
+      // Subscribe to the confirmed meter channel. auto_publish_vumeter is on by
+      // default, so frames should already be flowing once subscribed.
+      try {
+        if (this.clientId) {
+          this._send([{ channel: '/meta/subscribe', subscription: '/ravenna/meter', id: this._nextId(), clientId: this.clientId }]);
+        }
+      } catch (e) { /* ignore */ }
+
+      this._setTimeout(() => {
+        this.off('raw', onRaw);
+        if (!sawFrame) {
+          // No meter frames arrived -> cannot confirm silence. Fail safe.
+          resolve({ confirmed: false, silent: null, maxRaw: null, maxRawHold: null, maxRawAnywhere: null, maxDb: null, fullScale: this.meterFullScale, raw });
+          return;
+        }
+        resolve({
+          confirmed: true,
+          silent: maxForModule === 0,        // 0 == digital black; instantaneous decides go/no-go
+          maxRaw: maxForModule,              // peak instantaneous linear level for the gated module
+          maxRawHold: maxHoldForModule,      // latched peak-hold (may predate the sample; context only)
+          maxRawAnywhere: maxAnywhere,       // any other hot meter (e.g. live stream inputs)
+          maxDb: maxForModule > 0 ? RavennaEngine.dbFromLevel(maxForModule, this.meterFullScale) : null,
+          fullScale: this.meterFullScale,    // 0 dBFS reference (assumed 2^15; see dbFromLevel)
+          raw
+        });
+      }, windowMs);
+    });
+  }
+
+  /**
+   * High-level set by parameter name, using PARAMS descriptors.
+   * For 'tenths-db' params, pass dB; the library converts and clamps to caps.
+   * ctx may carry { channelIndex } for per-channel params.
+   */
+  setParam(moduleId, key, value, ctx = {}) {
+    const desc = PARAMS[key];
+    if (!desc) throw new Error(`Unknown parameter '${key}'`);
+
+    let v = value;
+    if (desc.unit === 'tenths-db') {
+      v = dbToTenths(value);
+      const cap = this._capFor(moduleId, key);
+      if (cap) v = Math.min(cap.max, Math.max(cap.min, v));   // clamp in tenths
+    }
+    const channelCount = this._channelCountFor(moduleId, desc.section);
+    const valueObj = desc.build(v, { channelCount, channelIndex: ctx.channelIndex || 0 });
+    const path = desc.section === 'ins'
+      ? require('./paths').moduleInsPath(moduleId)
+      : moduleOutsPath(moduleId);
+    return this.publishSettings(path, valueObj);
+  }
+
+  _capFor(moduleId, key) {
+    const c = this.capabilities[moduleId];
+    if (!c) return null;
+    if (key === 'attenuation') return c.attenuation || null;
+    if (key === 'channel_trim') return c.trim || null;
+    return null;
+  }
+
+  _channelCountFor(moduleId, section) {
+    if (!this.tree || !Array.isArray(this.tree._modules)) return 1;
+    const m = this.tree._modules.find((x) => x.id === moduleId);
+    const sec = m && m.custom && m.custom[section];
+    return (sec && Array.isArray(sec.channels)) ? sec.channels.length : 1;
+  }
+
+  // ---- inbound ------------------------------------------------------------
+
+  _ingestTree(tree) {
+    this.tree = tree;
+    this.capabilities = {};
+    this._outsCache = {};   // per-module last-known outs scalars, for change-detection in feedback echoes
+    if (Array.isArray(tree._modules)) {
+      for (const m of tree._modules) {
+        const outs = m && m.custom && m.custom.outs;
+        if (outs) this._outsCache[m.id] = this._snapshotOuts(outs);
+        const caps = outs && outs.capabilities;
+        if (caps) {
+          this.capabilities[m.id] = {
+            attenuation: caps.attenuation_info || null,
+            trim: (caps.channel && caps.channel.trim_info) || null,
+            mute: !!caps.mute,
+            rollOff: caps.roll_off_filters || null,
+            name: m.name || null
+          };
+        }
+      }
+    }
+    this.catalog = buildCatalog(tree);
+    this.compat = checkCompat(tree);
+    this.emit('tree', tree);
+    this.emit('catalog', this.catalog);
+    this.emit('compat', this.compat);
+  }
+
+  _handleMessage(m) {
+    this._kickLiveness(); // any frame = device alive
+    this.emit('raw', m);  // expose every frame (used by meter sampling / debugging)
+
+    const ch = m.channel;
+    if (ch === '/meta/handshake') {
+      if (m.successful && m.clientId) {
+        this.clientId = m.clientId;
+        this.emit('status', 'connected');
+        this._backoffIdx = 0;
+        this._subscribeAndSync();
+        this._connectLoop();
+      } else {
+        this._teardownAndReconnect('connect-failed');
+      }
+      return;
+    }
+    if (ch === '/meta/connect') {
+      if (m.successful) this._connectLoop();
+      else this._teardownAndReconnect('connect-failed');
+      return;
+    }
+    if (ch === '/meta/subscribe') return;
+
+    if (ch === '/ravenna/settings' || ch === '/ravenna/status') {
+      const d = m.data;
+      if (d && d.path === '$' && d.value) {
+        // Only /ravenna/settings carries the AUTHORITATIVE full tree (modules with
+        // custom/capabilities). The periodic /ravenna/status '$' is a REDUCED tree
+        // (modules carry only {state,id,type}); ingesting it would wipe capabilities
+        // and the catalog every ~2 s. So ingest from settings only — but either '$'
+        // is sufficient to declare the device reachable.
+        if (ch === '/ravenna/settings') this._ingestTree(d.value);
+        if (!this.online) { this.online = true; this.emit('online'); }
+      }
+      if (ch === '/ravenna/settings') {
+        this.emit('settings', d);
+        this._maybeEmitParam(d);
+      } else {
+        this.emit('statusmsg', d);
+      }
+      return;
+    }
+    if (ch === '/ravenna/errors') { this.emit('errors', m.data); }
+  }
+
+  /** Compact snapshot of an outs node's settable scalars, for change-detection. */
+  _snapshotOuts(o) {
+    return {
+      attenuation: typeof o.attenuation === 'number' ? o.attenuation : undefined,
+      mute: typeof o.mute === 'boolean' ? o.mute : undefined,
+      roll_off_filter: typeof o.roll_off_filter === 'number' ? o.roll_off_filter : undefined,
+      out_max_level: typeof o.out_max_level === 'number' ? o.out_max_level : undefined,
+      trims: Array.isArray(o.channels) ? o.channels.map((c) => (c && typeof c.trim === 'number' ? c.trim : undefined)) : undefined
+    };
+  }
+
+  // Resolve a /ravenna/settings echo into catalog-style param change event(s).
+  // The device echoes at TWO observed granularities (confirmed from a live capture):
+  //   - narrow:      $._modules[?(@.id==N)][0].custom.outs   value = { attenuation: -399 }
+  //                  (attenuation drives this path; value IS the outs delta)
+  //   - module-root: $._modules[?(@.id==N)][0]               value = { ...whole module..., custom:{outs:{...}} }
+  //                  (mute / roll_off_filter / out_max_level / trim from web UI or front panel)
+  // Either way we resolve the outs object and emit only keys that actually CHANGED
+  // vs the last-known value (so a full-module echo doesn't spam unchanged channels).
+  _maybeEmitParam(d) {
+    if (!d || !d.path || typeof d.value !== 'object' || d.value === null) return;
+    const m = /_modules\[\?\(@\.id==(\d+)\)\]\[0\](?:\.custom\.(outs|ins))?\s*$/.exec(d.path);
+    if (!m) return;
+    const moduleId = parseInt(m[1], 10);
+    let outs;
+    if (m[2] === 'outs') outs = d.value;                 // narrow outs echo: value is the delta
+    else if (m[2] === 'ins') return;                     // ins feedback not modeled yet
+    else { const c = d.value.custom; outs = c && c.outs; } // module-root echo: dig into custom.outs
+    if (!outs || typeof outs !== 'object') return;
+
+    if (!this._outsCache) this._outsCache = {};
+    const prev = this._outsCache[moduleId] || (this._outsCache[moduleId] = {});
+
+    if (typeof outs.attenuation === 'number' && outs.attenuation !== prev.attenuation) {
+      prev.attenuation = outs.attenuation;
+      this.emit('param', { moduleId, key: 'attenuation', raw: outs.attenuation, value: outs.attenuation / 10, unit: 'dB' });
+    }
+    if (typeof outs.mute === 'boolean' && outs.mute !== prev.mute) {
+      prev.mute = outs.mute;
+      this.emit('param', { moduleId, key: 'mute', raw: outs.mute, value: outs.mute, unit: 'bool' });
+    }
+    if (typeof outs.roll_off_filter === 'number' && outs.roll_off_filter !== prev.roll_off_filter) {
+      prev.roll_off_filter = outs.roll_off_filter;
+      this.emit('param', { moduleId, key: 'roll_off_filter', raw: outs.roll_off_filter, value: outs.roll_off_filter, unit: 'enum' });
+    }
+    if (typeof outs.out_max_level === 'number' && outs.out_max_level !== prev.out_max_level) {
+      prev.out_max_level = outs.out_max_level;
+      this.emit('param', { moduleId, key: 'out_max_level', raw: outs.out_max_level, value: outs.out_max_level, unit: 'int' });
+    }
+    if (Array.isArray(outs.channels)) {
+      if (!Array.isArray(prev.trims)) prev.trims = [];
+      outs.channels.forEach((c, i) => {
+        if (c && typeof c.trim === 'number' && c.trim !== prev.trims[i]) {
+          prev.trims[i] = c.trim;
+          this.emit('param', { moduleId, key: 'channel_trim', channelIndex: i, raw: c.trim, value: c.trim / 10, unit: 'dB' });
+        }
+      });
+    }
+  }
+
+  _onFrame(raw) {
+    let arr;
+    try { arr = JSON.parse(raw); } catch (e) { return; }
+    if (!Array.isArray(arr)) arr = [arr];
+    for (const m of arr) this._handleMessage(m);
+  }
+
+  // ---- watchdog & reconnect ----------------------------------------------
+
+  _kickLiveness() {
+    this._clearLiveness();
+    this._livenessTimer = this._setTimeout(() => {
+      this.emit('status', 'stale');
+      this._teardownAndReconnect('timeout');
+    }, this.livenessMs);
+  }
+
+  _clearLiveness() {
+    if (this._livenessTimer) { this._clearTimeout(this._livenessTimer); this._livenessTimer = null; }
+  }
+
+  _clearReconnect() {
+    if (this._reconnectTimer) { this._clearTimeout(this._reconnectTimer); this._reconnectTimer = null; }
+  }
+
+  _goOffline(reason) {
+    const was = this.online;
+    this.online = false;
+    this.clientId = null;
+    if (was) this.emit('offline', reason);
+  }
+
+  _teardownAndReconnect(reason) {
+    this._clearLiveness();
+    try { if (this.ws) { this.ws.removeAllListeners(); this.ws.close(); } } catch (e) { /* ignore */ }
+    this.ws = null;
+    this._goOffline(reason);
+    if (this._closing) return;
+    if (this._reconnectTimer) return;
+    const delay = this.backoff[Math.min(this._backoffIdx, this.backoff.length - 1)];
+    this._backoffIdx++;
+    this.emit('status', 'reconnecting');
+    this._reconnectTimer = this._setTimeout(() => { this._reconnectTimer = null; this._open(); }, delay);
+  }
+
+  _open() {
+    let ws;
+    try {
+      ws = new this._WebSocket(this.url, { perMessageDeflate: true, origin: this.origin });
+    } catch (e) {
+      this.emit('error', e);
+      this._teardownAndReconnect('connect-failed');
+      return;
+    }
+    this.ws = ws;
+    ws.on('open', () => {
+      this.emit('status', 'open');
+      this.msgId = 0; this.clientId = null;
+      this._kickLiveness();
+      this._handshake();
+    });
+    ws.on('message', (data) => this._onFrame(data.toString()));
+    ws.on('close', () => { if (!this._closing) this._teardownAndReconnect('closed'); });
+    ws.on('error', (e) => { this.emit('error', e); });
+  }
+}
+
+module.exports = { RavennaEngine };

package/src/paths.js

@@ -0,0 +1,97 @@
+'use strict';
+
+/**
+ * paths.js
+ * --------
+ * Knowledge about the RAVENNA control grammar, kept separate from connection
+ * logic so that new parameters (or new devices like Anubis) slot in here.
+ *
+ * The device addresses parameters with a JSONPath into its state tree, e.g.
+ *   $._modules[?(@.id==60)][0].custom.outs
+ * and you SET by publishing { path, value } to /service/ravenna/settings,
+ * where `value` is a *partial* object merged into the node at `path`.
+ *
+ * CONFIDENCE levels reflect how sure we are of a parameter's SET shape:
+ *   'confirmed' - observed in a captured set frame from a real device
+ *   'inferred'  - derived from the state/capability shape; very likely correct
+ *   'unknown'   - discoverable (we can read its value) but no verified setter
+ */
+
+/** Build the standard module "outs" path. */
+function moduleOutsPath(moduleId) {
+  return `$._modules[?(@.id==${moduleId})][0].custom.outs`;
+}
+
+/** Build the standard module "ins" path (mic pre gains etc. live here on input cards). */
+function moduleInsPath(moduleId) {
+  return `$._modules[?(@.id==${moduleId})][0].custom.ins`;
+}
+
+/**
+ * Regex to recognise a feedback frame's path as belonging to a given module's outs.
+ * Matches e.g. _modules[?(@.id==60)][0].custom.outs (with or without leading $.).
+ */
+function moduleOutsPathRegex(moduleId) {
+  return new RegExp(`_modules\\[\\?\\(@\\.id==${moduleId}\\)\\]\\[0\\]\\.custom\\.outs`);
+}
+
+/**
+ * Parameter descriptors. `unit` drives value encoding:
+ *   'tenths-db' : device stores integer tenths of a dB; library converts to/from dB
+ *   'bool'      : boolean
+ *   'enum'      : integer mapped to a label set (from capabilities.roll_off_filters etc.)
+ *   'int'       : raw integer
+ */
+const PARAMS = {
+  attenuation: {
+    section: 'outs', unit: 'tenths-db', confidence: 'confirmed',
+    capInfo: 'attenuation_info',
+    build: (v) => ({ attenuation: v })            // v already in tenths
+  },
+  // All four below CONFIRMED on hardware (fw 1.9.0b62872) via an active set->re-read:
+  // the `.custom.outs` set shape actually applies for each. See scripts/set-probe.js.
+  mute: {
+    section: 'outs', unit: 'bool', confidence: 'confirmed',
+    capFlag: 'mute',
+    build: (v) => ({ mute: !!v })
+  },
+  roll_off_filter: {
+    section: 'outs', unit: 'enum', confidence: 'confirmed',
+    capEnum: 'roll_off_filters',
+    build: (v) => ({ roll_off_filter: v | 0 })
+  },
+  // out_max_level is a 0/1 toggle between the card's two output reference levels.
+  out_max_level: {
+    section: 'outs', unit: 'int', confidence: 'confirmed',
+    capFlag: 'out_max_level',
+    build: (v) => ({ out_max_level: v ? 1 : 0 })
+  },
+  // Per-channel trim is an array within custom.outs; the partial-array shape (target
+  // channel carries {trim}, others {}) is confirmed to apply on the device.
+  channel_trim: {
+    section: 'outs', unit: 'tenths-db', confidence: 'confirmed',
+    capInfo: 'channel.trim_info', perChannel: true,
+    build: (v, ctx) => {
+      // ctx: { channelCount, channelIndex }
+      const arr = [];
+      for (let i = 0; i < (ctx.channelCount || 1); i++) {
+        arr.push(i === ctx.channelIndex ? { trim: v } : {});
+      }
+      return { channels: arr };
+    }
+  }
+};
+
+/** dB -> device tenths (rounded). */
+function dbToTenths(db) { return Math.round(db * 10); }
+/** device tenths -> dB. */
+function tenthsToDb(t) { return Math.round(t) / 10; }
+
+module.exports = {
+  moduleOutsPath,
+  moduleInsPath,
+  moduleOutsPathRegex,
+  PARAMS,
+  dbToTenths,
+  tenthsToDb
+};