RPC Method

For tasks that are not executed within the system real time engine, the device supports remote procedure calls (RPC). RPC are executed asynchronous to the audio and logic system. RPC work with HTTP/POST as well as WebSockets.

RPC structure

RPC use the rpc method and transmit their own call within the message payload. We do this to keep control API structure consistent and use the same endpoints for other request types.

RPC messages are therefore formatted like this:

{"method":"rpc", "payload":{"method":"", "params":{}} }

the payload object encapsulates the rpc itself with its available method and respective parameters
for HTTP/POST requests, make sure to also include a token
for WebSockets, you may include a msgID (optional)

Answers to RPC are formatted like this:

{"method":"rpc", "payload":{"method":"","params":{},"result":{}},"success":true}

Sample RPC

For example, to retrieve a list of available mixer snapshots, use the following RPC:

{
    "method": "rpc",
    "token": "xxx",
    "payload": {
        "method": "getsnapshotlist",
        "params": {
            "type": 2
        }
    }
}

This will be answered with a list like this

{
  "method": "rpc",
  "payload": {
    "method": "getsnapshotlist",
    "params": {
      "type": 2
    },
    "result": [
      {
        "factory": true,
        "id": "default",
        "name": "default",
        "readgroups": 0,
        "writegroups": 0
      },
      {
        "factory": false,
        "id": "d2b49cd3-5dea-4f9a-9fe1-382ea7b66fa0",
        "name": "test",
        "readgroups": 0,
        "writegroups": 0
      }
    ]
  },
  "success": true
}

tip

For the following documentation, we will only provide the payload object. When using RPC, make sure to encapsulate them like shown above.

Available RPCs

Snapshots

For snapshots (or presets), we differ between 3 types:

Type 1: Channel Snapshots (the channel processing and routing)
Type 2: Mixer Snapshots (the whole state of a mixer)
Type 3: Processing Snapshots (flex processing parameters)

Saving, deleting or modifying snapshots requires sufficient user rights within the API or on the frontend. The user rights are inherited from the user groups defined as a bitmask in readgroups and writegroups.

User group bitmasks

The Bitmasks used for readgroups and writegroups are coded like the following:

Group	Decimal Value	Binary Representation	Hexadecimal Representation
Group 1	1	`0b00000001`	`0x00000001`
Group 2	2	`0b00000010`	`0x00000002`
Group 3	4	`0b00000100`	`0x00000004`
Group 4	8	`0b00001000`	`0x00000008`
Group 5	16	`0b00010000`	`0x00000010`
Group 6	32	`0b00100000`	`0x00000020`
Group 7	64	`0b01000000`	`0x00000040`
Group 8	128	`0b10000000`	`0x00000080`

Examples

Group 1 only:
- Decimal: 1
- Binary: 0b00000001
- Hex: 0x00000001
Group 4 only:
- Decimal: 8
- Binary: 0b00001000
- Hex: 0x00000008
Group 8 only:
- Decimal: 128
- Binary: 0b10000000
- Hex: 0x00000080
Group 1, 4, and 8:
- Decimal: 137
- Binary: 0b10001001
- Hex: 0x00000089
All groups set:
- Decimal: 255
- Binary: 0b11111111
- Hex: 0x000000FF

getsnapshotlist

Get a list of available snapshots by type.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "getsnapshotlist",
    "params": {
        "type": 2,
        "mixer": 0
    }
  }
}

type (required)
mixer (optional): defines the virtual mixer for mixer snapshots. Default value 0 applied when not defined.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "getsnapshotlist",
    "params": {
      "type": 2
    },
    "result": [
      {
        "factory": false,
        "id": "[uuid]",
        "name": "morning",
        "readgroups": 0,
        "writegroups": 1
      },
      {
        "factory": false,
        "id": "[uuid]",
        "name": "evening",
        "readgroups": 0,
        "writegroups": 1
      }
    ]
  },
  "success": true
}

result: an array of all available snapshots by ID (UUID) and name.
factory: factory snapshots are predefined by DHD and can not be modified or overwritten.

loadsnapshot

