QRC Commands

QRC is a Unicode-based TCP/IP control protocol. The client connects to the Q-SYS Core (or emulator) on port 1710 and sends JSON RPC 2.0 null-terminated commands.

Note: For the JSON-RPC 2.0 Specification, visit jsonrpc.org.

Tip: In all QRC commands, id acts as an identifier and allows for the sender to match the response with the command. The id will be copied and returned to the sender in the response. The id field must be a number and you can use whatever value you want.

Every QRC command must meet both of the following requirements:

  1. It must be a command from the supported commands listed below.
  2. Each command must be terminated in a null.

For the first requirement, you can find the full list of supported QRC commands below.

For the second, a zero character following the escape character should be used for the null, as shown here.

Use these methods to log on to the Q-SYS Core processor via the QRC protocol and maintain the socket connection.

Note: User credentials must first be created in Users (Administrator)

Logs on to the system.

Parameters

User, Password

Example

Copy 
{
  "jsonrpc":"2.0",
  "method":"Logon",
  "params":{
    "User":"username",
    "Password":"1234"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id" : <id_send_with_command>,								
  "error" : <error if command failed>,								
  "response" : <response if command succeeded>, 								
}

This is a simple, "do nothing" method for making sure that the socket remains open.

Parameters

None.

Example

Copy 
{
  "jsonrpc":"2.0",
  "method":"NoOp",
  "params":{
  }
}

Use these methods to obtain the status of the Q-SYS Core.

This method is automatically deployed to return the status of the Q-SYS Core whenever a client connects to the QRC port or the status changes.

Note: When the connection is open and there is a status change on any device in the inventory, an unsolicited EngineStatus message will be sent.

Parameters

State : One of the following strings – "Idle", "Active", "Standby".

DesignName : Name of the currently running design.

DesignCode : GUID of the currently running design.

IsRedundant : True if the design is configured to be a redundant design.

IsEmulator : True if the design is currently running in the emulator.

Example

Copy 
{
  "jsonrpc":"2.0", 
  "method":"EngineStatus", 
  "params":{
    "State":"Active", 
    "DesignName":"MyDesign", 
    "DesignCode":"qALFilm6IcCo", 
    "IsRedundant":false, 
    "IsEmulator":true
  }
}

Manually request the current status. Returns the EngineStatus of the Q-SYS Core.

Parameters

NA

Response Results

Platform : The Q-SYS Core model.

State : One of the following strings – "Idle", "Active", "Standby".

DesignName : Name of the currently running design.

DesignCode : GUID of the currently running design.

IsRedundant : True if the design is configured to be a redundant design.

IsEmulator : True if the design is currently running in the emulator.

Example

Copy 
{
  "jsonrpc": "2.0", 
  "method": "StatusGet", 
  "id": 1234,
  "params": 0
}

Response

{
  "jsonrpc":"2.0", 
  "id":1234
  "result":{ 
    "Platform":"Core 510i", 
    "State":"Active",
    "DesignName":"SAF‐MainPA", 
    "DesignCode":"qALFilm6IcAz", 
    "IsRedundant":false, 
    "IsEmulator":true, 
    "Status":{
      "Code":0 
      "String":"OK"
    }
  }
}

Use these methods to get and set Named Control values.

Specify an array of Named Control strings, receive an array of control values.

Parameters

Array of Named Control strings, e.g.:

["Named_Control_Name", "Named_Control_Name"]

Response

Name : Name of the control, relative to the component.

Value : The value of the control. This can be a number, string, or boolean.

String : String representation of the control.

Example 1: Single Named Control

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "Control.Get",
  "params": ["MainGain"]
}

Response

{
  "jsonrpc": "2.0",
  "id": 1234,
  "result": [
    {
      "Name": "MainGain", 
      "Value": ‐12
    }
  ]
}

Example 2: Multiple Named Controls

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method":  "Control.Get", 
  "params": ["MainGain", "MainMute"]
}

