MCP Voice/Text-Controlled Q-SYS Demo

✅ PHASE 1 COMPLETE - AI-powered voice and text control for Q-SYS audio systems using the official @q-sys/qrwc SDK and Model Context Protocol.

🎉 BREAKTHROUGH: Q-SYS Connection SUCCESS!

We've successfully connected to a live Q-SYS Core with 42 components and 3,074+ controls!

🏆 Phase 1 Achievements

✅ Official @q-sys/qrwc SDK Integration - Using Q-SYS's official WebSocket library
✅ Live Q-SYS Core Connection - Connected to professional AV system at 192.168.50.150:443
✅ 42 Components Discovered - Full access to audio, video, and control systems
✅ 3,074+ Controls Available - Real-time control and monitoring of all Q-SYS components
✅ WSS Protocol Working - Secure WebSocket connection established
✅ Real-time Events - Live update events from Q-SYS components verified
✅ Professional Error Handling - Robust connection management and logging

🎛️ Connected Q-SYS System Overview

Your Q-SYS system includes:

Audio: 15 components (mixers, gain controls, mics, soundbar)
Video: 8 components (displays, video switching, cameras, HDMI routing)
Conference: 5 components (Zoom Room, Microsoft Teams integration)
Control: 9 components (touchpanels, UCI controllers, encoders)
Building: 9 components (HVAC, status monitoring, date/time)

🚀 Quick Start

Test the Q-SYS Connection

# Test basic connection
npm run test:connection

# Test component interaction  
node tests/integration/qsys/test-component-control.mjs

# Run main application
npm run dev

Setup Your Q-SYS Core

Follow the setup guides:
- QRWC_SETUP_GUIDE.md - Complete Q-SYS Core configuration
- QSYS_SETUP.md - Quick setup instructions
Configure your Core IP:
- Edit qsys-core.config.json with your Q-SYS Core's IP address
- The application will automatically load your configuration

Development

# Install dependencies
npm install

# Run development server (connects to Q-SYS)
npm run dev

# Run tests
npm test

# Run linting
npm run lint

# Type checking
npm run type-check

🔧 Configuration

Q-SYS Core Configuration

Edit qsys-core.config.json:

{
  "qsysCore": {
    "host": "YOUR_CORE_IP_ADDRESS",
    "port": 443,
    "username": "",
    "password": "",
    "connectionSettings": {
      "timeout": 10000,
      "reconnectInterval": 5000,
      "enableAutoReconnect": true
    }
  }
}

Configuration Setup (No Duplication!)

We use separate files for different configuration:

# Q-SYS Core settings (IP, port, credentials):
# → Edit qsys-core.config.json

# OpenAI API key and environment settings:  
# → Edit .env file

# Setup both files:
./setup-env.sh

File	Purpose
`qsys-core.config.json`	Q-SYS Core connection settings
`.env`	OpenAI API key, environment variables

See OPENAI_SETUP.md for complete setup instructions.

📊 Project Status

✅ Phase 1: Q-SYS Remote WebSocket Control (QRWC) - COMPLETE

✅ 1.1: Project Setup & Infrastructure
✅ 1.2: Official @q-sys/qrwc SDK Integration
✅ 1.3: WebSocket Connection (WSS on port 443)
✅ 1.4: Component Discovery & Access (42 components found)
✅ 1.5: Real-time Event Handling
✅ 1.6: Error Handling & Reconnection Logic
✅ 1.7: Configuration System (JSON + Environment)
✅ 1.8: Testing & Verification

🔄 Phase 2: MCP Server Implementation - READY

⏳ MCP tools for Q-SYS component control
⏳ Real-time component monitoring
⏳ Voice command processing integration

🔄 Phase 3: AI Integration - READY

⏳ OpenAI integration for voice processing
⏳ Natural language Q-SYS control
⏳ Conversational AV system management

🛠️ Technology Stack

Core Technologies

TypeScript 5.8.4 - Strict typing and modern JavaScript
@q-sys/qrwc 0.4.1-beta - Official Q-SYS Remote WebSocket Control SDK
WebSocket (WSS) - Secure WebSocket connection to Q-SYS Core
Winston - Structured logging with metadata
Jest - Testing framework with async support

Q-SYS Integration