Load a snapshot by ID.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "loadsnapshot",
    "params": {
        "mixer": 0,
        "fader": 1,
        "fp": 1,
        "id": "[uuid]"
    }
  }
}

mixer(optional, for mixer snapshots): defines the virtual mixer for mixer snapshots. Default value 0 applied when not defined.
fader (required for channel snapshots): the fader to load the snapshot to.
fp (required for flex processing snapshots): the flex processing to load the snapshot to.
id (required): the UUID of the Snapshot, as received from getsnapshotlist.

Response

{
  "method": "rpc",
  "payload": {
    "method": "loadsnapshot",
    "params": {
      "fader": 1,
      "id": "[uuid]"
    },
    "result": {}
  },
  "success": true
}

Special case: load snapshot 0 / default snapshot

To load the default snapshot for a virtual mixer, load it with the ID default.

info

Snapshot 0 can only be loaded and saved, not removed or modified.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "loadsnapshot",
    "params": {
        "type": 2,
        "mixer": 0,
        "id": "default"
    }
  }
}

savesnapshot

Save a snapshot.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "savesnapshot",
    "params": {
        "type": 1,
        "mixer": 0,
        "fader": 1,
        "fp": 1,
        "id": "[uuid]",
        "name":"snapname",
        "usergroups": 1
    }
  }
}

type (required)
mixer(optional, for mixer snapshots): defines the virtual mixer for mixer snapshots. Default value 0 applied when not defined.
fader (required for channel snapshots): the fader which the snapshot shall be created from.
fp (required for flex processing snapshots): the flex processing which the snapshot shall be created from.
id (required): the UUID of the Snapshot to overwrite, as received from getsnapshotlist. Leave blank to create a new snapshot.
name (optional): the name of the snapshot, which is displayed in the console. Date / time of creation used if not given.
writegroups (required): bitmask of the user group which has the snapshot rights to load/modify the snapshot. 1-255. 0 is not allowed as no user would have access to the snapshot.
readgroups (optional): bitmask of the user group which has the snapshot rights to load the snapshot. 0-255. 0 (default if not defined) means all users (even not logged in) have access to load the snapshot.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "savesnapshot",
    "params": {
      "fader": 1,
      "id": "",
      "name": "snapname",
      "readgroups": 0,
      "type": 1,
      "writegroups": 1
    },
    "result": {}
  },
  "success": true
}

Special case: save snapshot 0 / default snapshot

Save a new default snapshot for a virtual mixer with the ID default.

info

Snapshot 0 can only be loaded and saved, not removed or modified.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "savesnapshot",
    "params": {
        "type": 2,
        "mixer": 0,
        "id": "default",
        "writegroup": 1
    }
  }
}

modifysnapshot

Modify a snapshot's attributes, not his content. Attributes are snapshot name, readgroups or writegroups.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "modifysnapshot",
    "params": {
        "id": "[uuid]",
        "name": "snapname",
        "readgroups": 1,
        "writegroups": 1
    }
  }
}

id (required): the UUID of the Snapshot to modify, as received from getsnapshotlist.
name (optional): the name of the snapshot, which is displayed in the console. Date / time of creation used if not given. Minimum of 2 characters required.
writegroups (optional): bitmask of the user group which has the snapshot rights to load/modify the snapshot. 1-255. 0 is not allowed as no user would have access to the snapshot. Value not changed if not given.
readgroups (optional): bitmask of the user group which has the snapshot rights to load the snapshot. 0-255. 0 means all users (even not logged in) have access to load the snapshot. Value not changed if not given.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "modifysnapshot",
    "params": {
      "id": "[uuid]",
      "name": "snapname",
      "readgroups": 1,
      "writegroups": 1
    },
    "result": {}
  },
  "success": true
}

info

Default snapshot (snapshot 0) can not be modified via modifysnapshot

removesnapshot

Remove a snapshot.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "removesnapshot",
    "params": {
        "id": "[uuid]",
    }
  }
}

id (required): the UUID of the Snapshot to overwrite, as received from getsnapshotlist.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "removesnapshot",
    "params": {
      "id": "[uuid]"
    },
    "result": {}
  },
  "success": true
}