Response

{
  "jsonrpc": "2.0",
  "id": 1234,
  "result": [
    {
      "Name": "MainGain", 
      "Value": ‐12 
      "String" : "‐12.0dB"
    },
    {
      "Name": "MainMute", 
      "Value": false, 
      "String" : "Unmuted"
    }
  ]
}

Set a control's value. Specify a single control name, value, and optional ramp time.

Parameters

Name : Name of the control, relative to the component.

Value : The value of the control. This can be a number, string, or boolean.

Ramp : (Optional) The ramp time used to set the control.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "Control.Set", 
  "params": {
    "Name": "MainGain", 
    "Value": ‐12
  }
}

Use these methods to get and set controls within Named Components, or obtain a list of all Named Components in a design.

Returns the values of one or more specified controls within a specified Named Component.

Parameters

Name : The name of the named component.

Controls : An array of control values.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "Component.Get", 
  "params": {
    "Name": "My APM",
    "Controls": [
      { "Name": "ent.xfade.gain" }
    ]
  }
}

Response

{
  "jsonrpc": "2.0", 
  "result": {
    "Name": "My APM",
    "Controls": [
    {
      "Name": "ent.xfade.gain", 
      "Value": ‐100.0,
      "String": "‐100.0dB" 
      "Position": 0
    }
    ]
  }
}

Returns a table of all controls and their values in a specified Named Component.

Parameters

Name : The name of the named component.

Example

Copy 
{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "Component.GetControls",
    "params": {
        "Name": "MyGain"
    }
}

Response

{
    "jsonrpc": "2.0",
    "result": {
        "Name": "MyGain",
        "Controls": [
            {
                "Name": "bypass",
                "Type": "Boolean",
                "Value": false,
                "String": "no",
                "Position": 0.0,
                "Direction": "Read/Write"
            },
                "Name": "gain",
                "Type": "Float",
                "Value": 0.0,
                "ValueMin": -100.0,
                "ValueMax": 20.0,
                "StringMin": "-100dB",
                "StringMax": "20.0dB",
                "String": "0dB",
                "Position": 0.83333331,
                "Name": "invert",
                "String": "normal",
                "Name": "mute",
                "String": "unmuted",
            }
        ]
    },
    "id": 1234
}

Set one or more controls for a single named component. Returns a list of unknown controls after processing.

Parameters

Name : The name of the named component.

Controls : An array of control values.

ResponseValues : (optional). Can be set to either true or false. When set to true, the response will return the new Values of the controls.

Example 1: Set a single control

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "Component.Set", 
  "params": {
    "Name": "My APM",
    "Controls": [
      {
        "Name": "ent.xfade.gain", 
        "Value": ‐100.0,
        "Ramp": 2.0
      }
    ]
  }
}

Example 2: Set multiple controls

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "Component.Set", 
  "params": {
    "Name": "My APM",
    "Controls": [
      {
        "Name": "ent.xfade.gain", 
        "Value": ‐100.0,
        "Ramp": 2.0
      },
      {
        "Name": "bgm.xfade.gain", 
        "Value": 0.0,
        "Ramp": 1.0
      }
    ]
  }
}

Example 3: Setting ResponseValues to True

Copy 
=> {
  "jsonrpc": "2.0",
  "method": "Component.Set",
  "params": {
    "Name": "Gain",
    "ResponseValues": true,
    "Controls": [
      {
        "Name": "gain",
        "Value": -10,
        "Ramp": 0
      }
    ]
  },
  "id": 101
}

<= {
  "jsonrpc": "2.0",
  "result": [
    {
      "Component": "Gain",
      "Name": "gain",
      "String": "-10.0dB",
      "Value": -10,
      "Position": 0.75
    }
  ],
  "id": 101
}

Get a list of all named components in a design, along with their type and properties.

Parameters

NA

Example

Copy 
{
  "jsonrpc": "2.0",
  "method": "Component.GetComponents", 
  "params": "test",
  "id": 1234
}

