qsys-qrc 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Owens
+
+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,51 @@
+# qsys-qrc
+
+TypeScript client for QSC's **Q-SYS Remote Control (QRC)** protocol — the
+null-terminated JSON-RPC-over-TCP interface every Q-SYS Core (and Q-SYS
+Designer in Emulate mode) serves on port 1710.
+
+Handles the wire framing, request/response correlation, change groups,
+keepalive, and transparent auto-reconnect, and ships shared types for
+controls, components, and engine status. It is the core that the
+[`qsys`](https://www.npmjs.com/package/qsys) CLI and the
+[`q-sys-mcp`](https://www.npmjs.com/package/q-sys-mcp) server build on.
+
+## Install
+
+```sh
+npm install qsys-qrc
+```
+
+## Usage
+
+```ts
+import { QrcClient } from 'qsys-qrc';
+
+const qrc = new QrcClient({ host: '192.168.1.10' });
+await qrc.connect();
+
+const status = await qrc.statusGet();          // typed helpers…
+await qrc.setControl('MainGain', -6, 2);       // value -6, 2 s ramp
+const [gain] = await qrc.getControl(['MainGain']);
+
+await qrc.send('Component.GetComponents');     // …or raw QRC methods
+
+qrc.close();
+```
+
+Typed helpers cover the whole protocol surface: status, components,
+named controls, change groups (poll-based watch), and snapshots.
+
+The client keeps the socket alive (`NoOp` keepalive) and reconnects
+transparently if the Core drops the connection; in-flight requests are
+rejected, subsequent ones reuse the new socket.
+
+## Disclaimer
+
+This is an independent open-source project, **not affiliated with, endorsed
+by, or supported by QSC, LLC**. "Q-SYS" is a trademark of QSC. The client
+speaks the publicly documented QRC protocol and contains no QSC code.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+/** qsys-qrc — the QRC client, wire framing, and shared types. */
+export * from './qrc.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+/** qsys-qrc — the QRC client, wire framing, and shared types. */
+export * from './qrc.js';

package/dist/qrc.d.ts

@@ -0,0 +1,159 @@
+import { EventEmitter } from 'node:events';
+export interface QrcClientOptions {
+    host: string;
+    port?: number;
+    /** Keepalive interval in ms. QRC closes idle sockets after 60s; default 30s. */
+    keepAliveMs?: number;
+    /** Per-request timeout in ms (default 10s). */
+    requestTimeoutMs?: number;
+    /**
+     * Auto-reconnect on an unexpected socket drop (Core restart, leaving Emulate
+     * mode, a network blip), replaying logon + change-group registrations so
+     * polling resumes seamlessly. Default true. An explicit close() disables it.
+     */
+    reconnect?: boolean;
+    /** Initial reconnect backoff in ms (default 500). */
+    reconnectInitialMs?: number;
+    /** Max reconnect backoff in ms (default 10_000). */
+    reconnectMaxMs?: number;
+    /** Consecutive background reconnect attempts before giving up until the next request (default 8). */
+    reconnectMaxAttempts?: number;
+}
+export declare class QrcError extends Error {
+    code?: number;
+    data?: unknown;
+    constructor(err: unknown);
+}
+/**
+ * Q-SYS Remote Control (QRC) client.
+ * Speaks JSON-RPC 2.0 over a raw TCP socket (default port 1710), framed with
+ * null terminators — the wire format QSC documents and that the Designer
+ * Emulate-mode soft-core serves on localhost.
+ *
+ * Events: 'engineStatus' (params), 'notification' (full message), 'error', 'close',
+ * plus reconnect lifecycle: 'reconnecting' (attempt #), 'reconnected',
+ * 'reconnectError' ({attempt, error}), 'reconnectFailed'.
+ */
+export declare class QrcClient extends EventEmitter {
+    private readonly host;
+    private readonly port;
+    private readonly keepAliveMs;
+    private readonly requestTimeoutMs;
+    private readonly reconnectEnabled;
+    private readonly reconnectInitialMs;
+    private readonly reconnectMaxMs;
+    private readonly reconnectMaxAttempts;
+    private socket;
+    private buf;
+    private nextId;
+    private readonly pending;
+    private keepAliveTimer;
+    private connected;
+    private explicitlyClosed;
+    private reconnectPromise;
+    private logonCreds;
+    private readonly changeGroups;
+    constructor(opts: QrcClientOptions);
+    isConnected(): boolean;
+    connect(): Promise<void>;
+    /** Open a fresh socket and wire its handlers. Rejects if the TCP connect fails. */
+    private openSocket;
+    private onData;
+    private dispatch;
+    /**
+     * Send a JSON-RPC request and await the correlated response. If the socket is
+     * down (or drops mid-request) and auto-reconnect is enabled, this waits for a
+     * reconnect and retries once — connection drops are transparent to callers.
+     */
+    send(method: string, params?: unknown): Promise<unknown>;
+    /** One request attempt on the current socket — no reconnect handling. */
+    private sendOnce;
+    /** A connection drop is retryable; a timeout (socket still up) is not. */
+    private shouldRetryAfterDrop;
+    /** Fire-and-forget notification (no id, no response expected). */
+    notify(method: string, params?: unknown): void;
+    private startKeepAlive;
+    private stopKeepAlive;
+    private onClose;
+    /** Resolve once connected, driving (or joining) a reconnect attempt as needed. */
+    private ensureReconnected;
+    /**
+     * Re-dial with exponential backoff, then replay logon + change-group
+     * registrations so polling resumes. Never rejects: callers read isConnected()
+     * (or a subsequent sendOnce) for the outcome. Gives up after maxAttempts, but
+     * the next request re-triggers a fresh attempt.
+     */
+    private runReconnect;
+    /** Re-establish session state on a fresh socket. Throws if any step fails. */
+    private replayState;
+    /** Tear down the current socket without triggering reconnect (used between attempts). */
+    private teardownSocket;
+    private sleep;
+    close(): void;
+    /** Emit 'error' if anyone is listening; otherwise log to stderr instead of throwing. */
+    private emitError;
+    logon(user: string, password: string): Promise<unknown>;
+    statusGet(): Promise<EngineStatus>;
+    getComponents(): Promise<QrcComponent[]>;
+    getComponentControls(name: string): Promise<{
+        Name: string;
+        Controls: QrcControl[];
+    }>;
+    getComponent(name: string, controls: string[]): Promise<{
+        Name: string;
+        Controls: QrcControl[];
+    }>;
+    setComponent(name: string, controls: Array<{
+        Name: string;
+        Value: ControlValue;
+        Ramp?: number;
+    }>): Promise<unknown>;
+    getControl(names: string[]): Promise<QrcControl[]>;
+    setControl(name: string, value: ControlValue, ramp?: number): Promise<unknown>;
+    changeGroupAddControl(id: string, controls: string[]): Promise<unknown>;
+    changeGroupAddComponentControl(id: string, component: string, controls: string[]): Promise<unknown>;
+    changeGroupPoll(id: string): Promise<{
+        Id: string;
+        Changes: QrcControl[];
+    }>;
+    changeGroupRemove(id: string, controls: string[]): Promise<unknown>;
+    changeGroupClear(id: string): Promise<unknown>;
+    changeGroupInvalidate(id: string): Promise<unknown>;
+    changeGroupDestroy(id: string): Promise<unknown>;
+    /**
+     * Recall a saved snapshot. Note: QRC's `Bank` param is the snapshot *number*
+     * within a named bank — `bank` here is the bank name, `number` the slot.
+     */
+    snapshotLoad(bank: string, number: number, ramp?: number): Promise<unknown>;
+    snapshotSave(bank: string, number: number): Promise<unknown>;
+    private groupState;
+}
+export type ControlValue = number | string | boolean;
+export interface EngineStatus {
+    Platform: string;
+    State: string;
+    DesignName: string;
+    DesignCode: string;
+    IsRedundant: boolean;
+    IsEmulator: boolean;
+    Status: {
+        Code: number;
+        String: string;
+    };
+}
+export interface QrcComponent {
+    ID?: string;
+    Name: string;
+    Type: string;
+    Properties?: Array<{
+        Name: string;
+        Value: string;
+        PrettyName?: string;
+    }>;
+}
+export interface QrcControl {
+    Name: string;
+    Value: ControlValue;
+    String?: string;
+    Position?: number;
+}

package/dist/qrc.js

@@ -0,0 +1,392 @@
+import net from 'node:net';
+import { EventEmitter } from 'node:events';
+export class QrcError extends Error {
+    code;
+    data;
+    constructor(err) {
+        const o = (err && typeof err === 'object') ? err : null;
+        super(o ? String(o.message ?? JSON.stringify(err)) : String(err));
+        this.name = 'QrcError';
+        if (o) {
+            this.code = typeof o.code === 'number' ? o.code : undefined;
+            this.data = o.data;
+        }
+    }
+}
+/**
+ * Q-SYS Remote Control (QRC) client.
+ * Speaks JSON-RPC 2.0 over a raw TCP socket (default port 1710), framed with
+ * null terminators — the wire format QSC documents and that the Designer
+ * Emulate-mode soft-core serves on localhost.
+ *
+ * Events: 'engineStatus' (params), 'notification' (full message), 'error', 'close',
+ * plus reconnect lifecycle: 'reconnecting' (attempt #), 'reconnected',
+ * 'reconnectError' ({attempt, error}), 'reconnectFailed'.
+ */
+export class QrcClient extends EventEmitter {
+    host;
+    port;
+    keepAliveMs;
+    requestTimeoutMs;
+    reconnectEnabled;
+    reconnectInitialMs;
+    reconnectMaxMs;
+    reconnectMaxAttempts;
+    socket = null;
+    buf = '';
+    nextId = 1;
+    pending = new Map();
+    keepAliveTimer = null;
+    connected = false;
+    explicitlyClosed = false;
+    reconnectPromise = null;
+    logonCreds = null;
+    changeGroups = new Map();
+    constructor(opts) {
+        super();
+        this.host = opts.host;
+        this.port = opts.port ?? 1710;
+        this.keepAliveMs = opts.keepAliveMs ?? 30_000;
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? 10_000;
+        this.reconnectEnabled = opts.reconnect ?? true;
+        this.reconnectInitialMs = opts.reconnectInitialMs ?? 500;
+        this.reconnectMaxMs = opts.reconnectMaxMs ?? 10_000;
+        this.reconnectMaxAttempts = opts.reconnectMaxAttempts ?? 8;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    async connect() {
+        this.explicitlyClosed = false;
+        await this.openSocket();
+    }
+    /** Open a fresh socket and wire its handlers. Rejects if the TCP connect fails. */
+    openSocket() {
+        return new Promise((resolve, reject) => {
+            const sock = net.createConnection({ host: this.host, port: this.port });
+            sock.setEncoding('utf8');
+            const onConnectError = (e) => reject(e);
+            sock.once('error', onConnectError);
+            sock.once('connect', () => {
+                sock.removeListener('error', onConnectError);
+                this.socket = sock;
+                this.connected = true;
+                this.buf = '';
+                sock.on('data', (chunk) => this.onData(typeof chunk === 'string' ? chunk : chunk.toString('utf8')));
+                sock.on('error', (e) => this.emitError(e));
+                sock.on('close', () => this.onClose());
+                this.startKeepAlive();
+                resolve();
+            });
+        });
+    }
+    onData(chunk) {
+        this.buf += chunk;
+        let idx;
+        while ((idx = this.buf.indexOf('\0')) !== -1) {
+            const raw = this.buf.slice(0, idx);
+            this.buf = this.buf.slice(idx + 1);
+            if (!raw.trim())
+                continue;
+            let msg;
+            try {
+                msg = JSON.parse(raw);
+            }
+            catch {
+                this.emitError(new Error(`QRC parse error: ${raw.slice(0, 200)}`));
+                continue;
+            }
+            this.dispatch(msg);
+        }
+    }
+    dispatch(msg) {
+        const id = msg.id;
+        if (typeof id === 'number' && this.pending.has(id)) {
+            const p = this.pending.get(id);
+            this.pending.delete(id);
+            clearTimeout(p.timer);
+            if (msg.error)
+                p.reject(new QrcError(msg.error));
+            else
+                p.resolve(msg.result);
+            return;
+        }
+        // Unsolicited notification (EngineStatus on connect, change-group autopolls, etc.)
+        if (typeof msg.method === 'string') {
+            if (msg.method === 'EngineStatus')
+                this.emit('engineStatus', msg.params);
+            this.emit('notification', msg);
+        }
+    }
+    /**
+     * Send a JSON-RPC request and await the correlated response. If the socket is
+     * down (or drops mid-request) and auto-reconnect is enabled, this waits for a
+     * reconnect and retries once — connection drops are transparent to callers.
+     */
+    async send(method, params) {
+        if (!this.connected)
+            await this.ensureReconnected();
+        try {
+            return await this.sendOnce(method, params);
+        }
+        catch (err) {
+            if (this.shouldRetryAfterDrop(err)) {
+                await this.ensureReconnected();
+                if (this.connected)
+                    return await this.sendOnce(method, params);
+            }
+            throw err;
+        }
+    }
+    /** One request attempt on the current socket — no reconnect handling. */
+    sendOnce(method, params) {
+        if (!this.socket || !this.connected) {
+            return Promise.reject(new Error('QRC not connected — call connect() first'));
+        }
+        const id = this.nextId++;
+        const frame = JSON.stringify({ jsonrpc: '2.0', method, params: params ?? null, id }) + '\0';
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`QRC request timed out: ${method} (id ${id})`));
+            }, this.requestTimeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.socket.write(frame);
+        });
+    }
+    /** A connection drop is retryable; a timeout (socket still up) is not. */
+    shouldRetryAfterDrop(err) {
+        if (this.explicitlyClosed || !this.reconnectEnabled)
+            return false;
+        const m = err?.message ?? '';
+        return m.includes('QRC connection closed') || m.includes('QRC not connected');
+    }
+    /** Fire-and-forget notification (no id, no response expected). */
+    notify(method, params) {
+        if (!this.socket || !this.connected)
+            return;
+        this.socket.write(JSON.stringify({ jsonrpc: '2.0', method, params: params ?? null }) + '\0');
+    }
+    startKeepAlive() {
+        this.stopKeepAlive();
+        this.keepAliveTimer = setInterval(() => this.notify('NoOp', {}), this.keepAliveMs);
+        this.keepAliveTimer.unref?.();
+    }
+    stopKeepAlive() {
+        if (this.keepAliveTimer) {
+            clearInterval(this.keepAliveTimer);
+            this.keepAliveTimer = null;
+        }
+    }
+    onClose() {
+        this.connected = false;
+        this.stopKeepAlive();
+        for (const p of this.pending.values()) {
+            clearTimeout(p.timer);
+            p.reject(new Error('QRC connection closed'));
+        }
+        this.pending.clear();
+        this.emit('close');
+        // Kick a background reconnect on an unexpected drop. The !reconnectPromise
+        // guard means a drop during an in-flight reconnect attempt won't start a
+        // second loop (and our own teardownSocket() won't either).
+        if (this.reconnectEnabled && !this.explicitlyClosed && !this.reconnectPromise) {
+            void this.ensureReconnected();
+        }
+    }
+    /** Resolve once connected, driving (or joining) a reconnect attempt as needed. */
+    ensureReconnected() {
+        if (this.connected)
+            return Promise.resolve();
+        if (this.explicitlyClosed || !this.reconnectEnabled)
+            return Promise.resolve();
+        if (!this.reconnectPromise) {
+            this.reconnectPromise = this.runReconnect().finally(() => {
+                this.reconnectPromise = null;
+            });
+        }
+        return this.reconnectPromise;
+    }
+    /**
+     * Re-dial with exponential backoff, then replay logon + change-group
+     * registrations so polling resumes. Never rejects: callers read isConnected()
+     * (or a subsequent sendOnce) for the outcome. Gives up after maxAttempts, but
+     * the next request re-triggers a fresh attempt.
+     */
+    async runReconnect() {
+        let delay = this.reconnectInitialMs;
+        for (let attempt = 1; attempt <= this.reconnectMaxAttempts; attempt++) {
+            if (this.explicitlyClosed)
+                return;
+            this.emit('reconnecting', attempt);
+            try {
+                await this.openSocket();
+                await this.replayState();
+                this.emit('reconnected');
+                return;
+            }
+            catch (err) {
+                this.teardownSocket();
+                this.emit('reconnectError', { attempt, error: err });
+                if (attempt >= this.reconnectMaxAttempts)
+                    break;
+                await this.sleep(delay);
+                delay = Math.min(delay * 2, this.reconnectMaxMs);
+            }
+        }
+        this.emit('reconnectFailed');
+    }
+    /** Re-establish session state on a fresh socket. Throws if any step fails. */
+    async replayState() {
+        if (this.logonCreds) {
+            await this.sendOnce('Logon', { User: this.logonCreds.user, Password: this.logonCreds.password });
+        }
+        for (const [id, g] of this.changeGroups) {
+            if (g.controls.size > 0) {
+                await this.sendOnce('ChangeGroup.AddControl', { Id: id, Controls: [...g.controls] });
+            }
+            for (const [component, controls] of g.components) {
+                if (controls.size > 0) {
+                    await this.sendOnce('ChangeGroup.AddComponentControl', {
+                        Id: id,
+                        Component: { Name: component, Controls: [...controls].map((n) => ({ Name: n })) },
+                    });
+                }
+            }
+        }
+    }
+    /** Tear down the current socket without triggering reconnect (used between attempts). */
+    teardownSocket() {
+        this.stopKeepAlive();
+        if (this.socket) {
+            this.socket.removeAllListeners();
+            this.socket.destroy();
+            this.socket = null;
+        }
+        this.connected = false;
+    }
+    sleep(ms) {
+        return new Promise((resolve) => {
+            const t = setTimeout(resolve, ms);
+            t.unref?.();
+        });
+    }
+    close() {
+        this.explicitlyClosed = true;
+        this.stopKeepAlive();
+        if (this.socket) {
+            this.socket.end();
+            this.socket = null;
+        }
+        this.connected = false;
+        this.changeGroups.clear();
+        this.logonCreds = null;
+    }
+    /** Emit 'error' if anyone is listening; otherwise log to stderr instead of throwing. */
+    emitError(err) {
+        if (this.listenerCount('error') > 0)
+            this.emit('error', err);
+        else
+            console.error('[qrc]', err.message);
+    }
+    // ---- QRC method wrappers ----
+    async logon(user, password) {
+        const result = await this.send('Logon', { User: user, Password: password });
+        this.logonCreds = { user, password }; // remembered so reconnect can re-auth
+        return result;
+    }
+    statusGet() {
+        return this.send('StatusGet', 0);
+    }
+    getComponents() {
+        return this.send('Component.GetComponents', null);
+    }
+    getComponentControls(name) {
+        return this.send('Component.GetControls', { Name: name });
+    }
+    getComponent(name, controls) {
+        return this.send('Component.Get', {
+            Name: name,
+            Controls: controls.map((n) => ({ Name: n })),
+        });
+    }
+    setComponent(name, controls) {
+        return this.send('Component.Set', { Name: name, Controls: controls });
+    }
+    getControl(names) {
+        return this.send('Control.Get', names);
+    }
+    setControl(name, value, ramp) {
+        const params = { Name: name, Value: value };
+        if (ramp != null)
+            params.Ramp = ramp;
+        return this.send('Control.Set', params);
+    }
+    async changeGroupAddControl(id, controls) {
+        const result = await this.send('ChangeGroup.AddControl', { Id: id, Controls: controls });
+        const g = this.groupState(id);
+        for (const c of controls)
+            g.controls.add(c);
+        return result;
+    }
+    async changeGroupAddComponentControl(id, component, controls) {
+        const result = await this.send('ChangeGroup.AddComponentControl', {
+            Id: id,
+            Component: { Name: component, Controls: controls.map((n) => ({ Name: n })) },
+        });
+        const set = this.groupState(id).components.get(component) ?? new Set();
+        for (const c of controls)
+            set.add(c);
+        this.groupState(id).components.set(component, set);
+        return result;
+    }
+    changeGroupPoll(id) {
+        return this.send('ChangeGroup.Poll', { Id: id });
+    }
+    async changeGroupRemove(id, controls) {
+        const result = await this.send('ChangeGroup.Remove', { Id: id, Controls: controls });
+        const g = this.changeGroups.get(id);
+        if (g)
+            for (const c of controls)
+                g.controls.delete(c); // drop from replay state too
+        return result;
+    }
+    async changeGroupClear(id) {
+        const result = await this.send('ChangeGroup.Clear', { Id: id });
+        const g = this.changeGroups.get(id);
+        if (g) {
+            g.controls.clear();
+            g.components.clear();
+        }
+        return result;
+    }
+    changeGroupInvalidate(id) {
+        return this.send('ChangeGroup.Invalidate', { Id: id });
+    }
+    async changeGroupDestroy(id) {
+        const result = await this.send('ChangeGroup.Destroy', { Id: id });
+        this.changeGroups.delete(id); // stop replaying a group the caller tore down
+        return result;
+    }
+    /**
+     * Recall a saved snapshot. Note: QRC's `Bank` param is the snapshot *number*
+     * within a named bank — `bank` here is the bank name, `number` the slot.
+     */
+    snapshotLoad(bank, number, ramp) {
+        const params = { Name: bank, Bank: number };
+        if (ramp != null)
+            params.Ramp = ramp;
+        return this.send('Snapshot.Load', params);
+    }
+    snapshotSave(bank, number) {
+        return this.send('Snapshot.Save', { Name: bank, Bank: number });
+    }
+    groupState(id) {
+        let g = this.changeGroups.get(id);
+        if (!g) {
+            g = { controls: new Set(), components: new Map() };
+            this.changeGroups.set(id, g);
+        }
+        return g;
+    }
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "qsys-qrc",
+  "version": "0.1.0",
+  "description": "Q-SYS Remote Control (QRC) client, null-terminated JSON-RPC wire framing, and shared types — the core the qsys CLI and q-sys-mcp server both build on.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/reowens/qsys-tools.git",
+    "directory": "packages/qsys-qrc"
+  },
+  "bugs": {
+    "url": "https://github.com/reowens/qsys-tools/issues"
+  },
+  "homepage": "https://github.com/reowens/qsys-tools/tree/main/packages/qsys-qrc#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": ["q-sys", "qsys", "qsc", "qrc", "av"]
+}