info

Default snapshot (snapshot 0) can not be deleted

getsnapshot

Get the content of a snapshot to download or store it. Provide the contents received in snapshotdata object via setsnapshot.

Request:

{
  "method": "rpc",
  "payload": {
      "method": "getsnapshot",
      "params": {
          "id": "[uuid]",
      }
  }
}

id (required): the UUID of the Snapshot to fetch, as received from getsnapshotlist.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "getsnapshot",
    "params": {
      "id": "[uuid]"
    },
    "result": {
      "snapshotdata": {
        // Snapshot contents
      }
    }
  },
  "success": true
}

info

To fetch a default snapshot (snapshot 0), use UUID default as well as mixer in the request, to receive the correct default snapshot fo a given mixer (if mixer is not given, mixer 0 will be used).

setsnapshot

Upload a snapshot file to the device, as received by getsnapshot. Can be on the same or on another console. It will be added as a new snapshot file or replace an existing one if the UUID already exists.

warning

The snapshot contents must be provided as fetched via getsnapshot - manipulation is not possible to protect the system. If a snapshot's content has been changed, it will be rejected by the system.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "setsnapshot",
    "params": {
      "snapshotdata": {
        // Snapshot contents
      }
    }
  }
}

snapshotdata (required): The snapshot contents as received from getsnapshot.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "setsnapshot",
    "params": {
      "snapshotdata": {
        // Snapshot contents
      }
    },
    "result": {}
  },
  "success": true
}

info

To set a default snapshot (snapshot 0), use UUID default as well as mixer in the request, to set the correct default snapshot fo a given mixer (if mixer is not given, mixer 0 will be used).

Set fading / fade to value

fadetovalue

This request allows you to fade to a specific fader value in a given time. The curve is always fader-linear.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "fadetovalue",
    "params": {
      "mixer":0, 
      "fader":2, 
      "time":1.5, 
      "value": 0
    }
  }
}

mixer (optional): The ID of the virtual mixer to act on. Mixer 0 by default.
fader (required): The fader ID which shall be faded.
fadetime (required): The time how long the fade should take until target value is reached. Range: 0..30 seconds, steps in 0.020s.
value (required): The value to fade to in dB. Range: -160..0..10.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "fadetovalue",
    "params": {
      "fader": 2,
      "mixer": 0,
      "time": 1.5,
      "value": 0
    },
    "result": {}
  },
  "success": true
}

Set channel names

setchannellabel

Set the channel label for a channel. This option is not fader based as in the real time API, but acts on the source (fader channel). The Fader Channel ID is unique within the device, so there is no mixer reference required.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "setchannellabel",
    "params": {
      "sourceid": 1,
      "label": "labeltext"
    }
  }
}

sourceid (required): the channel source ID (fader channel ID) of which the label shall be changed.
label (required): The label to set. Leave blank to reset to default value.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "setchannellabel",
    "params": {
      "label": "labeltext",
      "mixer": 0,
      "sourceid": 1
    },
    "result": {
      "label": "labeltext",
      "mixer": 0,
      "sourceid": 1
    }
  },
  "success": true
}

External lists (websocket only)

Using Control API, you can inject custom button lists into our TFT views, using the Remote Routing button list element on the console display.

warning

External lists RPC only work via websocket, not via HTTP/POST. Once the websocket / API connection of the client which registers the list is disconnected and no more clients are subscribed (registered) to the external list, the list will be deleted.

important

Using Remote Routing button list requires license 52-8583 XC/XS Core Control Networking

The basic concept is that the registerextlist command creates an external list which is then displayed in a Button List element within Views of the Device, either on the hardware or Views App. This type of lists are configured in Toolbox as a Remote Routing button list.

After the list was registered, all client can subscribe to events emitted by list interactions (push and release of a button). Also, all clients can set new contents to the list, there is no owner. Once all clients unsubscribed to the list or closed their websocket connection, the list is deleted.

registerextlist