Response

{
  "jsonrpc": "2.0", 
  "result": [
    {
      "Name": "APM ABC",
      "Type": "apm",
      "Properties": []
    },
    {
      "Name": "My Delay Mixer", 
      "Type": "delay_matrix", 
      "Properties": [
        {
          "Name": "n_inputs",
          "Value": "8"
        },
        {
          "Name": "n_outputs",
          "Value": "8"
        },
        {
          "Name": "max_delay",
          "Value": "0.5"
        },
        {
          "Name": "delay_type", 
          "Value": "0"
        },
        {
          "Name": "linear_gain", 
          "Value": "False"
        },
        {
          "Name": "multi_channel_type", 
          "Value": "1"
        },
        {
          "Name": "multi_channel_count", 
          "Value": "8"
        }
      ]
    }
  ],
  "id": 1234
}

Use these methods to create, manipulate, and poll change groups.

Note: There is a maximum limit of four change groups, but there is no restriction on the number of controls within a change group

Create a change group and/or add controls to a change group via Named Controls.

Parameters

Id : Change group ID.

Controls : Array of control names.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.AddControl", 
  "params": {
    "Id": "my change group", 
    "Controls" : [
      "some control", "another control"
    ]
  }
}

Create a change group and/or add controls to a change group via a Named Component.

Parameters

Id : Change group ID.

Component : Named Component name and array of controls.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.AddComponentControl", 
  "params": {
    "Id": "my change group", 
    "Component" : {
      "Name": "My Component", 
      "Controls": [
        { "Name": "gain" },
        { "Name": "mute" }
      ]
    }
  }
}

Remove controls from a change group via Named Controls. Returns a list of unknown controls after processing.

Parameters

Id : Change group ID.

Controls : Array of control names.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.Remove", 
  "params": {
    "Id": "my change group" 
    "Controls" : [
      "some control"
    ]
  }
}

Poll a change group.

Parameters

Id : Change group ID.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.Poll", 
  "params": {
    "Id": "my change group"
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1234,
  "result": {
    "Id": "my change group", 
    "Changes": [
      { // Named control return value 
      "Name": "some control", 
      "Value": ‐12
      "String": "‐12dB"
      },
      { // Named component return value 
      "Component": "My Component", 
      "Name": "gain",
      "Value": ‐12 
      "String": "‐12dB"
      }
    ]
  }
}

Destroy a change group.

Parameters

Id : Change group ID.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.Destroy", 
  "params": {
    "Id": "my change group"
  }
}

Invalidates a change group, which causes all controls to be resent.

Parameters

Id : Change group ID.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.Invalidate", 
  "params": {
    "Id": "my change group"
  }
}

Clears a change group, which removes all controls.

Parameters

Id : Change group ID.

Example

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.Clear", 
  "params": {
    "Id": "my change group"
  }
}

Set up automatic polling.

Parameters

Id : Change group ID.

Rate : The polling interval, in seconds.

Example

Configure automatic polling to receive a response every 5 seconds:

Copy 
{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "ChangeGroup.AutoPoll", 
  "params": {
    "Id": "my change group", 
    "Rate": 5
  }
}

Response

{
  "jsonrpc": "2.0",
  "id": 1234,
  "result": {
    "Id": "my change group", 
    "Changes": [
      { // Named control return value 
        "Name": "some control", 
        "Value": ‐12
        "String": "‐12dB"
      },
      { // Named component return value 
        "Component": "My Component", 
        "Name": "gain",
        "Value": ‐12 
        "String": "‐12dB"
      }
    ]
  }
}

Use the mixer control API methods to set mixer input and output parameters.

String Syntax

The mixer control API uses a string specification to determine to which inputs and outputs to apply changes. The syntax supports space- or comma-separated numbers, ranges of numbers, all numbers (*), and negation of a selection with the ! operator. For example:

*

everything

1 2 3

channels 1, 2, 3

