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 on your Mac or Ubuntu desktop.
[npm qsys-cli]
[npm qsys-qrc]
[npm qsys-mcp]
[npm qsys-mac]
[npm qsys-linux]
[node ≥18]
[license: MIT]
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.
Quick start — shell
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)
or in any MCP client config:
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.
Registry-aware MCP clients can discover it as io.github.reowens/qsys-mcp.
Quick start — your own code
Change groups (poll-based watch), component access, snapshots, and logon are all
covered by typed helpers — see 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:
Or use the npm bootstrapper:
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:
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:
brew trust is required by current Homebrew for third-party cask taps.
The signed installer source lives in
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.11.
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.
Q-SYS Designer on Linux
The initial Linux recipe runs Designer 10.5.1 on Ubuntu 26.04 x86-64
through Wine Staging 11.20 and Windows .NET 10. Supply your own vendor ZIP/EXE:
Installation needs an accessible X11/XWayland desktop and 12 GiB free during
setup. It runs per-user without sudo and adds a Q-SYS Designer desktop
launcher. See requirements and validation.
The source checkout also has a vendor-free Docker test harness, described under
Container smoke tests. You
build its image locally; no image is published.
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 workspace (Node 22.13+; pnpm comes from the
packageManager field via corepack).
The e2e suites (QRC integration, the MCP-over-mock end-to-end, and the
transparent-reconnect/AutoPoll-replay regression) run against
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 and ramps/meters) uses a
separate, fuller emulator.
qsys-mac-installer builds separately with Xcode — see
packages/qsys-mac-installer (scripts/package.sh for the
sign/notarize pipeline).
Maintainer release steps are documented in 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:
Licensing
The original qsys-tools source code is MIT licensed, including the QRC packages, the
qsys-mac npm bootstrapper, the qsys-linux recipe, 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.
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.