Content
# qsys-tools
> Open-source tooling for **QSC Q-SYS** audio/video systems — control a Core from
> your shell, your code, or an AI agent, and run Q-SYS Designer natively on your Mac.
[](https://www.npmjs.com/package/qsys-cli)
[](https://www.npmjs.com/package/qsys-qrc)
[](https://www.npmjs.com/package/qsys-mcp)
[](https://www.npmjs.com/package/qsys-mac)
[](https://nodejs.org)
[](#licensing)
Every Q-SYS Core — and Q-SYS Designer in **Emulate mode** — serves QSC's published
**QRC** protocol (JSON-RPC 2.0 over TCP, port 1710). It's the same external-control
interface Crestron/AMX integrations use. These tools speak it natively: **zero QSC
code, no SDK, no hardware required for development.**
| Package | What it is |
|---|---|
| [`qsys-cli`](packages/qsys) | CLI (command: `qsys`) — status, component inventory, get/set controls with ramps, live watch, snapshots |
| [`qsys-qrc`](packages/qsys-qrc) | TypeScript QRC client — wire framing, change groups, keepalive, transparent auto-reconnect, typed protocol surface |
| [`qsys-mcp`](packages/qsys-mcp) | [MCP](https://modelcontextprotocol.io) server (`io.github.reowens/qsys-mcp` in the MCP Registry) — 18 tools that let an AI agent inspect and drive a live Q-SYS system |
| [`qsys-mac`](packages/qsys-mac) | npm bootstrapper (command: `qsys-mac`) — downloads/verifies the signed Q-SYS Mac Installer DMG and delegates to its helper |
| [`qsys-mac-installer`](packages/qsys-mac-installer) | **Q-SYS Designer for macOS** — signed/notarized BYO-installer wrapper app + DMG source |
## Quick start — shell
```sh
export QSYS_HOST=192.168.1.10 # your Core, or 127.0.0.1 for Designer Emulate
npx qsys-cli status # engine/design status
npx qsys-cli ls # list components
npx qsys-cli get MainGain # read a named control
npx qsys-cli set MainGain -6 --ramp 2
npx qsys-cli watch MainGain # stream changes until Ctrl-C
npx qsys-cli snapshot load Bank 1 --ramp 1
```
```
$ qsys status
Design RobertOwens-L1 (code Hd4b6C9TXKzL)
Platform Emulator (emulator)
State Active
$ qsys set-component Main_Mixer input.1.gain -6 --ramp 2
NAME VALUE STRING POSITION
input.1.gain -6 -6.00dB 0.585
```
Install the command globally with `npm i -g qsys-cli` (the binary is plain `qsys`).
Every command takes `--json` for scripting; `watch` emits JSON lines.
## Quick start — AI agent (MCP)
```sh
claude mcp add qsys -- npx -y qsys-mcp
```
or in any MCP client config:
```json
{
"mcpServers": {
"qsys": { "command": "npx", "args": ["-y", "qsys-mcp"] }
}
}
```
Then ask the agent to connect to your Core (or the Designer emulator) and it can read
meters, flip mutes, ramp gains, watch controls for changes, and recall snapshots —
with auto-reconnect across Core restarts. Details in
[`packages/qsys-mcp`](packages/qsys-mcp).
Registry-aware MCP clients can discover it as `io.github.reowens/qsys-mcp`.
## Quick start — your own code
```sh
npm install qsys-qrc
```
```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();
```
Change groups (poll-based watch), component access, snapshots, and logon are all
covered by typed helpers — see [`packages/qsys-qrc`](packages/qsys-qrc).
## Q-SYS Designer on your Mac
For most users, use the signed DMG installer app. Run it once to create `Q-SYS Designer.app`, then
either trash the installer app or keep it around as a small manager for Launch, Reinstall, and Remove.
The installed Designer app and its Application Support data remain independent of the installer app.
Direct DMG path:
```sh
open https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4
```
Or use the npm bootstrapper:
```sh
npx qsys-mac install "/path/to/Q-SYS Designer Installer 10.4.0.exe"
```
It downloads and verifies the signed Q-SYS Mac Installer DMG, mounts it, and runs
the bundled helper. The npm package does not contain Q-SYS Designer or the app
payload. You provide **your own** free Designer installer download (BYO — nothing
of QSC's is redistributed).
For read-only support diagnostics, run:
```sh
npx qsys-mac doctor
```
Current macOS prerequisite: Rosetta 2. The signed DMG bundles Wine, .NET, `7z`,
icon tooling, `msiinfo`, and native helper binaries; normal setup does not need
Homebrew or host Python.
Prefer a GUI installer app? Homebrew can install it:
```sh
brew tap reowens/qsys
brew trust reowens/qsys
brew install --cask qsys-mac-installer
open -a "Q-SYS Mac Installer"
```
`brew trust` is required by current Homebrew for third-party cask taps.
The signed installer source lives in
[`packages/qsys-mac-installer`](packages/qsys-mac-installer). It provisions Wine +
.NET into Application Support and gives you a real Dock/Finder/menu-bar citizen.
The current signed DMG is
[`qsys-mac-installer 0.1.4`](https://github.com/reowens/qsys-tools/releases/tag/qsys-mac-installer-v0.1.4).
Bonus: Designer's **Emulate mode** serves QRC on `127.0.0.1:1710`, so all of the
tools above work hardware-free against it — that's how this repo's tooling is
validated.
## No hardware?
Point any of the tools at Q-SYS Designer running in Emulate mode (`--host
127.0.0.1`). Two protocol facts worth knowing: QRC has no method to *enumerate*
named controls or snapshot banks (you need their names from the design), and
`Component.GetComponents` returns only components with script access enabled.
## Development
This is a [pnpm](https://pnpm.io) workspace (Node 22.13+; pnpm comes from the
`packageManager` field via [corepack](https://nodejs.org/api/corepack.html)).
```sh
git clone https://github.com/reowens/qsys-tools.git
cd qsys-tools
corepack enable # provisions the pinned pnpm
pnpm install
pnpm -r build # builds packages in dependency order (qsys-qrc first)
pnpm run typecheck
pnpm test
```
The e2e suites (QRC integration, the MCP-over-mock end-to-end, and the
transparent-reconnect/AutoPoll-replay regression) run against
[`qsys-mock-core`](packages/qsys-mock-core) — an in-repo, design-driven Q-SYS Core
mock — so `pnpm test` exercises the full protocol with no hardware. Deeper
conformance testing (validated-against-Designer rendering, ramps/meters, and a
library of real Q-SYS designs) uses a separate, fuller emulator.
`qsys-mac-installer` builds separately with Xcode — see
[`packages/qsys-mac-installer`](packages/qsys-mac-installer) (`scripts/package.sh` for the
sign/notarize pipeline).
Maintainer release steps are documented in [`RELEASE.md`](RELEASE.md).
When working from this source checkout, use the workspace script instead of
`npx qsys-mac` so the local workspace package isn't confused with the published
one:
```sh
pnpm run qsys-mac -- status
pnpm run qsys-mac -- install "/path/to/Q-SYS Designer Installer 10.4.0.exe"
```
## Licensing
The original `qsys-tools` source code is **MIT** licensed, including the QRC packages, the
`qsys-mac` npm bootstrapper, and the `qsys-mac-installer` wrapper app.
The signed macOS installer DMG is a multi-license binary distribution because it bundles
redistributable third-party components such as Wine, .NET, p7zip, icoutils, `msiinfo`, and their
runtime libraries. Those components remain under their own licenses and notices; see
[`packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md`](packages/qsys-mac-installer/THIRD-PARTY-NOTICES.md).
Each package carries its own LICENSE file.
## Disclaimer
This is an independent open-source project, **not affiliated with, endorsed by, or
sponsored by QSC, LLC**. "Q-SYS" and "Q-SYS Designer" are trademarks of QSC, LLC,
used nominatively. These tools speak the publicly documented QRC protocol and
contain no QSC code.