1-6

channels 1 through 6

1-6 9

channels 1 through 6 and 9

1-3 5-9

channels 1 through 3 and 5 through 9

1-8 !3

channels 1 through 8 except 3

* !3-5

everything but 3 through 5

Methods

Set the crosspoint gain value for specified mixer inputs and outputs over an optional ramp time.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Outputs : String specification of mixer outputs. See String Syntax.

Value : The gain value to set.

Ramp : Ramp time to use for setting the gain value.

Example

Set all crosspoints on a mixer to -100dB over 5 seconds.

Copy 
{
  "jsonrpc": "2.0",
  "method": "Mixer.SetCrossPointGain", 
  "id": 1234,
  "params": {
    "Name": "Parade",
    "Inputs": "*",
    "Outputs": "*",
    "Value": ‐100.0,
    "Ramp": 5.0
  }
}

Set the crosspoint delay value for specified mixer inputs and outputs over an optional ramp time.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Outputs : String specification of mixer outputs. See String Syntax.

Value : The delay value to set.

Ramp : Ramp time to use for setting the delay value.

Enable or disable crosspoint muting for specified mixer inputs and outputs.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Outputs : String specification of mixer outputs. See String Syntax.

Value : The boolean mute value to set.

Enable or disable crosspoint solo for specified mixer inputs and outputs.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Outputs : String specification of mixer outputs. See String Syntax.

Value : The boolean solo value to set.

Set the gain value for specified mixer inputs over an optional ramp time.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Value : The input gain value to set.

Ramp : Ramp time to use for setting the input gain value.

Enable or disable muting for specified mixer inputs.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Value : The boolean input mute value to set.

Example

Mute inputs 4-6:

Copy 
{
  "jsonrpc": "2.0",
  "method": "Mixer.SetInputMute", 
  "params": {
    "Name": "Parade", 
    "Inputs": "4‐6", 
    "Value": true,
    "Ramp": 0.0
  },
  "id": 1234
}

Enable or disable solo for specified mixer inputs.

Parameters

Name : Name of the mixer.

Inputs : String specification of mixer inputs. See String Syntax.

Value : The boolean input solo value to set.

Set the gain value for specified mixer outputs over an optional ramp time.

Parameters

Name : Name of the mixer.

Outputs : String specification of mixer outputs. See String Syntax.

Value : The output gain value to set.

Ramp : Ramp time to use for setting the output gain value.

Enable or disable muting for specified mixer outputs.

Parameters

Name : Name of the mixer.

Outputs : String specification of mixer outputs. See String Syntax.

Value : The boolean output mute value to set.

Enable or disable muting for specified mixer cues.

Parameters

Name : Name of the mixer.

Cues : String specification of mixer cues.

Value : The boolean cue mute value to set.

Set the gain value for specified mixer cues over an optional ramp time.

Parameters

Name : Name of the mixer.

Cues : String specification of mixer cues.

Value : The cue gain value to set.

Ramp : Ramp time to use for setting the cue gain value.

Enable or disable cues for specified mixer inputs.

Parameters

Name : Name of the mixer.

Cues : String specification of mixer cues.

Inputs : String specification of mixer inputs. See String Syntax.

Value : The boolean cue enable value to set.

Enable or disable cue AFL (After Fader Level) for specified mixer inputs.

Parameters

Name : Name of the mixer.

Cues : String specification of mixer cues.

Inputs : String specification of mixer inputs. See String Syntax.

Value : The boolean cue AFL value to set.

Use the Loop Player control API methods to queue up file playback into a named Loop Player.

Note: In all Loop Player commands, there is a Log option that allows you to set it to true or false. This option enables Event Log logging for the command.

Start audio playback.

Parameters

Name : The name of the Loop Player.

StartTime : The time of day, in seconds, to start the job.

Files : Array of file specifications, including:

Name : Name of the file to play.

Mode : mono | stereo

Output : The Loop Player output number for playback.