Register a new list if it does not yet exist and automatically subscribe to it. If it already exists, just subscribe to it.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "registerextlist",
    "params": { 
      "list":1 
    }
  }
}

Response:

{ "method": "rpc", "msgID": "12", "payload": { "method": "registerextlist", "params": { "list": 1 }, "result": { "list": 1 } }, "success": true }

unregisterextlist

Unsubscribe to a list. If no more clients are subscribed to the list, the list will be deleted.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "unregisterextlist",
    "params": { 
      "list":1 
    }
  }
}

list (required): reference to the remote routing button list ID as defined in Toolbox.

setextlist

Set the contents of an external list.

Request:

{
  "method": "rpc",
  "payload": {
    "method": "setextlist",
    "params":  {
      "list":1, 
      "select":3, 
      "entries":[
        {"label":"Name1", "background": true, "color":"FF90FF", "pagination": false },
        {"label":"Name2", "background": true, "color":"000000", "pagination": true },
        {"label":"Name3", "background": true, "color":"000000", "pagination": false },
        {"label":"Name4", "background": true, "color":"000000", "pagination": false },
        {"label":"Name5", "background": true, "color":"000000", "pagination": true }
      ]
    }
  }
}

list (required): reference to the remote routing button list ID as defined in Toolbox.
select (optional): Directly jump to a specific list object's page.
entries (required): an array of entries (buttons) displayed in the list.
- label (required): The label text to display on the button.
- background (optional): if the color given shall act as font or as background color.
- color (optional): the font / background color.
- pagination (optional): force the list to show a new page after this button.

Response:

{
  "method": "rpc",
  "payload": {
    "method": "setextlist",
    "params": {
      "entries": [
        {
          "background": true,
          "color": "FF90FF",
          "label": "Name1",
          "pagination": false
        },
        {
          "background": true,
          "color": "000000",
          "label": "Name2",
          "pagination": true
        }
      ],
      "list": 1,
      "select": 4
    },
    "result": {
      "entries": [
        {
          "background": true,
          "color": "FF90FF",
          "label": "Name1",
          "pagination": false
        },
        {
          "background": true,
          "color": "000000",
          "label": "Name2",
          "pagination": true
        }
      ],
      "list": 1,
      "select": 4
    }
  },
  "success": true
}

event notifications

These events will be emitted to any open connection which has subscribed to the extlist.

Event:

{ 
  "method": "event", 
  "payload": { 
    "params": { 
      "entry": 0, 
      "list": 1, 
      "on": 1
    }, 
    "type": "extlistnotified" 
  } 
}

{ 
  "method": "event", 
  "payload": { 
    "params": { 
      "entry": 0, 
      "list": 1, 
      "on": 0
    }, 
    "type": "extlistnotified" 
  } 
}

entry: ID of the entry as given to the list element by setextlist.
list: ID of the extlist emitting the notification.
on: When the button is pushed, this value will be 1, if it is released, another event is emitted and results in 0 again.

Error Handling

RPC use the standard error handling mechanism of control API. Refer to REST API Usage documentation for a list of error codes and general behaviour.

RPC structure​

Sample RPC​

Available RPCs​

Snapshots​

User group bitmasks​

Examples​

getsnapshotlist​

loadsnapshot​

Special case: load snapshot 0 / default snapshot​

savesnapshot​

Special case: save snapshot 0 / default snapshot​

modifysnapshot​

removesnapshot​

getsnapshot​

setsnapshot​

Set fading / fade to value​

fadetovalue​

Set channel names​

setchannellabel​

External lists (websocket only)​

registerextlist​

unregisterextlist​

setextlist​

event notifications​

Error Handling​

RPC structure

Sample RPC

Available RPCs

Snapshots

User group bitmasks

Examples

getsnapshotlist

loadsnapshot

Special case: load snapshot 0 / default snapshot

savesnapshot

Special case: save snapshot 0 / default snapshot

modifysnapshot

removesnapshot

getsnapshot

setsnapshot

Set fading / fade to value

fadetovalue

Set channel names

setchannellabel

External lists (websocket only)

registerextlist

unregisterextlist

setextlist

event notifications

Error Handling