Official Q-SYS SDK - Using @q-sys/qrwc for WebSocket communication
Real-time Events - Component state updates and control changes
Professional Audio/Video Control - Full access to Q-SYS design components
SSL/HTTPS Support - Secure connections with self-signed certificate support

📁 Project Structure

src/
├── qrwc/                   # Q-SYS Remote WebSocket Control
│   └── officialClient.ts   # Official @q-sys/qrwc SDK wrapper (350 lines)
├── shared/                 # Shared utilities and types
│   ├── types/              # TypeScript definitions
│   └── utils/              # Logging, error handling, configuration
├── index.ts                # Main application entry point
tests/                      # Test suites
├── unit/                   # Unit tests for components
└── integration/            # Integration tests
docs/                       # Additional documentation
scripts/                    # Build and utility scripts

# Configuration & Testing
qsys-core.config.json      # Q-SYS Core connection configuration
tests/integration/qsys/test-connection.mjs        # Basic connection test script
tests/integration/qsys/test-component-control.mjs  # Component interaction test script

🧪 Testing & Verification

Connection Tests

# Test Q-SYS Core connection
npm run test:connection
# Expected: ✅ 42 components discovered

# Test component control  
node tests/integration/qsys/test-component-control.mjs
# Expected: ✅ Real-time component interaction working

Application Tests

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Type checking
npm run type-check

📖 Documentation

Setup & Configuration

QRWC Setup Guide - Complete Q-SYS Core configuration
Q-SYS Setup - Quick setup instructions
OpenAI Setup - OpenAI API key configuration for Phase 3
Run Instructions - Development setup

Technical Documentation

Implementation Plan - Complete technical implementation
Project Checklist - Phase completion tracking
QRC Overview - Q-SYS Remote Control overview
Component Control - Component interaction guide

Project Management

PRD Document - Product requirements
Cursor Rules - Development guidelines

🎯 Key Discovery: WSS Protocol

Critical Technical Breakthrough: Q-SYS Cores require Secure WebSocket (WSS) connections, not standard WebSocket (WS).

// ❌ This doesn't work:
const socket = new WebSocket('ws://core-ip:443/qrc-public-api/v0');

// ✅ This works:
const socket = new WebSocket('wss://core-ip:443/qrc-public-api/v0', {
  rejectUnauthorized: false  // For self-signed certificates
});

🏆 Live System Results

Connected to professional Q-SYS installation:

📦 Components found: 42
🎛️ Total controls: 3,074+

Categories discovered:
├── Audio: 15 components (mixers, mics, gain controls)
├── Video: 8 components (displays, switchers, cameras) 
├── Conference: 5 components (Zoom Room, Teams integration)
├── Control: 9 components (touchpanels, encoders)
└── System: 9 components (HVAC, monitoring, time sync)

📄 License

MIT License - see LICENSE file for details.

🎉 Phase 1 Complete! The Q-SYS QRWC integration is fully functional and ready for MCP Server development in Phase 2.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

AI-powered system that enables voice and text control for Q-SYS audio systems using OpenAI Agents SDK and Model Context Protocol.

Related MCP Servers

AivisSpeech MCP Server
kentaro
-
security
F
license
-
quality
A Model Context Protocol server that enables AI assistants to utilize AivisSpeech Engine's high-quality voice synthesis capabilities through a standardized API interface.
Last updated -
TypeScript
Blabber-MCP
pinkpixel-dev
-
security
A
license
-
quality
An MCP server that enables LLMs to generate spoken audio from text using OpenAI's Text-to-Speech API, supporting various voices, models, and audio formats.
Last updated -
4
1
JavaScript
MIT License
Voice Call MCP Server
popcornspace
-
security
A
license
-
quality
A Model Context Protocol server that enables AI assistants like Claude to initiate and manage real-time voice calls using Twilio and OpenAI's voice models.
Last updated -
14
TypeScript
MIT License
MCP Make Sound
nocoo
A
security
A
license
A
quality
A Model Context Protocol server for macOS that enables AI assistants to play system sounds for audio feedback, offering informational, warning, and error sound options.
Last updated -
3
JavaScript
MIT License

View all related MCP servers

MCP Voice/Text-Controlled Q-SYS Demo