Loop : If true, file playback loops.

RefID: If provided, a notification will be sent when a job has failed in some way. The error will be visible in the Event Log to make sense of what job failed. Additionally, the error will also be shown in the Q-SYS Remote Control Protocol (QRC).

Seek : The optional time, in seconds, to seek into each file before playback.

LoopPlayer.Start Example

Copy 
{
  "jsonrpc": "2.0",
  "method": "LoopPlayer.Start", 
  "params": {
    "Files": [
      {
        "Name": "Audio/mainloop.wav", 
        "Mode": "mono",
        "Output": 1
      }
    ],
    "Name": "test", 
    "StartTime": 62600, 
    "Loop": false, 
    "Log": true
  },
  "id": 1234
}

LoopPlayer.Error Example

Copy 
{
  "jsonrpc": "2.0",
  "method": "LoopPlayer.Error", 
  "params": { 
    "Error": "JobInPast", 
    "RefId": <Insert_id_from_LoopPlayer>, 
  }
}

Stop audio playback for specified outputs.

Parameters

Name : The name of the Loop Player.

Outputs : The Loop Player output numbers for which to stop playback.

Example

Copy 
{
  "jsonrpc": "2.0",
  "method": "LoopPlayer.Stop", 
  "params": {
    "Name": "test",
    "Outputs": [ 1, 3, 4 ], 
    "Log": true
  },
  "id": 1234
}

Cancel audio playback for specified outputs.

Parameters

Name : The name of the Loop Player.

Outputs : The Loop Player output numbers for which to stop playback.

Example

Copy 
{
  "jsonrpc": "2.0",
  "method": "LoopPlayer.Cancel", 
  "params": {
    "Name": "test",
    "Outputs": [ 1, 3, 4 ], 
    "Log": true
  },
  "id": 1234
}

Use these methods to load and save snapshots.

Load control settings from a specified snapshot bank and number with an optional ramp time.

Parameters

Name : String. The name of the snapshot bank from which to load the snapshot. This is the name given to the bank when it was created in Q-SYS Designer Software.

Bank : Integer. Identifies a snapshot within a snapshot bank. The range is 1 to the number of snapshots in the bank, inclusive.

Ramp : Double. Optional argument, in seconds, for specifying the ramp time when loading the snapshot.

Example

From a snapshot bank called "MySpecialBank", load control settings from snapshot # 7 with a ramp time of 8.5 seconds...

Copy 
{
  "jsonrpc": "2.0",
  "method": "Snapshot.Load", 
  "params": {
    "Name": "MySpecialBank",
    "Bank": 7, 
    "Ramp": 8.5
  },
  "id": 1234
}

Save control settings to a specified snapshot bank and number.

Parameters

Name : String. The name of the snapshot bank to which to save the snapshot. This is the name given to the bank when it was created in Q-SYS Designer Software.

Bank :  Integer. Identifies a snapshot within a snapshot bank. The range is 1 to the number of snapshots in the bank, inclusive.

Example

Save control settings to a snapshot bank called "MyVerySpecialBank" to snapshot # 4.

Copy 
{
  "jsonrpc": "2.0",
  "method": "Snapshot.Save", 
  "params": {
    "Name": "MyVerySpecialBank",
    "Bank": 4, 
  },
  "id": 1234
}

These codes can be returned as the code value in a JSON-RPC error object.
Code Details

-32700

Parse error. Invalid JSON was received by the server.

-32600

Invalid request. The JSON sent is not a valid Request object.

-32601

Method not found.

-32602

Invalid params.

-32603

Server error.

-32604

Core is on Standby. This code is returned when a QRC command is received while the Core is not the active Core in a redundant Core configuration.

2

Invalid Page Request ID

3

Bad Page Request - could not create the requested Page Request

4

Missing file

5

Change Groups exhausted

6

Unknown change croup

7

Unknown component name

8

Unknown control

9

Illegal mixer channel index

10

Logon required