Q-SYS Remote Control (QRC)

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.

Connection Methods

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

Logon

Logs on to the system.

Parameters

User, Password

Example

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

NoOp

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

Parameters

None.

Example

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

Status Methods

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

EngineStatus

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.

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

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

StatusGet

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

Parameters

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

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

Response

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

Control Methods

Use these methods to get and set Named Control values.

Control.Get

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

{
  "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

{
  "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"
    }
  ]
}

Control.Set

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

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

Component Control Methods

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

Component.Get

Gets one or more controls and their values within a Named Component.

Parameters

Name : The name of the named component.

Controls : An array of control values.

Example

{
  "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
    }
    ]
  }
}

Component.Set

Set one or more controls for a single named component.

Parameters

Name : The name of the named component.

Controls : An array of control values.

Example 1: Set a single control

{
  "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

{
  "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
      }
    ]
  }
}

Component.GetComponents

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

Parameters

Example

{
  "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
}

Change Group Methods

Use these methods to manipulate and poll change groups.

ChangeGroup.AddControl

Add controls to a change group via Named Controls.

Parameters

Id : Change group ID.

Controls : Array of control names.

Example

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

ChangeGroup.AddComponentControl

Add controls to a change group via a Named Component.

Parameters

Id : Change group ID.

Component : Named Component name and array of controls.

Example

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

ChangeGroup.Remove

Remove controls from a change group via Named Controls.

Parameters

Id : Change group ID.

Controls : Array of control names.

Example

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

ChangeGroup.Poll

Poll a change group.

Parameters

Id : Change group ID.

Example

{
  "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"
      }
    ]
  }
}

ChangeGroup.Destroy

Destroy a change group.

Parameters

Id : Change group ID.

Example

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

ChangeGroup.Invalidate

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

Parameters

Id : Change group ID.

Example

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

ChangeGroup.Clear

Clears a change group, which removes all controls.

Parameters

Id : Change group ID.

Example

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

ChangeGroup.AutoPoll

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:

{
  "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"
      }
    ]
  }
}

Mixer Control Methods

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

Mixer.SetCrossPointGain

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.

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

Mixer.SetCrossPointDelay

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.

Mixer.SetCrossPointMute

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.

Mixer.SetCrossPointSolo

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.

Mixer.SetInputGain

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.

Mixer.SetInputMute

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:

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

Mixer.SetInputSolo

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.

Mixer.SetOutputGain

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.

Mixer.SetOutputMute

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.

Mixer.SetCueMute

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.

Mixer.SetCueGain

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.

Mixer.SetInputCueEnable

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.

Mixer.SetInputCueAfl

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.

Loop Player Control Methods

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

LoopPlayer.Start

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.

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

Example

{
  "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.Stop

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

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

LoopPlayer.Cancel

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

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

Error Code Reference

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.
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